====== WordPress Newsletter Plugin Documentation (v2.x branch) ======
===== Requirements =====
- [[http://wordpress.org/download/|WordPress 2.0.x or higher]] (Tested on WP v2.0.7)
- [[http://wordpress.org/download/|WordPress 2.1.x or higher]] (Tested on WP v2.1.2)
- [[http://wordpress.org/download/|WordPress 2.5.x or higher]] (Tested on WP v2.5.0)
===== New Installation =====
If you are upgrading, please see the [[wordpress_newsletter_plugin_v2#upgrading|Upgrading]] section
- Extract the st_newsletter folder from the ShiftThis-WP-Newsletter.zip file.
- Upload the st_newsletter folder into the following WordPress directory: /wp-content/plugins/
- Access the Plugin Panel in your Admin Panel, scroll down through the list of Plugins to find **ShiftThis | Newsletter** and click on the Activate link to turn the Plugin on.
- Click on the new Newsletter Tab in your Admin Menu.
- You may need to set your Options on the Newsletter Options page before some features will be available to you.
===== Upgrading =====
If you are upgrading from a previous version:
- Extract the st_newsletter folder from the latest .zip file available on the [[http://www.shiftthis.net/my-paid-plugins/|My Paid Plugins]] Page
- Upload the **st_newsletter** folder into the following WordPress directory: /wp-content/plugins/ overwriting the previous files.
- Go to Newsletter > Options and check for any new features and set them to your preference, then save.
- You are now officially upgraded!
===== Newsletter Options =====
Access via the Newsletter Tab > Options.
* **Minimum User Level** - This sets the minimum user level allowed to create and edit your newsletters. Default is set to Editor (7)
* **Default Newsletter Template:** - Sets the default template for your newsletter, this can be overridden within the Newsletter Editor.
* **Max Number of Side Boxes** - This sets the default amount of Side Box fields in your Newsletter Editor for the amount of Side Boxes needed. 1 should suffice for most templates, though more complex layouts may require the use of multiples.
* **Show Meta Box for Newsletter** - Enables the Meta Box textarea within the Newsletter Editor.
* **Ability to Include Pages** - Enables the ability to include pages as well as posts within the Newsletter Editor - these are added to the Include these Posts area.
* **Subscribers Per Page Amount** - sets the amount of Subscribers to show per page on the Subscribers tab.
* **Maximum Newsletters to show per page in the Newsletter archive** - This sets the amount of Newsletters to list per page on your Newsletter Archive Page via the ''newsletter_page()'' function.
* **Default Message when no Newsletters are available in the Archive** - This is the text displayed when there are no public newsletters available to view in the archive via the ''newsletter_page()'' function.
* **Optional Pre-Subject** - This text will appear before your newsletter title in the subject line. Can also be left blank.
* **Flood Protection Batch** - Set the quantity of emails to send in a batch - Gmail's Max is 50.
* **Flood Protection Pause** - Set the time to wait between batches.
* **Images** - Two settings available for handling images within your newsletter:
* **Load From Site** - This will load all image via http from the email client of your users. This allows users to choose whether to view images or not and will lower the size of your newsletter email for faster delivery and less bandwidth usage.
* **Embed Local Images into Email** - This will embed all images located locally within your site to the email as an attachment. This will force the display of all local images for your newsletter but will also raise the size of your newsletter email which may result in slower delivery and higher bandwidth usage.
* **Subscribe Page** - Select the page containing your subscription form (''st_mailinglist_subscribe()'') so we know where to send subscribers who want to change their options.
* **Subscribe Form URI Override** - Set the action url of the Subscription form if the automated setting causes problems.
* **Show Categories** - Show Category Selection on Subscribe Page (generally used to hide the categories when you only use 1 category)
* **Subscribe Fields** - These are the fields you wish to display with your subscription form. You may add more fields using the **Add New Field** button and setting the Field Name in the empty text box and selecting whether it should be required or not. You can remove fields using the X button in front of the custom field. The Email field is not removable.
* **Required Text** - HTML text to appear next to any required fields to indicate that they are required.
* **Visual Editor** - Select the visual editor to use when creating your newsletters. Options include [[http://www.tamba2.org.uk/wordpress/quicktags/|QuickTags]], [[http://tinymce.moxiecode.com/|TinyMCE]] or [[http://www.fckeditor.net/|FCK Editor]].
* **Disable WordPress Filters** - This will disable Wordpress's "the_content" filter which automatically adds formatting tags to your Newsletter content.
* **Slash Fix** - This will switch the directory slash for the admin plugin within your WP Admin. This is generally only required when you are testing the plugin locally on a Windows Server and receiving "Fatal error: Cannot redeclare...".
* **Error Log** - This will display an error log upon sending for troubleshooting sending issues.
* **Send From Email** - This is the email you wish your newsletter to be sent from.
* **Send From Name** - This is the name you wish to use to send your newsletter from.
* **Send To Name** - This is the email name you wish to send to - you can use user information fields here as well or a custom name.
* **Bounce Address** - If an email bounces a notice will be sent to this address. You may want to set-up a separate account for bounce detection.
* **Send Using** - Select whether to send you newsletters via Swift SendMail (recommended) or Swift SMTP (slower) or Native Mail (not recommended). Note: Only your newsletters will use this setting, all subscription related emails use WordPress's default ''wp_mail'' function for sending.
* **SMTP Settings** - Only necessary if Swift SMTP is selected in your Send Using setting.
* Server - set to your email SMTP server setting (smtp.yourhost.com).
* Username - set to the username used to login to your SMTP account.
* Password - set to the password used to login to your SMTP account.
* Should we use TLS or SSL? - If your server required TLS or SSL select the appropriate setting, otherwise set to No.
* Port - Enter the port needed. (Gmail SMTP uses Port 465.)
===== Subscription Text =====
Access via Newsletter Tab > Subscription Text
=== Dynamic Tags ===
The subscription form text and emails can be customized from here. There are a number of Dynamic Tags available for use here.
* ''{presubject}'' - Displays the Pre-Subject set in the options above
* ''{list_name}'' - The Mailing List Name you set below
* ''{verify_link}'' - Displays the verification link needed to enable the subscription. This needs to be included somewhere in the Opt-In Message field or you won't get any subscribers!
* ''{resend_link}'' - Displays the link needed to resend verification email. This can be used only in Duplicate Address (unverified) field
* ''{retrieve_account}'' - Link that will send account management email. This can be used only in Duplicate Address (verified)
* ''{account_link}'' - Link to the subscription account management page. This can be used only in Retrieve Account Link Message
You will also be able to your custom fields here as well. If you have a custom field named **First Name**, this can be used with the dynamic tag of ''{firstname}''.
=== Text Fields ===
* **Mailing List Name** - The Name of your Mailing List.
* **Opt-In Subject** - Subject sent when user subscribes to your newsletter.
* **Opt-In Message** - Message sent when user subscribes to your newsletter. Note: The ''{verify_link}'' tag is required in this field, this is the only way for the subscriber to verify his address.
* **Success Message** - Message displayed on your site upon initial subscription.
* **Duplicate Address (unverified)** - Message displayed on your site if the email address has already been subscribed previously but has not yet been verified. Note: The ''{resend_link}'' tag is required in this field, this is the only way for the subscriber to resend the verification email to his address.
* **Duplicate Address (verified)** - Message displayed on your site if the email address has already been subscribed previously and verified.
* **Retrieve Account Link Message** - Message used to send account access link to subscriber. This sends him the link that is also included at the bottom of your newsletters for changing subscription settings or to unsubscribe.
===== Subscription Form =====
==== Widgets ====
If you have the [[http://automattic.com/code/widgets/|WordPress Widgets Plugin]] installed, you can use the included //ShiftThis Subscribe// Sidebar Widget to add the subscription form to your blog. Just access the Presentation Tab > Sidebar Widgets page and drag the //ShiftThis Subscribe// box from the Available Widgets into the Sidebar box. See the [[http://automattic.com/code/widgets/use/|How to Use Widgets]] page for more information on Widgets.
==== Manual Procedure ====
Insert '''' into your theme template in either your themes sidebar template or a [[http://codex.wordpress.org/Pages#Page_Templates|page template]] to display the subscribe form. This form can be styled to your needs easily within your themes styles.css stylesheet. You can also use a PHP Plugin such as [[http://bluesome.net/post/2005/08/18/50/|Exec-PHP]] to allow you to place '''' within a page or post via the **Write Panel**. 'Subscribe' is the default button text. You can replace the 'Subscribe' text with anything you like.
=== Creating a Page Template ===
To create a page template that includes the Subscribe Form, you will need to be using a theme that includes the page.php file. If your theme does not include this file, you will need to create it (See [[http://codex.wordpress.org/Pages#Page_Templates|WordPress Page templates]]).
- In your current themes folder, duplicate your page.php file and rename it subscribe.php
- Open subscribe.php and at the very top add the following code:Read the rest of this page »'); ?>
- Place the following code above or below this:
"fakeemail@mail.com"
"fakeemail2@mail.com"
"fakeemail3@mail.com"
"fakeemail4@mail.com"
"fakeemail5@mail.com"
"fakeemail6@mail.com"
"fakeemail7@mail.com"
"fakeemail8@mail.com"
==== Import/Export Requirements ====
To import the CSV file and read it’s contents, the plugin requires the following:
* Within your Options Panel under Miscellaneous, make sure your uploads folder is writable. This is where the csv file is temporarily uploaded to for importing.
* You will need fopen enabled to read the contents of the csv file and import.
==== Import Instructions ====
- Click the Browse button and select your CSV file of values to import and click the **Import File** Button. This uploads the file to the server for reading.
- You should now have the **Match Fields for Importing** area visible.
* **Import First Row** - Defaults to Yes, but if your CSV file contains Field Headings in the first row then select No.
* **Email** - Select the Email value from the drop down.
* **Extras** - Select the Extras value from the drop down
* **Categories** - Select the Categories value from the drop down.
* Continue for the rest of the values you may need. Leave unneeded fields as N/A.
-Click the **Import Values** button.
Your subscribers should now be imported. If you had any problems or errors while importing, make sure your CSV file is setup correctly, try using the included example files as a test.
===== Swift Test =====
Access via the Newsletter Tab > Swift Test.
This plugin is currently using [[http://www.swiftmailer.org/|Swift Mailer v3.0.5]]. Swift is a fully OOP Library for sending e-mails from PHP websites and applications. It does not rely on PHP's native mail() function which is known for using high server resources when sending multiple emails. Instead, Swift communicates directly with an SMTP server or a MTA binary to send mail quickly and efficiently.
Before releasing your Newsletter upon the world, it's recommended to make sure that your Swift setup is working properly. Below you will find a number of simple test emails to run for your website. **You will need to edit the file 'st_newsletter/Swift/tests/TestConfiguration.php' and fill with the appropriate values.** This will eventually use your Newsletter Options settings. Try using the **Swift Sendmail** option first as it is the quickest and easiest way to send email. If your server does not support the Sendmail Option, use the SMTP option.
===== Localization (Language) =====
To localize your plugin to your own language, do the following:
=== Create A New Language File ===
{{po_edit_windows.jpg?150}}
- Open your wp-config.php file from your WordPress Installation and change - define ('WPLANG', ''); - to define ('WPLANG', 'en_CA'); where en is the language (en=English) and CA is the Country Code (CA=Canada) for your region. Save and upload back to your server.
- Download and install poEdit (http://sourceforge.net/project/showfiles.php?group_id=27043&package_id=18746&release_id=459538)
- Run poEdit and open the st_newsletter/locale/WP-Newsletter.po file.
- To make changes to the text, select the line, then in the bottom-left box translate the text to your language. The top-left box is the original text, and the two right-side boxes are for comments only.
- Once you have made all the translation's neccessary, choose File > Save As.. and name your file 'stnl-en_CA' except replace "en" with your language code, and "CA" with your Country Code that you set in step 1. Save the file in the same locale directory. (You may need to save twice to generate the .mo file needed).
- Upload the stnl-[language]_[COUNTRY].mo file to your server to finish the translation.