Merge pull request #27 from INN/22-23-custom-classnames

22 23 custom classnames

Author: benlk

README.md

@@ -10,7 +10,7 @@
 ## All options:
 
 ```
-[pym src="" pymsrc="" pymoptions="" id="" ]
+[pym src="" pymsrc="" pymoptions="" id="" class="" ]
 ```
 
 `src` is the URL of the page that is to be embedded.
@@ -34,5 +34,15 @@ To do the same thing with this Pym shortcode, you would write:
 For example, the shortcode `[pym src="http://blog.apps.npr.org/pym.js/examples/graphic/child.html" id="extremely_specific_id"]` results in the following output:
 
 ```html
-<div id="extremely_specific_example"></div><script src="http://example.org/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('extremely_specific_example', 'http://blog.apps.npr.org/pym.js/examples/graphic/child.html', {})</script>
+<div id="extremely_specific_example" class="pym"></div><script src="http://example.org/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('extremely_specific_example', 'http://blog.apps.npr.org/pym.js/examples/graphic/child.html', {})</script>
 ```
+
+`class` is optional; this should be a valid HTML class name. It will be added to the element's default class, `'pym'`. You would want to use this if, for example, you wanted to [use a size-based class name to determine the size of the embed on your site](https://github.com/INN/pym-shortcode/issues/23). The class `'pym'` will always be output on container elements created by the Pym Shortcode. This class was introduced in version 1.2.2.
+
+For example, the shortcode `[pym src="http://blog.apps.npr.org/pym.js/examples/graphic/child.html" class="one two three four float-left mw_50"]` results in the following output:
+
+```html
+<div id="pym_0" class="pym one two three four float-left mw_50"></div><script src="http://insideenergy.dev/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('pym_0', 'http://blog.apps.npr.org/pym.js/examples/graphic/child.html', {})</script>
+```
+
+If you do not want the class `'pym'` output on container elements, [add a filter](https://codex.wordpress.org/Plugin_API/Filter_Reference) to the hook `pym_shortcode_default_class` that returns an empty string.

pym-shortcode.php

@@ -17,52 +17,68 @@
 
 /**
  * A shortcode to simplify the process of embedding articles using pym.js
+ *
+ * @param Array  $atts    the attributes passed in the shortcode.
+ * @param String $content the enclosed content; should be empty for this shortcode.
+ * @param String $tag     the shortcode tag.
  */
-function pym_shortcode( $atts, $context, $tag ) {
+function pym_shortcode( $atts, $content, $tag ) {
 
-	// generate an ID for this embed, necessary to prevent conflicts
+	// generate an ID for this embed; necessary to prevent conflicts.
 	global $pym_id;
 	if ( ! isset( $pym_id ) ) {
 		$pym_id = 0;
 	} else {
 		++$pym_id;
 	}
 
+	// Set us up the vars.
 	$pymsrc = empty( $atts['pymsrc'] ) ? plugins_url( '/js/pym.v1.min.js', __FILE__ ) : $atts['pymsrc'];
 	$pymoptions = empty( $atts['pymoptions'] ) ? '' : $atts['pymoptions'];
 	$id = empty( $atts['id'] ) ? '' : esc_attr( $atts['id'] );
 	$actual_id = empty( $id ) ? 'pym_' . $pym_id : $id;
 
+	/**
+	 * Filter pym_shortcode_default_class allows setting the default class on embeds
+	 *
+	 * @param String $default
+	 * @return String the default class name
+	 */
+	$default_class = apply_filters( 'pym_shortcode_default_class', 'pym' );
+	$class = empty( $atts['class'] ) ? '' : esc_attr( $atts['class'] );
+	$actual_classes = $default_class . ' ' . $class;
+
 	$src = $atts['src'];
 
 	ob_start();
 
 	printf(
-		'<div id="%1$s"></div>',
-		$actual_id
+		'<div id="%1$s" class="%2$s"></div>',
+		esc_attr( $actual_id ),
+		esc_attr( $actual_classes )
 	);
 
 	// If this is the first one on the page, output the pym src
 	// or if the pymsrc is set, output that.
 	if ( 0 === $pym_id || ! empty( $atts['pymsrc'] ) ) {
 		echo sprintf(
 			'<script src="%s"></script>',
-			$pymsrc
+			esc_attr( $pymsrc )
 		);
 	}
 
-	// Output the parent's scripts
+	// Output the parent's scripts.
 	echo '<script>';
 	echo sprintf(
 		'var pym_%1$s = new pym.Parent(\'%2$s\', \'%3$s\', {%4$s})',
-		$pym_id,
-		$actual_id,
-		$src,
+		esc_js( $pym_id ),
+		esc_js( $actual_id ),
+		esc_js( $src ),
 		$pymoptions
 	);
 	echo '</script>';
 
-	// What is output to the page
+	// What is output to the page:
 	$ret = ob_get_clean();
 	return $ret;
 }

readme.txt

@@ -49,6 +49,8 @@ Mobile view of the WordPress post with the NPR embed using Pym Shortcode:
 * Update to pym.js version 1.2.2: https://github.com/nprapps/pym.js/releases/tag/v1.2.2 (Changelog at https://github.com/nprapps/pym.js/blob/master/CHANGELOG )
 * (we skipped pym.js version 1.2.1: https://github.com/nprapps/pym.js/releases/tag/v1.2.1 )
 * Add `id=""` attribute to allow setting custom IDs on embeds. [#21](https://github.com/INN/pym-shortcode/issues/21)
+* Add `class=""` attribute to allow setting custom classes on embeds. [#22](https://github.com/INN/pym-shortcode/issues/22) and [#23](https://github.com/INN/pym-shortcode/issues/23).
+* Add a default class name `pym` to all embed-containing div elements output by this plugin, and a filter 'pym_shortcode_default_class' to allow changing it.
 
 = 1.2.0.2 =