WordPress.org
Get WordPress

Plugin Directory

Changeset 777053


Ignore:
Timestamp:
09/23/2013 02:40:57 AM (13 years ago)
Author:
codebykat
Message:

added screenshots, contextual help and expanded Readme

Location:
post-by-email/trunk
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • post-by-email/trunk/class-post-by-email-admin.php

    r777051 r777053  
    2424        return self::$instance;
    2525    }
     26
     27    /**
     28    * Help tabs for the settings page.
     29    *
     30    * @since    1.0.4
     31    */
     32    public static $help_tabs = array(
     33        'post-by-email' => array(
     34            'title'   => 'Post By Email',
     35            'content' => 'Post By Email allows you to send your WordPress site an email with the content of your post. You must set up a special-purpose e-mail account with IMAP or POP3 access to use this, and any mail received at this address will be posted, so it&#8217;s a good idea to keep this address very secret.</p><p>For detailed installation and configuration instructions, see the links to the right.',
     36        ),
     37        'mailserver' => array(
     38                'title'   => 'Mailbox Settings',
     39                'content' => 'If you&#8217;re not sure what to put here and the defaults don&#8217;t work, ask your email provider for the correct settings.  Here are links to the settings for some common email providers:<li><a href="https://support.google.com/mail/troubleshooter/1668960?hl=en">Gmail</a></li><li><a href="http://help.yahoo.com/kb/index?page=content&id=SLN4075">Yahoo</a></li><li><a href="http://windows.microsoft.com/en-ca/windows/outlook/send-receive-from-app">Outlook.com</a></li>Note that you might also have to enable POP/IMAP access via your email provider.',
     40        ),
     41        'security' => array(
     42                'title'  => 'Security',
     43                'content' => 'If you&#8217ve set a PIN for authentication, you will need to specify it somewhere in your email message using the following shortcode:<p><kbd>[pin abc123]</kbd><p>(Replace abc123 with the PIN you chose.)</p><p>Mail that doe not contain this PIN will be discarded!',
     44        ),
     45        'shortcodes' => array(
     46                'title'    => 'Shortcodes',
     47                'content'  => 'You can specify categories, tags and custom taxonomy terms in your email by including shortcodes.  If no categories or tags are specified, the post will be created in the default category.</p><p>You can also include a gallery shortcode to specify gallery options for any attachments.</p><p>Shortcode examples can be found on the <a href="http://wordpress.org/plugins/post-by-email/">plugin page</a>.',
     48        ),
     49    );
    2650
    2751    /**
    … …  
    198222            array( $this, 'display_plugin_admin_page' )
    199223        );
    200         WP_Screen::get($this->plugin_screen_hook_suffix)->add_help_tab( array(
    201                 'id'      => 'options-postemail',
    202                 'title'   => __( 'Post Via Email' ),
    203                 'content' => '<p>' . __( 'Post via email settings allow you to send your WordPress install an email with the content of your post. You must set up a secret e-mail account with POP3 access to use this, and any mail received at this address will be posted, so it&#8217;s a good idea to keep this address very secret.', 'post-by-email' ) . '</p>',
    204             )
     224        $screen = WP_Screen::get( $this->plugin_screen_hook_suffix);
     225        foreach ( self::$help_tabs as $id => $data ) {
     226            $screen->add_help_tab( array(
     227                    'id'       => $id,
     228                    'title'    => __( $data['title'], 'post-by-email' ),
     229                    'content'  => '',
     230                    'callback' => array( $this, 'show_help_tabs' )
     231                )
     232            );
     233        }
     234        $screen->set_help_sidebar(
     235            '<p><strong>' . __( 'For more information:', 'post-by-email' ) . '</strong></p>' .
     236            '<p>' . __( '<a href="http://wordpress.org/plugins/post-by-email/installation" target="_blank">Installation</a>', 'post-by-email' ) . '</p>' .
     237            '<p>' . __( '<a href="http://wordpress.org/plugins/post-by-email/" target="_blank">Usage</a>', 'post-by-email' ) . '</p>' .
     238            '<p>' . __( '<a href="http://wordpress.org/support/plugin/post-by-email" target="_blank">Support Forums</a>', 'post-by-email' ) . '</p>'
    205239        );
     240    }
     241
     242    /**
     243    * Prints out the content for the contextual help tabs.
     244    *
     245    * @since    1.0.4
     246    */
     247    public function show_help_tabs( $screen, $tab ) {
     248        printf(
     249                '<p>%s</p>',
     250                __( $tab['callback'][0]::$help_tabs[ $tab['id'] ]['content'], 'post-by-email' )
     251            );
    206252    }
    207253

  • post-by-email/trunk/readme.md

    r773033 r777053  
    1111## Description ##
    1212
    13 **Warning:** This plugin is currently a very early beta!  Use at your own risk and please report any bugs, either on the [WordPress Support forums](http://wordpress.org/support/plugin/post-by-email) or via the [Github issues page](https://github.com/codebykat/wp-post-by-email/issues).
     13**Warning:** This plugin is currently in beta!  Use at your own risk and please report any bugs, either on the [WordPress Support forums](http://wordpress.org/support/plugin/post-by-email) or via the [Github issues page](https://github.com/codebykat/wp-post-by-email/issues).
    1414
    15 Any new messages sent to the configured email address will be posted to the blog.  This plugin replaces the functionality that used to live in core.
     15Any new messages sent to the configured email address will be posted to the blog.  This plugin replaces the functionality that used to live in WordPress core.
     16
     17Once an email has been successfully posted to the blog, it can either be marked as read (IMAP servers only) or deleted from the mailbox.
     18
     19Updates on the project can be found on the [Make WordPress Core blog](http://make.wordpress.org/core/tag/post-by-email/).
     20
     21
     22**Features**
     23* Supports IMAP or POP3 servers, with or without SSL
     24* Optional PIN-based authentication guards against email spoofing
     25* Uses WordPress's built-in roles to manage which users can post
     26* Set categories, tags and custom taxonomies by including shortcodes in your email
     27* Email attachments will automatically be added to the post's gallery
     28* Emails from unauthorized users can be either set as pending or discarded
     29
     30### Post Authors and Security ###
    1631
    1732The "From" address is matched to WordPress users in the database to determine the post's author.  If the author doesn't have an account or isn't allowed to publish posts, the post status will be set to "pending".
    1833
    19 Once an email has been successfully posted to the blog, it will either be marked as read (IMAP servers only) or deleted from the mailbox.
     34By default, any users in the Author, Editor or Administrator roles are able to publish posts.  Use the Users menu item in the admin dashboard to view and manage which users have this capability.  For more information on the WordPress permissions system, see <a href="http://codex.wordpress.org/Roles_and_Capabilities">Codex: Roles and Capabilities</a>.
    2035
    21 You can set categories, tags and custom taxonomy terms on your posts by including shortcodes in your email.  These should be space-separated.  Use slugs for tags (and non-hierarchical taxonomies) and either slugs or IDs for categories (/ hierarchical taxonomies).  Terms that do not yet exist will be created.  Examples:
    22 `[category posted-by-email another-category]`
     36### Shortcodes ###
     37
     38By default, emailed posts will be placed in the default category configured in the settings.
     39
     40You can also set the categories, tags and custom taxonomy terms on your posts by including shortcodes in your email.  These should be space-separated.  Use slugs for tags (and non-hierarchical taxonomies) and either slugs or IDs for categories (/ hierarchical taxonomies).  Terms that do not yet exist will be created.  Examples:
     41
     42**Categories:** Use either slugs or IDs. 
     43`[category posted-by-email another-category]` 
     44`[category 14]`
     45
     46**Tags:** Use slugs. 
    2347`[tag cool-stuff]`
    24 `[category 14]`
    25 `[custom-taxonomy-name thing1 thing2]`
     48
     49**Custom Taxonomies:** Use slugs for non-hierarchical taxonomies, and IDs for hierarchical. 
     50`[custom-taxonomy-name thing1 thing2]` 
    2651`[another-custom-taxonomy 2 3 5]`
    2752
    28 Updates on the project can be found on the [Make WordPress Core blog](http://make.wordpress.org/core/tag/post-by-email/).
     53### Attachments ###
     54
     55Any files attached to an email will be uploaded to the Media Library and added to the post as a gallery.  You can specify gallery options, or its location within the post, by including a <a href="http://codex.wordpress.org/Gallery_Shortcode">gallery shortcode</a> in your email.  If no gallery shortcode exists, it will be added to the end of the post.
     56
    2957
    3058## Installation ##
    3159
    32601. See [Installing Plugins](http://codex.wordpress.org/Managing_Plugins#Installing_Plugins).
     611. Set up an email address that will be used specifically to receive messages for your blog.
     621. Make sure your email service is configured to allow external connections via POP3 or IMAP.
    33631. Activate the plugin through the 'Plugins' menu.
    34 1. Configure mailbox information under plugin settings.
     641. Configure mailbox information under Tools->Post By Email.
     65
     66### Instructions for specific email services ###
     67
     68- Gmail: <a href="https://support.google.com/mail/troubleshooter/1668960?hl=en">This page</a> will walk you through enabling IMAP or POP3 access.  When prompted to select an email client for configuration instructions, select "Other" to view the settings. 
     69
     70- Yahoo! Mail: Use these <a href="http://help.yahoo.com/kb/index?page=content&id=SLN4075">IMAP settings</a>; IMAP access should be enabled by default.  Mail Plus subscribers can also use these <a href="http://help.yahoo.com/kb/index?locale=en_US&y=PROD_MAIL_ML&page=content&id=SLN4724">POP3 settings</a>. 
     71
     72- Outlook.com (Hotmail) settings and instructions can be found on <a href="http://windows.microsoft.com/en-ca/windows/outlook/send-receive-from-app">this page</a>.
    3573
    3674
    37 ## Tests ##
     75## Frequently Asked Questions ##
    3876
    39 Like WordPress Core, this plugin includes unit tests written in PHPUnit.
     77### What timestamp will be used for posts? ###
     78Posts will be backdated to use the date and time they were received by the mailserver, NOT the time they were imported by the plugin.
    4079
    41 To run the tests:
     80### Will messages show up on my blog as soon as I send them? ###
     81No, emails are not "forwarded" to your blog.  Just like any third-party mail client, Post By Email has to check for new messages, and will only do this once per hour (or when you click the "Check Now" button in the settings).  In addition, because of how WordPress' task scheduling (wp_cron) works, this check will only be triggered when a page on your blog has been loaded.  There is also sometimes a delay between when messages are sent and when they show up in the mailbox, especially with POP3 access.
     82
     83### I found a bug! ###
     84Oh no!  I would like to know as much as possible about it so that I can fix it.  For the information to include with a bug report, please see <a href="#reporting-bugs">Reporting Bugs</a>.
     85
     86### What does the error "Bad tagged response" mean? ###
     87This probably means you're trying to connect to a POP3 server over the IMAP port, or vice versa.  Double-check your server URL, protocol and port number and try again.
     88
     89
     90## Screenshots ##
     91###1. Main settings page###
     92![Main settings page](http://s.wordpress.org/extend/plugins/post-by-email/screenshot-1.png)
     93
     94###2. The activity log###
     95![The activity log](http://s.wordpress.org/extend/plugins/post-by-email/screenshot-2.png)
     96
     97
     98
     99## Testing ##
     100
     101### Automated Tests ###
     102
     103Like WordPress Core, this plugin includes automated unit tests written in PHPUnit.
     104
     105To run the unit tests:
    42106
    431071. Set up the WordPress testing library as described in [Handbook: Automated Testing](http://make.wordpress.org/core/handbook/automated-testing/).  You can also do this [using WP-CLI](http://wp-cli.org/blog/plugin-unit-tests.html). 
    441081. From the plugin directory, run `WP_TESTS_DIR=/path/to/WordPress/test/install phpunit`
    45109
     110### Manual Testing ###
     111
     1121. Set up a test email address (services such as Gmail work great for this) and enable IMAP or POP3 access.  (Refer to <a href="http://wordpress.org/plugins/post-by-email/installation/">Installation</a> for detailed instructions.)
     1131. Verify that you are using the correct mailbox settings by using a third-party email client, such as Outlook or OSX Mail.app, to connect to your test mailbox.
     1141. Enter those settings into the Post By Email settings and save them.
     1151. Navigate to the "Activity Log" tab and press the "Check Now" button.  When the page reloads, you should see a new entry in the log file describing the results of the mail check.
     116
     117**Caveat** 
     118There is sometimes a delay between sending an email and having it show up in the mailbox, especially with POP3.  If you're using IMAP, you can connect using a third-party mail client to verify that messages have been received, then mark them as unread so Post By Email will pick them up.
     119
     120
     121## Reporting Bugs ##
     122
     123Before reporting a bug, make sure you've updated the plugin to the latest version.
     124
     125Then, provide as much of the following information as possible:
     126
     1271. WordPress version (e.g. 3.6.x).
     1281. Plugin version (e.g. 1.0.3).
     1291. PHP version (e.g. 5.2.x or 5.3.x).
     1301. Your mailbox settings (URL, protocol, port and whether SSL is enabled; not your login and password).
     1311. Any error messages displayed (it might help to <a href="http://codex.wordpress.org/WP_DEBUG">enable WP_DEBUG</a> in your wp-config.php).
     1321. If the issue is related to a specific email, the full email, including headers.  Feel free to replace any personal information with dummy text (such as "sender@example.com").  <a href="https://support.google.com/groups/answer/75960?hl=en">This link</a> has instructions for viewing full message headers in Gmail, Outlook and Yahoo.
     133
     134
    46135## Changelog ##
     136
     137### 1.0.4 ###
     138* Added screenshots, expanded Readme and contextual help.
     139* Added support for user-included gallery shortcode (allows use of WP's gallery options).
     140* Added warning when checking email before changed settings have been saved.
     141* Code style fixes as per http://gsoc.trac.wordpress.org/ticket/377
     142* Fixed https://github.com/codebykat/wp-post-by-email/issues/3
    47143
    48144### 1.0.3 ###

  • post-by-email/trunk/readme.txt

    r773033 r777053  
    1111== Description ==
    1212
    13 **Warning:** This plugin is currently a very early beta!  Use at your own risk and please report any bugs, either on the [WordPress Support forums](http://wordpress.org/support/plugin/post-by-email) or via the [Github issues page](https://github.com/codebykat/wp-post-by-email/issues).
     13**Warning:** This plugin is currently in beta!  Use at your own risk and please report any bugs, either on the [WordPress Support forums](http://wordpress.org/support/plugin/post-by-email) or via the [Github issues page](https://github.com/codebykat/wp-post-by-email/issues).
    1414
    15 Any new messages sent to the configured email address will be posted to the blog.  This plugin replaces the functionality that used to live in core.
     15Any new messages sent to the configured email address will be posted to the blog.  This plugin replaces the functionality that used to live in WordPress core.
     16
     17Once an email has been successfully posted to the blog, it can either be marked as read (IMAP servers only) or deleted from the mailbox.
     18
     19Updates on the project can be found on the [Make WordPress Core blog](http://make.wordpress.org/core/tag/post-by-email/).
     20
     21
     22**Features**
     23* Supports IMAP or POP3 servers, with or without SSL
     24* Optional PIN-based authentication guards against email spoofing
     25* Uses WordPress's built-in roles to manage which users can post
     26* Set categories, tags and custom taxonomies by including shortcodes in your email
     27* Email attachments will automatically be added to the post's gallery
     28* Emails from unauthorized users can be either set as pending or discarded
     29
     30### Post Authors and Security ###
    1631
    1732The "From" address is matched to WordPress users in the database to determine the post's author.  If the author doesn't have an account or isn't allowed to publish posts, the post status will be set to "pending".
    1833
    19 Once an email has been successfully posted to the blog, it will either be marked as read (IMAP servers only) or deleted from the mailbox.
     34By default, any users in the Author, Editor or Administrator roles are able to publish posts.  Use the Users menu item in the admin dashboard to view and manage which users have this capability.  For more information on the WordPress permissions system, see <a href="http://codex.wordpress.org/Roles_and_Capabilities">Codex: Roles and Capabilities</a>.
    2035
    21 You can set categories, tags and custom taxonomy terms on your posts by including shortcodes in your email.  These should be space-separated.  Use slugs for tags (and non-hierarchical taxonomies) and either slugs or IDs for categories (/ hierarchical taxonomies).  Terms that do not yet exist will be created.  Examples:
    22 `[category posted-by-email another-category]`
     36### Shortcodes ###
     37
     38By default, emailed posts will be placed in the default category configured in the settings.
     39
     40You can also set the categories, tags and custom taxonomy terms on your posts by including shortcodes in your email.  These should be space-separated.  Use slugs for tags (and non-hierarchical taxonomies) and either slugs or IDs for categories (/ hierarchical taxonomies).  Terms that do not yet exist will be created.  Examples:
     41
     42**Categories:** Use either slugs or IDs. 
     43`[category posted-by-email another-category]` 
     44`[category 14]`
     45
     46**Tags:** Use slugs. 
    2347`[tag cool-stuff]`
    24 `[category 14]`
    25 `[custom-taxonomy-name thing1 thing2]`
     48
     49**Custom Taxonomies:** Use slugs for non-hierarchical taxonomies, and IDs for hierarchical. 
     50`[custom-taxonomy-name thing1 thing2]` 
    2651`[another-custom-taxonomy 2 3 5]`
    2752
    28 Updates on the project can be found on the [Make WordPress Core blog](http://make.wordpress.org/core/tag/post-by-email/).
     53### Attachments ###
     54
     55Any files attached to an email will be uploaded to the Media Library and added to the post as a gallery.  You can specify gallery options, or its location within the post, by including a <a href="http://codex.wordpress.org/Gallery_Shortcode">gallery shortcode</a> in your email.  If no gallery shortcode exists, it will be added to the end of the post.
     56
    2957
    3058== Installation ==
    3159
    32601. See [Installing Plugins](http://codex.wordpress.org/Managing_Plugins#Installing_Plugins).
     611. Set up an email address that will be used specifically to receive messages for your blog.
     621. Make sure your email service is configured to allow external connections via POP3 or IMAP.
    33631. Activate the plugin through the 'Plugins' menu.
    34 1. Configure mailbox information under plugin settings.
     641. Configure mailbox information under Tools->Post By Email.
     65
     66### Instructions for specific email services ###
     67
     68- Gmail: <a href="https://support.google.com/mail/troubleshooter/1668960?hl=en">This page</a> will walk you through enabling IMAP or POP3 access.  When prompted to select an email client for configuration instructions, select "Other" to view the settings.
     69
     70- Yahoo! Mail: Use these <a href="http://help.yahoo.com/kb/index?page=content&id=SLN4075">IMAP settings</a>; IMAP access should be enabled by default.  Mail Plus subscribers can also use these <a href="http://help.yahoo.com/kb/index?locale=en_US&y=PROD_MAIL_ML&page=content&id=SLN4724">POP3 settings</a>.
     71
     72- Outlook.com (Hotmail) settings and instructions can be found on <a href="http://windows.microsoft.com/en-ca/windows/outlook/send-receive-from-app">this page</a>.
    3573
    3674
    37 == Tests ==
     75== Frequently Asked Questions ==
    3876
    39 Like WordPress Core, this plugin includes unit tests written in PHPUnit.
     77= What timestamp will be used for posts? =
     78Posts will be backdated to use the date and time they were received by the mailserver, NOT the time they were imported by the plugin.
    4079
    41 To run the tests:
     80= Will messages show up on my blog as soon as I send them? =
     81No, emails are not "forwarded" to your blog.  Just like any third-party mail client, Post By Email has to check for new messages, and will only do this once per hour (or when you click the "Check Now" button in the settings).  In addition, because of how WordPress' task scheduling (wp_cron) works, this check will only be triggered when a page on your blog has been loaded.  There is also sometimes a delay between when messages are sent and when they show up in the mailbox, especially with POP3 access.
     82
     83= I found a bug! =
     84Oh no!  I would like to know as much as possible about it so that I can fix it.  For the information to include with a bug report, please see the Reporting Bugs section in <a href="http://wordpress.org/plugins/post-by-email/other_notes/">Other Notes</a>.
     85
     86= What does the error "Bad tagged response" mean? =
     87This probably means you're trying to connect to a POP3 server over the IMAP port, or vice versa.  Double-check your server URL, protocol and port number and try again.
     88
     89
     90== Screenshots ==
     911. Main settings page
     921. The activity log
     93
     94
     95== Testing ==
     96
     97### Automated Tests ###
     98
     99Like WordPress Core, this plugin includes automated unit tests written in PHPUnit.
     100
     101To run the unit tests:
    42102
    431031. Set up the WordPress testing library as described in [Handbook: Automated Testing](http://make.wordpress.org/core/handbook/automated-testing/).  You can also do this [using WP-CLI](http://wp-cli.org/blog/plugin-unit-tests.html).
    441041. From the plugin directory, run `WP_TESTS_DIR=/path/to/WordPress/test/install phpunit`
    45105
     106### Manual Testing ###
     107
     1081. Set up a test email address (services such as Gmail work great for this) and enable IMAP or POP3 access.  (Refer to <a href="http://wordpress.org/plugins/post-by-email/installation/">Installation</a> for detailed instructions.)
     1091. Verify that you are using the correct mailbox settings by using a third-party email client, such as Outlook or OSX Mail.app, to connect to your test mailbox.
     1101. Enter those settings into the Post By Email settings and save them.
     1111. Navigate to the "Activity Log" tab and press the "Check Now" button.  When the page reloads, you should see a new entry in the log file describing the results of the mail check.
     112
     113**Caveat** 
     114There is sometimes a delay between sending an email and having it show up in the mailbox, especially with POP3.  If you're using IMAP, you can connect using a third-party mail client to verify that messages have been received, then mark them as unread so Post By Email will pick them up.
     115
     116
     117== Reporting Bugs ==
     118
     119Before reporting a bug, make sure you've updated the plugin to the latest version.
     120
     121Then, provide as much of the following information as possible:
     122
     1231. WordPress version (e.g. 3.6.x).
     1241. Plugin version (e.g. 1.0.3).
     1251. PHP version (e.g. 5.2.x or 5.3.x).
     1261. Your mailbox settings (URL, protocol, port and whether SSL is enabled; not your login and password).
     1271. Any error messages displayed (it might help to <a href="http://codex.wordpress.org/WP_DEBUG">enable WP_DEBUG</a> in your wp-config.php).
     1281. If the issue is related to a specific email, the full email, including headers.  Feel free to replace any personal information with dummy text (such as "sender@example.com").  <a href="https://support.google.com/groups/answer/75960?hl=en">This link</a> has instructions for viewing full message headers in Gmail, Outlook and Yahoo.
     129
     130
    46131== Changelog ==
     132
     133= 1.0.4 =
     134* Added screenshots, expanded Readme and contextual help.
     135* Added support for user-included gallery shortcode (allows use of WP's gallery options).
     136* Added warning when checking email before changed settings have been saved.
     137* Code style fixes as per http://gsoc.trac.wordpress.org/ticket/377
     138* Fixed https://github.com/codebykat/wp-post-by-email/issues/3
    47139
    48140= 1.0.3 =
Note: See TracChangeset for help on using the changeset viewer.