Merge pull request #213 from demoive/master

Labels and documentation changes re: custom transformer rules

README.md

@@ -8,6 +8,10 @@ This plugin adds support for Instant Articles for Facebook, which is a new way f
 
 With the plugin active, a new menu will be available for you to connect to your Facebook Page and start publishing your Instant Articles. You'll also see the status of each Instant Articles submission on the edit page of your posts.
 
+A best effort is made to generate valid Instant Article markup from your posts' content/metadata and publish it to Facebook. The plugin knows how to transform your posts' markup from a set of rules which forms a mapping between elements in you *source markup* and the valid *Instant Article components*. We refer to this “glue” between the two as the ***Transformer Rules***.
+
+Built-in to the plugin are many [pre-defined transformer rules](https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json) which aims to cover standard WordPress installations. If your WordPress content contains elements which are not covered by the built-in ruleset, you can define your own additional rules to extend or override the defaults in the Settings of this plugin, under: **Plugin Configuration** > **Publishing Settings** > **Custom transformer rules**.
+
 ## Feed submission to Facebook
 
 Facebook has a review process where they verify that all Instant Articles are properly formatted, have content consistency with their mobile web counterparts, and adhere to their community standards and content policies. You will not be able to publish Instant Articles in Facebook until your feed has been approved.
@@ -26,13 +30,29 @@ Facebook requires a minimum number of articles in your feed before they will rev
 
 ## Frequently Asked Questions
 
