From 471ae0a7827abf61bcbdd8a852fab4c325271ad7 Mon Sep 17 00:00:00 2001 From: John Bintz Date: Wed, 18 Nov 2009 18:39:37 -0500 Subject: [PATCH] port template tags docs --- classes/ComicPressStoryline.inc | 73 +++--- css/cp-admin.css | 19 +- docs/en_US/media-uploader.html | 2 +- docs/en_US/storyline-post-template-tags.html | 237 +++++++++++++++++++ docs/en_US/template-tags.html | 146 ------------ test/ComicPressStorylineTest.php | 27 +++ 6 files changed, 328 insertions(+), 176 deletions(-) create mode 100644 docs/en_US/storyline-post-template-tags.html delete mode 100644 docs/en_US/template-tags.html diff --git a/classes/ComicPressStoryline.inc b/classes/ComicPressStoryline.inc index cb85a8d..7b6bf87 100644 --- a/classes/ComicPressStoryline.inc +++ b/classes/ComicPressStoryline.inc @@ -410,7 +410,7 @@ class ComicPressStoryline { return $this; } - function _find_children($parent) { + function _ensure_numeric_category($parent) { if (!is_numeric($parent)) { foreach (get_all_category_ids() as $id) { $category = get_category($id); @@ -419,6 +419,11 @@ class ComicPressStoryline { } } } + return $parent; + } + + function _find_children($parent) { + $parent = $this->_ensure_numeric_category($parent); if (is_numeric($parent)) { $children = array($parent); do { @@ -557,38 +562,50 @@ class ComicPressStoryline { } if (!$include_all) { - foreach ($restrictions as $type => $list) { - if (substr($type, 0, 1) == "!") { - $method_root = 'exclude'; - $method_type = substr($type, 1); + foreach ($restrictions as $_type => $_list) { + if (!is_string($_type) && is_array($_list)) { + $all_checks = array($_list); } else { - $method_root = 'include'; - $method_type = $type; + $all_checks = array( + array($_type, $_list) + ); } - if (!is_array($list)) { $list = array($list); } + foreach ($all_checks as $info) { + list($type, $list) = $info; - foreach ($list as $restriction) { - $method = ''; - $args = array($restriction); - switch ($method_type) { - case 'child_of': $method = 'children'; break; - case 'root_of': $method = 'post_root'; break; - case 'from_post': $method = 'post_category'; break; - case 'previous': - $method = 'adjacent'; - $args[] = false; - break; - case 'next': - $method = 'adjacent'; - $args[] = true; - break; - default: - $method = $method_type; break; + if (substr($type, 0, 1) == "!") { + $method_root = 'exclude'; + $method_type = substr($type, 1); + } else { + $method_root = 'include'; + $method_type = $type; } - if (!empty($method)) { - array_unshift($args, "_find_${method}"); - call_user_func_array(array($this, "_${method_root}"), $args); + + if (!is_array($list)) { $list = array($list); } + + foreach ($list as $restriction) { + $method = ''; + $args = array($restriction); + switch ($method_type) { + case 'child_of': $method = 'children'; break; + case 'root_of': $method = 'post_root'; break; + case 'from_post': $method = 'post_category'; break; + case 'previous': + $method = 'adjacent'; + $args[] = false; + break; + case 'next': + $method = 'adjacent'; + $args[] = true; + break; + default: + $method = $method_type; break; + } + if (!empty($method)) { + array_unshift($args, "_find_${method}"); + call_user_func_array(array($this, "_${method_root}"), $args); + } } } } diff --git a/css/cp-admin.css b/css/cp-admin.css index ce5a1f8..de1add4 100644 --- a/css/cp-admin.css +++ b/css/cp-admin.css @@ -193,7 +193,8 @@ a.selected { #comicpress-relative-posts { border: solid #464646 1px; - border-bottom: none + border-bottom: none; + width: 65% } #comicpress-relative-posts th, @@ -206,6 +207,16 @@ a.selected { background-color: #b5bdf5 } +#comicpress-relative-post-highlighter { + float: right; + display: inline; + width: 30% +} + +#comicpress-relative-post-highlighter p { + margin-top: 0 +} + #comicpress-relative-post-highlighter code { font-size: 14px; cursor: help @@ -213,4 +224,10 @@ a.selected { tr.highlighted td { background-color: #ffff30 +} + +.cp-documentation ul { + list-style-type: inherit; + margin: inherit; + padding: inherit } \ No newline at end of file diff --git a/docs/en_US/media-uploader.html b/docs/en_US/media-uploader.html index 0979291..283f95b 100644 --- a/docs/en_US/media-uploader.html +++ b/docs/en_US/media-uploader.html @@ -1,3 +1,3 @@

Uploading Comic Files

-

WordPress Media Uploader Integration

+

WordPress Media Uploader Integration

\ No newline at end of file diff --git a/docs/en_US/storyline-post-template-tags.html b/docs/en_US/storyline-post-template-tags.html new file mode 100644 index 0000000..1c2f9bb --- /dev/null +++ b/docs/en_US/storyline-post-template-tags.html @@ -0,0 +1,237 @@ +

Storyline Post Template Tags

+ +

R() and RT()

+ +

+ R() and RT() find posts that are relative to the current or provided post. + R() returns the found post, while RT() sets up the post so that you can use + standard WordPress template tags on the found posts as if it was part of the current Loop: +

+ +
+// use a post programmatically
+$previous_post = R('previous');
+echo get_the_permalink($previous_post->ID);
+
+// use template tags with a post
+Protect(); // save the current Loop post
+RT('previous');
+the_permalink();
+Restore(); // restore the saved Loop post
+
+ +

Basic Interactive Usage Sample

+ +
+

Mouse over each template tag on the right to see what post it will return relative to the Current Post.

+ +
+
    +
  • R('first')
    • +
  • R('first', 'blog')
    • +
  • R('first', 'comic')
    • +
  • R('previous', 'blog')
    • +
  • R('previous', 'comic')
    • +
  • R('previous')
    • +
  • R('current')
    • +
  • R('next')
    • +
  • R('next', 'comic')
    • +
  • R('next', 'blog')
    • +
  • R('last', 'comic')
    • +
  • R('last', 'blog')
    • +
  • R('last')
    • +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Post NamePost DatePost Category
First in Blog2009-01-01Blog
First in Comic2009-01-02Comic
Previous in Blog2009-01-03Blog
Previous in Comic2009-01-04Comic
A Previous Extra Post2009-01-05Extra
Current Post2009-01-06Comic
A Next Extra Post2009-01-07Extra
Next in Comic2009-01-08Comic
Next in Blog2009-01-09Blog
Last in Comic2009-01-10Comic
Last in Blog2009-01-11Blog
+
+
+ + + +

R() and RT() options

+ +

+ Both R() and RT() accept up to three parameters: +

+ +
+// find the relative of all posts in the database
+R('previous');
+
+// only search the comic category and its children
+R('previous', 'comic');
+
+// only search the children of the comic category
+R('previous', array('child_of' => 'comic', '!only' => 'comic'));
+
+// get the previos post relative to the provided post
+R('previous', null, $other_post);
+
+ +

+ The second parameter, the restrictions, takes either a string or an array: +

+ +

Valid strings

+ + + +

Valid array keys and values

+ +

+ If you want a more sophisticated search, you can provide an array that, with each match, will add the matching categories to the search list. + You can preface any of the keys with an exclamation point to remove matches from the list. +

+ + + +

Protect(), Unprotect(), and Restore()

+ +

+ In order for ComicPress Core to be able to work properly, it needs to be able to work with posts that are not part of the current page's Loop. + WordPress stores information on the current page's Loop in what are known as global variables. + Programmtically, it can be tricky to keep track of and manage these variables. ComicPress Core handles all of this for you using the Protect(), + Unprotect(), and Restore() functions. +

+ +

+ For example, you have a comics category with the slug comic. + If you want to display the latest comic at the top of your home page, above your blog posts, you would use Protect() and Unprotect() like this: +

+ +
+Protect();
+
+if (RT('last', 'comic')) {
+  foreach (M() as $image) { echo EM('embed'); }
+  ?>
+    <h2><?php the_title() ?></h2>
+  <?php
+}
+
+Unprotect();
+
+ +

+ If you're using RT() tags to modify the current post, and need to work with the saved post, use Restore(): +

+ +
+get_header();
+
+Protect();
+
+RT('last', 'comic');
+echo 'The last comic title: '; echo the_title();
+
+Restore();
+echo 'The current post title: '; echo the_title();
+
+RT('first', 'comic');
+echo 'The first comic title: '; echo the_title();
+
+Unprotect();
+echo 'The current post title: '; echo the_title();
+
+ +

+ These are also available as action and filter hooks, to keep your theme safe when ComicPress Core is deactivated as an alternative to function_exists(): +

+ +
+do_action('comicpress-Protect');
+
+if (apply_filters('comicpress-RT', 'last', array('child_of' => 'comic'))) {
+  foreach (M() as $image) { echo EM('embed'); }
+  ?>
+    <h2><?php the_title() ?></h2>
+  <?php
+}
+
+do_action('comicpress-Unprotect');
+
diff --git a/docs/en_US/template-tags.html b/docs/en_US/template-tags.html deleted file mode 100644 index a9857a1..0000000 --- a/docs/en_US/template-tags.html +++ /dev/null @@ -1,146 +0,0 @@ -

Template Tags

- -

R() and RT()

- -

R() and RT() find posts that are relative to the current or provided post.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Post NamePost DatePost Category
First in Blog2009-01-01Blog
First in Comic2009-01-02Comic
Previous in Blog2009-01-03Blog
Previous in Comic2009-01-04Comic
A Previous Extra Post2009-01-05Extra
Current Post2009-01-06Comic
A Next Extra Post2009-01-07Extra
Next in Comic2009-01-08Comic
Next in Blog2009-01-09Blog
Last in Comic2009-01-10Comic
Last in Blog2009-01-11Blog
- -
- -
- - - - - -

Protect(), Unprotect(), and Restore()

- -

- By design, WordPress stores information on the current page's Loop in what are known as global variables. - In order for ComicPress Core to be able to work properly, it needs to be able to work with posts that are not part of the current page's Loop. - The best example is on the Home page of a standard webcomic, where the latest comic is displayed above the list of current blog posts. - Programmtically, it can be tricky to keep track of and manage these variables. ComicPress Core handles all of this for you using the Protect(), - Unprotect(), and Restore() functions. -

- -

- For example, you have a comics category with the slug comic. - If you want to display the latest comic at the top of your home page, above your blog posts, you would use Protect() and Restore() like this: -

- -
-get_header();
-
-Protect();
-
-if (RT('last', array('child_of' => 'comic'))) {
-  foreach (M() as $image) { echo EM('embed'); }
-  ?>
-    <h2><?php the_title() ?></h2>
-  <?php
-}
-
-Unprotect();
-
- -

- These are also available as action and filter hooks, to keep your theme safe when ComicPress Core is deactivated as an alternative to function_exists(): -

- -
-get_header();
-
-do_action('comicpress-Protect');
-
-if (apply_filters('comicpress-RT', 'last', array('child_of' => 'comic'))) {
-  foreach (M() as $image) { echo EM('embed'); }
-  ?>
-    <h2><?php the_title() ?></h2>
-  <?php
-}
-
-do_action('comicpress-Unprotect');
-
diff --git a/test/ComicPressStorylineTest.php b/test/ComicPressStorylineTest.php index cbe0b21..f99ec1a 100644 --- a/test/ComicPressStorylineTest.php +++ b/test/ComicPressStorylineTest.php @@ -568,6 +568,14 @@ class ComicPressStorylineTest extends PHPUnit_Framework_TestCase { array( array('next' => 3), array(4) + ), + array( + array( + array('only', 1), + array('only', 2), + array('!only', 2), + ), + array(1) ) ); } @@ -657,6 +665,25 @@ class ComicPressStorylineTest extends PHPUnit_Framework_TestCase { function testEnsurePostID($thing, $expected_result) { $this->assertEquals($expected_result, $this->css->_ensure_post_id($thing)); } + + function providerTestEnsureNumericCategory() { + return array( + array(false, false), + array(0, 0), + array(1, 1), + array('comic', 'comic'), + array('test', 1) + ); + } + + /** + * @dataProvider providerTestEnsureNumericCategory + */ + function testEnsureNumericCategory($string, $expected_id) { + add_category(1, (object)array('slug' => 'test')); + + $this->assertEquals($expected_id, $this->css->_ensure_numeric_category($string)); + } } ?> \ No newline at end of file