github-migration
/
comicpress-core
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

port template tags docs

This commit is contained in:
John Bintz 2009-11-18 18:39:37 -05:00
parent d35cf3a883
commit 471ae0a782
6 changed files with 328 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
classes/ComicPressStoryline.inc
View File

@ -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);
}
}
}
}

19
css/cp-admin.css
View File

@ -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
@ -214,3 +225,9 @@ a.selected {
tr.highlighted td {
background-color: #ffff30
}
.cp-documentation ul {
list-style-type: inherit;
margin: inherit;
padding: inherit
}

237
docs/en_US/storyline-post-template-tags.html Normal file
View File

@ -0,0 +1,237 @@
<h1>Storyline Post Template Tags</h1>
<h2>R() and RT()</h2>
<p>
<code>R()</code> and <code>RT()</code> find posts that are relative to the current or provided post.
<code>R()</code> returns the found post, while <code>RT()</code> 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:
</p>
<pre class="prettyprint lang-php">
// 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
</pre>
<h3>Basic Interactive Usage Sample</h3>
<div style="overflow: hidden">
<p><em>Mouse over each template tag on the right to see what post it will return relative to the <strong>Current Post</strong>.</em></p>
<div id="comicpress-relative-post-highlighter">
<ul>
<li><code class="highlight-1">R('first')</code></li>
<li><code class="highlight-1">R('first', 'blog')</code></li>
<li><code class="highlight-2">R('first', 'comic')</code></li>
<li><code class="highlight-3">R('previous', 'blog')</code></li>
<li><code class="highlight-4">R('previous', 'comic')</code></li>
<li><code class="highlight-5">R('previous')</code></li>
<li><code class="highlight-6">R('current')</code></li>
<li><code class="highlight-7">R('next')</code></li>
<li><code class="highlight-8">R('next', 'comic')</code></li>
<li><code class="highlight-9">R('next', 'blog')</code></li>
<li><code class="highlight-10">R('last', 'comic')</code></li>
<li><code class="highlight-11">R('last', 'blog')</code></li>
<li><code class="highlight-11">R('last')</code></li>
</ul>
</div>
<table id="comicpress-relative-posts" cellspacing="0">
<tr>
<th>Post Name</th>
<th>Post Date</th>
<th>Post Category</th>
</tr>
<tr>
<td>First in Blog</td>
<td>2009-01-01</td>
<td>Blog</td>
</tr>
<tr>
<td>First in Comic</td>
<td>2009-01-02</td>
<td>Comic</td>
</tr>
<tr>
<td>Previous in Blog</td>
<td>2009-01-03</td>
<td>Blog</td>
</tr>
<tr>
<td>Previous in Comic</td>
<td>2009-01-04</td>
<td>Comic</td>
</tr>
<tr>
<td>A Previous Extra Post</td>
<td>2009-01-05</td>
<td>Extra</td>
</tr>
<tr>
<td><strong>Current Post</strong></td>
<td><strong>2009-01-06</strong></td>
<td><strong>Comic</strong></td>
</tr>
<tr>
<td>A Next Extra Post</td>
<td>2009-01-07</td>
<td>Extra</td>
</tr>
<tr>
<td>Next in Comic</td>
<td>2009-01-08</td>
<td>Comic</td>
</tr>
<tr>
<td>Next in Blog</td>
<td>2009-01-09</td>
<td>Blog</td>
</tr>
<tr>
<td>Last in Comic</td>
<td>2009-01-10</td>
<td>Comic</td>
</tr>
<tr>
<td>Last in Blog</td>
<td>2009-01-11</td>
<td>Blog</td>
</tr>
</table>
<br style="clear: both" />
</div>
<script type="text/javascript">
$$('body').pop().observe('mouseover', function(e) {
var all_rows = $$('#comicpress-relative-posts tr');
all_rows.invoke('removeClassName', 'highlighted');
var target = e.findElement('#comicpress-relative-post-highlighter *[class*=highlight]');
if (target) {
target.className.replace(/highlight-/, '').split(',').each(function(row) {
all_rows[row].addClassName('highlighted');
});
}
});
</script>
<h3>R() and RT() options</h3>
<p>
Both <code>R()</code> and <code>RT()</code> accept up to three parameters:
</p>
<pre class="prettyprint lang-php">
// 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);
</pre>
<p>
The second parameter, the <strong>restrictions</strong>, takes either a string or an array:
</p>
<h4>Valid strings</h4>
<ul>
<li><strong><em>a category slug</em></strong>: Search for matching posts in the provided category and its children.</li>
<li><strong>from_post</strong>: Search for matching posts in the category this post belongs to.</li>
</ul>
<h4>Valid array keys and values</h4>
<p>
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.
</p>
<ul>
<li><strong>child_of</strong> =&gt; <em>category slug</em>: Search for matching posts in the provided category and its children.</li>
<li><strong>only</strong> =&gt; <em>category slug</em>: Search only the provided category.</li>
<li><strong>root_of</strong> =&gt; <em>post ID or object</em>: Find the root category the post belongs to and search for posts from that category and in all children.</li>
<li><strong>from_post</strong> =&gt; <em>post ID or object</em>: Search for matching posts in the category this post belongs to.</li>
<li><strong>previous</strong> =&gt; <em>category slug</em>: Search for matching posts in the category before the provided category as defined in the storyline structure.</li>
<li><strong>next</strong> =&gt; <em>category slug</em>: Search for matching posts in the category after the provided category as defined in the storyline structure.</li>
<li><strong>level</strong> =&gt; <em>storyline level</em>: Search for posts in the categories defined at this level in the storyline structure, with level 1 being the topmost categories, level 2 being their direct children, etc.</i>
</ul>
<h2>Protect(), Unprotect(), and Restore()</h2>
<p>
In order for <em>ComicPress Core</em> 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 <strong>global variables</strong>.
Programmtically, it can be tricky to keep track of and manage these variables. <em>ComicPress Core</em> handles all of this for you using the <code>Protect()</code>,
<code>Unprotect()</code>, and <code>Restore()</code> functions.
</p>
<p>
For example, you have a comics category with the slug <strong>comic</strong>.
If you want to display the latest comic at the top of your home page, above your blog posts, you would use <code>Protect()</code> and <code>Unprotect()</code> like this:
</p>
<pre class="prettyprint lang-php">
Protect();
if (RT('last', 'comic')) {
foreach (M() as $image) { echo EM('embed'); }
?&gt;
&lt;h2&gt;&lt;?php the_title() ?&gt;&lt;/h2&gt;
&lt;?php
}
Unprotect();
</pre>
<p>
If you're using <code>RT()</code> tags to modify the current post, and need to work with the saved post, use <code>Restore()</code>:
</p>
<pre class="prettyprint lang-php">
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();
</pre>
<p>
These are also available as action and filter hooks, to keep your theme safe when <em>ComicPress Core</em> is deactivated as an alternative to <code>function_exists()</code>:
</p>
<pre class="prettyprint lang-php">
do_action('comicpress-Protect');
if (apply_filters('comicpress-RT', 'last', array('child_of' => 'comic'))) {
foreach (M() as $image) { echo EM('embed'); }
?&gt;
&lt;h2&gt;&lt;?php the_title() ?&gt;&lt;/h2&gt;
&lt;?php
}
do_action('comicpress-Unprotect');
</pre>

146
docs/en_US/template-tags.html
View File

@ -1,146 +0,0 @@
<h1>Template Tags</h1>
<h2>R() and RT()</h2>
<p>R() and RT() find posts that are relative to the current or provided post.</p>
<table id="comicpress-relative-posts" cellspacing="0">
<tr>
<th>Post Name</th>
<th>Post Date</th>
<th>Post Category</th>
</tr>
<tr>
<td>First in Blog</td>
<td>2009-01-01</td>
<td>Blog</td>
</tr>
<tr>
<td>First in Comic</td>
<td>2009-01-02</td>
<td>Comic</td>
</tr>
<tr>
<td>Previous in Blog</td>
<td>2009-01-03</td>
<td>Blog</td>
</tr>
<tr>
<td>Previous in Comic</td>
<td>2009-01-04</td>
<td>Comic</td>
</tr>
<tr>
<td>A Previous Extra Post</td>
<td>2009-01-05</td>
<td>Extra</td>
</tr>
<tr>
<td><strong>Current Post</strong></td>
<td><strong>2009-01-06</strong></td>
<td><strong>Comic</strong></td>
</tr>
<tr>
<td>A Next Extra Post</td>
<td>2009-01-07</td>
<td>Extra</td>
</tr>
<tr>
<td>Next in Comic</td>
<td>2009-01-08</td>
<td>Comic</td>
</tr>
<tr>
<td>Next in Blog</td>
<td>2009-01-09</td>
<td>Blog</td>
</tr>
<tr>
<td>Last in Comic</td>
<td>2009-01-10</td>
<td>Comic</td>
</tr>
<tr>
<td>Last in Blog</td>
<td>2009-01-11</td>
<td>Blog</td>
</tr>
</table>
<div id="comicpress-relative-post-highlighter">
<ul>
<li><code class="highlight-1">R('first')</code></li>
<li><code class="highlight-2">R('first', array('child_of' =&gt; 'comic'))</code></li>
<li><code class="highlight-2">R('previous', array('child_of' =&gt; 'blog'))</code></li>
<li><code class="highlight-2">R('previous', array('child_of' =&gt; 'comic'))</code></li>
<li><code class="highlight-2">R('previous', array('child_of' =&gt; 'comic'))</code></li>
</ul>
</div>
<script type="text/javascript">
$$('body').pop().observe('mouseover', function(e) {
var all_rows = $$('#comicpress-relative-posts tr');
all_rows.invoke('removeClassName', 'highlighted');
var target = e.findElement('#comicpress-relative-post-highlighter *[class*=highlight]');
if (target) {
target.className.replace(/highlight-/, '').split(',').each(function(row) {
top.console.log(row);
all_rows[row].addClassName('highlighted');
});
}
});
</script>
<ul>
<li><strong>child_of</strong>: The given category plus any children.</li>
</ul>
<h2>Protect(), Unprotect(), and Restore()</h2>
<p>
By design, WordPress stores information on the current page's Loop in what are known as <strong>global variables</strong>.
In order for <em>ComicPress Core</em> 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. <em>ComicPress Core</em> handles all of this for you using the Protect(),
Unprotect(), and Restore() functions.
</p>
<p>
For example, you have a comics category with the slug <strong>comic</strong>.
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:
</p>
<pre class="prettyprint lang-php">
get_header();
Protect();
if (RT('last', array('child_of' => 'comic'))) {
foreach (M() as $image) { echo EM('embed'); }
?&gt;
&lt;h2&gt;&lt;?php the_title() ?&gt;&lt;/h2&gt;
&lt;?php
}
Unprotect();
</pre>
<p>
These are also available as action and filter hooks, to keep your theme safe when <em>ComicPress Core</em> is deactivated as an alternative to function_exists():
</p>
<pre class="prettyprint lang-php">
get_header();
do_action('comicpress-Protect');
if (apply_filters('comicpress-RT', 'last', array('child_of' => 'comic'))) {
foreach (M() as $image) { echo EM('embed'); }
?&gt;
&lt;h2&gt;&lt;?php the_title() ?&gt;&lt;/h2&gt;
&lt;?php
}
do_action('comicpress-Unprotect');
</pre>

27
test/ComicPressStorylineTest.php
View File

@ -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));
}
}
?>