-**How do I customize the output for my site?**
+**Why is there content from my post missing in the generated Instant Article?**
+
+More likely than not, this is because there is markup in the body of your post that is not mapped to a recognized Instant Article component. On the “Edit Post” screen for your post, look for additional information about the *transformed* output shown within the **Facebook Instant Articles** module located at the bottom of the screen.
+
+**In the Instant Articles module for my post, what does the “This post was transformed into an Instant Article with some warnings” message mean?**
+
+When transforming your post into an Instant Article, this plugin will show warnings when it encounters content which might not be valid when published to Facebook. When you see this message, it is recommended to resolve each warning individually.
+
+**What does the “No rules defined for ____ in the context of  ____” warning mean?**
+
+This plugin transforms your post into an Instant Article by matching markup in your content to one of the [components available](https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/docs/QuickStart.md#transformer-classes) in Instant Articles markup. Although the plugin contains many [built-in rules](https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json) to handle common cases, there may be markup in your post which is not recognized by these existing rules. In this case, you may be required to define some of your own rules. See below for more details about where and how.
+
+**How do I define my own transformer rules so that content from my site is rendered appropriately in an Instant Article?**
+
+Your custom rules can be defined in the Settings of this plugin, under: **Plugin Configuration** > **Publishing Settings** > **Custom transformer rules**. More detailed instructions about all the options available is documented in the [Custom Transformer Rules](https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/docs/QuickStart.md#custom-transformer-rules) section of the Facebook Instant Articles SDK.
+
+**I know of a custom transformer rule which is pretty common in the community. How can it be included by default in the plugin?**
 
-There are a number of filters available in the plugin for modifying the output.
+You can propose popular transformer rules to be included in the plugin by [suggesting it on GitHub](https://github.com/Automattic/facebook-instant-articles-wp/issues/new).
 
 **How do I post articles to Instant Articles after plugin is installed?**
 
-You can re-publish existing articles (simply edit + save) or post new articles in order to submit them to Instant Articles. After you have 50 articles added, you will be able to submit them for review.
+You can re-publish existing articles (simply edit + save) or post new articles in order to submit them to Instant Articles. After you have 10 articles added, you will be able to submit them for review.
 
 **How do I change the feed slug/URL if I'm using the RSS integration?**
 

meta-box/meta-box-template.php

@@ -139,9 +139,9 @@
 	<p>
 		<span class="dashicons dashicons-warning"></span>
 		This post was transformed into an Instant Article with some warnings
-		<a href="#" class="instant-articles-toggle-debug">
-			(toggle debug information)
-		</a>
+		[<a href="https://wordpress.org/plugins/fb-instant-articles/faq/" target="_blank">Learn more</a> |
+		<a href="<?php echo esc_url( $settings_page_href ); ?>">Transformer rule configuration</a> |
+		<a href="#" class="instant-articles-toggle-debug">Toggle debug information</a>]
 	</p>
 	<ul class="instant-articles-messages">
 		<?php foreach ( $adapter->transformer->getWarnings() as $warning ) : ?>
@@ -166,9 +166,7 @@
 	<p>
 		<span class="dashicons dashicons-yes"></span>
 		This post was transformed into an Instant Article with no warnings
-		<a href="#" class="instant-articles-toggle-debug">
-			(toggle debug information)
-		</a>
+		[<a href="#" class="instant-articles-toggle-debug">Toggle debug information]</a>
 	</p>
 <?php endif; ?>
 

readme.txt

@@ -15,6 +15,10 @@ This plugin adds support for Instant Articles for Facebook, which is a new way f
 
 With the plugin active, a new menu will be available for you to connect to your Facebook Page and start publishing your Instant Articles. You'll also see the status of each Instant Articles submission on the edit page of your posts.
 
+A best effort is made to generate valid Instant Article markup from your posts' content/metadata and publish it to Facebook. The plugin knows how to transform your posts' markup from a set of rules which forms a mapping between elements in you *source markup* and the valid *Instant Article components*. We refer to this “glue” between the two as the ***Transformer Rules***.
+
+Built-in to the plugin are many [pre-defined transformer rules](https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json) which aims to cover standard WordPress installations. If your WordPress content contains elements which are not covered by the built-in ruleset, you can define your own additional rules to extend or override the defaults in the Settings of this plugin, under: **Plugin Configuration** > **Publishing Settings** > **Custom transformer rules**.
+
 = Feed submission to Facebook =
 
 Facebook has a review process where they verify that all Instant Articles are properly formatted, have content consistency with their mobile web counterparts, and adhere to their community standards and content policies. You will not be able to publish Instant Articles in Facebook until your feed has been approved.
@@ -42,9 +46,29 @@ Facebook requires a minimum number of articles in your feed before they will rev
 
 == Frequently Asked Questions ==
 
-= How do I customize the output for my site? =
+= Why is there content from my post missing in the generated Instant Article? =
+
+More likely than not, this is because there is markup in the body of your post that is not mapped to a recognized Instant Article component. On the “Edit Post” screen for your post, look for additional information about the *transformed* output shown within the **Facebook Instant Articles** module located at the bottom of the screen.
+
+= In the Instant Articles module for my post, what does the “This post was transformed into an Instant Article with some warnings” message mean? =
+
+When transforming your post into an Instant Article, this plugin will show warnings when it encounters content which might not be valid when published to Facebook. When you see this message, it is recommended to resolve each warning individually.
+
+= What does the “No rules defined for ____ in the context of  ____” warning mean? =
+
+This plugin transforms your post into an Instant Article by matching markup in your content to one of the [components available](https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/docs/QuickStart.md#transformer-classes) in Instant Articles markup. Although the plugin contains many [built-in rules](https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json) to handle common cases, there may be markup in your post which is not recognized by these existing rules. In this case, you may be required to define some of your own rules. See below for more details about where and how.
+
+= How do I define my own transformer rules so that content from my site is rendered appropriately in an Instant Article? =
+
+Your custom rules can be defined in the Settings of this plugin, under: **Plugin Configuration** > **Publishing Settings** > **Custom transformer rules**. More detailed instructions about all the options available is documented in the [Custom Transformer Rules](https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/docs/QuickStart.md#custom-transformer-rules) section of the Facebook Instant Articles SDK.
+
+= I know of a custom transformer rule which is pretty common in the community. How can it be included by default in the plugin? =
+
+You can propose popular transformer rules to be included in the plugin by [suggesting it on GitHub](https://github.com/Automattic/facebook-instant-articles-wp/issues/new).
+
+= How do I post articles to Instant Articles after plugin is installed? =
 
-There are a number of filters available in the plugin for modifying the output.
+You can re-publish existing articles (simply edit + save) or post new articles in order to submit them to Instant Articles. After you have 10 articles added, you will be able to submit them for review.
 
 = How do I change the feed slug/URL if I'm using the RSS integration? =
 
@@ -55,15 +79,19 @@ By default it is set to `instant-articles` which usually will give you a feed UR
 
 Usually simply visiting the permalinks settings page in the WordPress dashboard will do the trick (/wp-admin/options-permalink.php)
 
+== Screenshots ==
+
+1. Customized transformer rules enabled on the main Settings page. The particular configuration shown here would cause `<u>` and `<bold>` tags in the source markup to be rendered in *italics* and **bold**, respectively, in the generated Instant Article.
+
 == Changelog ==
 
-= 0.1 =
-* Initial version
+= 2.1 =
+* Fixes compatibility with PHP 5.4+
+* Bug fixes
 
 = 2.0 =
 * Using Facebook Instant Articles SDK for PHP
 * Added API integration
 
-= 2.1 =
-* Fixes compatibility with PHP 5.4+
-* Bug fixes
+= 0.1 =
+* Initial version

settings/class-instant-articles-option-publishing.php

@@ -24,7 +24,7 @@ class Instant_Articles_Option_Publishing extends Instant_Articles_Option {
 
 		'dev_mode' => array(
 			'label' => 'Development Mode',
-			'description' => 'When publishing in development, none of your articles will be made live, and they will be saved as drafts you can edit in the Instant Articles library on your Facebook Page. Whether in development mode or not, articles will not be published live until you have submitted a sample batch to Facebook and passed a one-time review.',
+			'description' => 'Articles published while in Development Mode are saved as "drafts" within Facebook and will not be made live. Note: Since articles in "draft" are not reviewed, Development Mode should be disabled when publishing articles to Facebook which you intend to use in your <a href="https://developers.facebook.com/docs/instant-articles/publishing#review" target="_blank">one-time review</a>.',
 			'render' => 'checkbox',
 			'default' => false,
 			'checkbox_label' => 'Enable development mode',
@@ -35,15 +35,15 @@ class Instant_Articles_Option_Publishing extends Instant_Articles_Option {
 			'render' => 'checkbox',
 			'default' => '',
 			'checkbox_label' => 'Enable custom transformer rules',
-			'description' => 'You can provide a JSON with a list of additional <a href="https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/docs/QuickStart.md#transformer" target="_blanl">Transformer Rules</a> to customize the output of your Instant Articles.',
+			'description' => 'Define your own rules to customize the transformation of your content into Instant Articles',
 			'default' => '',
 		),
 
 		'custom_rules' => array(
 			'label' => '',
 			'render' => 'textarea',
 			'placeholder' => '{ "rules": [{ "class": "BoldRule", "selector": "span.bold" }, ... ] }',
-			'description' => 'Refer to the <a href="https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/tests/Facebook/InstantArticles/Transformer/instant-article-example-rules.json" target="_blank">example JSON</a> on the <a href="https://github.com/facebook/facebook-instant-articles-sdk-php" target="_blank">Facebook Instant Articles PHP SDK</a> for sample configurations for all built-in rules.',
+			'description' => 'Read more about <a href="https://github.com/facebook/facebook-instant-articles-sdk-php/blob/master/docs/QuickStart.md#custom-transformer-rules" target="_blank">defining your own custom rules</a> to extend/override the <a href="https://github.com/Automattic/facebook-instant-articles-wp/blob/master/rules-configuration.json" target="_blank">built-in ruleset</a>. If you\'ve defined a common rule which you think this plugin should include by default, <a href="https://github.com/Automattic/facebook-instant-articles-wp/issues/new" target="_blank">tell us about it</a>!',
 			'default' => ''
 		),