Permalink
Browse files

First version of content providers docs.

  • Loading branch information...
1 parent 875b19b commit c6d69b9dbf5ab75186a624ff7964804ed3db41c5 @farazdagi farazdagi committed Jun 29, 2011
Showing with 308 additions and 0 deletions.
  1. +225 −0 entries/en/documentation/providers.twig
  2. +30 −0 entries/en/samples/provider.primarchs.twig
  3. +53 −0 plugins/Provider/Primarchs.php
@@ -0,0 +1,225 @@
+permalink: /en/documentation/providers/
+---
+<h1 id="main">Content Providers</h1>
+<div class="toc-box">&nbsp;</div>
+
+<h2 id="core" class="in-toc">Introduction</h2>
+<p>
+Sometimes you need to use some external data within your Phrozn pages.
+For the most obvious example, consider you have an RSS feed, and want to display it's contents
+on some Phrozn page. Content providers are exactly for this kind of tasks.
+</p>
+<p class="note">
+Content providers are classes that inject content within your otherwise static pages. Roughly, they represent Data Access
+Layer between your entity templates and whatever data you need to feature on those templates.
+</p>
+
+<p>
+Content providers may be as simple as some array of elements you want to traverse within your templates. They can also
+be quite complex, involving fetching data from some external servers, process it and then inject into templates.
+</p>
+
+
+<h2 id="provider-class" class="in-toc">Content Provider Class</h2>
+<p class="warning">
+All extension classes MUST reside in <code>.phrozn/plugins</code> folder.<br>
+Base namespace used for plugin code is <code>PhroznPlugin</code>.
+</p>
+
+<p>In order for your class to be used as Content Provider it MUST implement <code>Phrozn\Provider</code> interface.</p>
+<pre class="php">
+namespace Phrozn;
+use Phrozn\Has;
+
+interface Provider
+ extends Has\Config,
+ Has\ProjectPath
+{
+ /**
+ * Get generated content
+ *
+ * @return mixed
+ */
+ public function get();
+}
+</pre>
+<p>As you see, interface is pretty simple with only one relevant method <code>get</code> (other methods are
+inherited from <code>Has\Config</code> and <code>Has\ProjectPath</code> interfaces and are used to inject extra
+configuration and project path respectively).</p>
+<p>
+In order to simplify the creation of new content providers, Phrozn comes with base class that implements auxiliary
+functionality, so the only method you generally need to implement is <code>\Phrozn\Provider::get()</code>.
+</p>
+<p>
+Any data returned from <code>get()</code> method can be injected into templates. Although you can return scalars,
+it is more common to return array, and if you need scalar to inject it directly into
+<a href="/en/documentation/front-matter/#custom-variables">Front Matter custom variables</a>.
+</p>
+
+<h2 id="inject-provider-content" class="in-toc">Injecting Content Into Entries</h2>
+<p>
+Content Providers are exposed inside <a href="/en/documentation/front-matter/#custom-variables">Front Matter</a>
+using special variable <code>providers</code>:
+</p>
+<pre>
+providers:
+ key:
+ provider: ProviderClass
+ param: paramValue
+ another_param: paramValue
+</pre>
+<p>Where, </p>
+<table>
+ <tr>
+ <th width="20%">Entity</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>key</code></td>
+ <td>Anything you like to use when referring to provider within your entry.</td>
+ </tr>
+ <tr>
+ <td><code>provider</code></td>
+ <td>
+ Class name of the Content Provider class. As mentioned above this class must implement
+ <code>\Phrozn\Provider</code> interface.
+ </td>
+ </tr>
+ <tr>
+ <td><code>param(s)</code></td>
+ <td>
+ You can pass any named parameters to provider class, thus allowing parametrization.
+ Parameters are optional, and if passed can be accessed within provider class by
+ using <code>\Phrozn\Provider::getConfig()</code> method.
+ </td>
+ </tr>
+</table>
+
+<p>
+As you can see, <code>providers</code> is a list, implying that within single entry you may have several
+different providers, or you can expose the very same provider under different keys (and using different parameters).
+See example below, which does exactly that.
+</p>
+
+
+<h2 id="primarchs-list-example" class="in-toc">Simple Example (List of Primarchs)</h2>
+<p>
+Let's start simple and create very basic Content Provider, one that will only inject bunch of strings into
+our template.
+</p>
+
+<p>Here is our simple provider that injects the
+names of <a href="http://warhammer40k.wikia.com/wiki/Primarch">Primarchs</a> into an entry.
+Standard location for processor classes is <code>plugins/Provider</code>, so we save this as
+<code>plugins/Provider/Primarchs.php</code>:</p>
+
+<pre class="php">
+namespace PhroznPlugin\Provider;
+
+class Primarchs
+ extends \Phrozn\Provider\Base
+ implements \Phrozn\Provider
+{
+ private $primarchs = array(
+ array("Lion El'Jonson", "Dark Angels", "Loyal"),
+ array("Fulgrim", "Emperor's Children", "Traitor"),
+ array("Perturabo", "Iron Warriors", "Traitor"),
+ array("Jaghatai Khan", "White Scars", "Loyal"),
+ array("Leman Russ", "Space Wolves", "Loyal"),
+ array("Rogal Dorn", "Imperial Fists", "Loyal"),
+ array("Night Haunter", "Night Lords", "Traitor"),
+ array("Sanguinius", "Blood Angels", "Loyal"),
+ array("Ferrus Manus", "Iron Hands", "Loyal"),
+ array("Angron", "World Eaters", "Traitor"),
+ array("Roboute Guilliman", "Ultramarines", "Loyal"),
+ array("Mortarion", "Death Guard", "Traitor"),
+ array("Magnus the Red", "Thousand Sons", "Traitor"),
+ array("Horus", "Luna Wolves/Sons of Horus", "Traitor"),
+ array("Lorgar", "Word Bearers", "Traitor"),
+ array("Vulkan", "Salamanders", "Loyal"),
+ array("Corax", "Raven Guard", "Loyal"),
+ array("Alpharius1 &nbsp; Omegeon2", "Alpha Legion", "Complicated"),
+ );
+
+ public function get()
+ {
+ // get reference to configuration object (it holds passed vars, if any)
+ $config = $this-&gt;getConfig();
+
+ // form list, replacing numeric keys with associative
+ // you can get rid of this by updating original array
+ $primarchs = array_map(function ($item) {
+ return array(
+ 'name' =&gt; $item[0],
+ 'legion' =&gt; $item[1],
+ 'allegiance' =&gt; $item[2],
+ );
+ }, $this-&gt;primarchs);
+
+ // find who is loyal and who is not!
+ if (isset($config['allegiance']) &amp;&amp; $allegiance = $config['allegiance']) {
+ $primarchs = array_filter($primarchs, function ($primarch) use ($allegiance) {
+ return $allegiance === $primarch['allegiance'];
+ });
+ }
+
+ return $primarchs;
+ }
+}
+</pre>
+
+<p>If it doesn't make sense just yet, don't worry it will in a minute. Here is corresponding entry file
+<code>provider.primarchs.twig</code>:</p>
+<pre class="html">
+providers:
+ all_primarchs:
+ provider: Primarchs
+ traitor_primarchs:
+ provider: Primarchs
+ allegiance: Traitor # pass parameter
+ loyal_primarchs:
+ provider: Primarchs
+ allegiance: Loyal
+---
+&lt;h1 id=&quot;all-primarchs&quot;&gt;All Primarchs:&lt;/h1&gt;
+&lt;ul&gt;
+{% raw %}{% for primarch in this.providers.all_primarchs %}
+ &lt;li&gt;&lt;b&gt;{{ primarch.name }}&lt;/b&gt; of {{ primarch.legion }} ({{ primarch.allegiance}})&lt;/li&gt;
+{% endfor %}{% endraw %}
+&lt;/ul&gt;
+
+&lt;h1 id=&quot;loyal-primarchs&quot;&gt;Loyal Primarchs:&lt;/h1&gt;
+&lt;ul&gt;
+{% raw %}{% for primarch in this.providers.traitor_primarchs %}
+ &lt;li&gt;&lt;b&gt;{{ primarch.name }}&lt;/b&gt; of {{ primarch.legion }} ({{ primarch.allegiance}})&lt;/li&gt;
+{% endfor %}{% endraw %}
+&lt;/ul&gt;
+
+&lt;h1 id=&quot;traitor-primarchs&quot;&gt;Traitor Primarchs:&lt;/h1&gt;
+&lt;ul&gt;
+{% raw %}{% for primarch in this.providers.traitor_primarchs %}
+ &lt;li&gt;&lt;b&gt;{{ primarch.name }}&lt;/b&gt; of {{ primarch.legion }} ({{ primarch.allegiance}})&lt;/li&gt;
+{% endfor %}{% endraw %}
+&lt;/ul&gt;
+</pre>
+<p>
+As you see I exposed the same provider class <code>Primarchs</code> under different keys.
+The only difference is parameter passed.
+</p>
+<p>
+Now, it is a good time to scroll up and review the code in provider's <code>get()</code> method.
+Pretty simple stuff, right?
+</p>
+
+<p>
+By the way, did you know that number of loyal Primarchs is equal to that of traitors? Check the
+<a href="/en/samples/provider.primarchs.html">result page</a> and see for yourself :)
+</p>
+
+<h2 id="conclusion" class="in-toc">Conclusion</h2>
+<p>
+As you see, Phrozn has quite a good support for dynamic content (if your dynamically
+genereated data is ok with being put into static form).
+Whenever you need to get access to some data within your entries, the answer is almost always will be
+Content Providers.
+</p>
@@ -0,0 +1,30 @@
+providers:
+ all_primarchs:
+ provider: Primarchs
+ traitor_primarchs:
+ provider: Primarchs
+ allegiance: Traitor # pass parameter
+ loyal_primarchs:
+ provider: Primarchs
+ allegiance: Loyal
+---
+<h1 id="all-primarchs">All Primarchs:</h1>
+<ul>
+{% for primarch in this.providers.all_primarchs %}
+ <li><b>{{ primarch.name }}</b> of {{ primarch.legion }} ({{ primarch.allegiance}})</li>
+{% endfor %}
+</ul>
+
+<h1 id="loyal-primarchs">Loyal Primarchs:</h1>
+<ul>
+{% for primarch in this.providers.traitor_primarchs %}
+ <li><b>{{ primarch.name }}</b> of {{ primarch.legion }} ({{ primarch.allegiance}})</li>
+{% endfor %}
+</ul>
+
+<h1 id="traitor-primarchs">Traitor Primarchs:</h1>
+<ul>
+{% for primarch in this.providers.traitor_primarchs %}
+ <li><b>{{ primarch.name }}</b> of {{ primarch.legion }} ({{ primarch.allegiance}})</li>
+{% endfor %}
+</ul>
@@ -0,0 +1,53 @@
+<?php
+namespace PhroznPlugin\Provider;
+
+class Primarchs
+ extends \Phrozn\Provider\Base
+ implements \Phrozn\Provider
+{
+ private $primarchs = array(
+ array("Lion El'Jonson", "Dark Angels", "Loyal"),
+ array("Fulgrim", "Emperor's Children", "Traitor"),
+ array("Perturabo", "Iron Warriors", "Traitor"),
+ array("Jaghatai Khan", "White Scars", "Loyal"),
+ array("Leman Russ", "Space Wolves", "Loyal"),
+ array("Rogal Dorn", "Imperial Fists", "Loyal"),
+ array("Night Haunter", "Night Lords", "Traitor"),
+ array("Sanguinius", "Blood Angels", "Loyal"),
+ array("Ferrus Manus", "Iron Hands", "Loyal"),
+ array("Angron", "World Eaters", "Traitor"),
+ array("Roboute Guilliman", "Ultramarines", "Loyal"),
+ array("Mortarion", "Death Guard", "Traitor"),
+ array("Magnus the Red", "Thousand Sons", "Traitor"),
+ array("Horus", "Luna Wolves/Sons of Horus", "Traitor"),
+ array("Lorgar", "Word Bearers", "Traitor"),
+ array("Vulkan", "Salamanders", "Loyal"),
+ array("Corax", "Raven Guard", "Loyal"),
+ array("Alpharius1 & Omegeon2", "Alpha Legion", "Complicated"),
+ );
+
+ public function get()
+ {
+ // get reference to configuration object (it holds passed vars, if any)
+ $config = $this->getConfig();
+
+ // form list, replacing numeric keys with associative
+ // you can get rid of this by updating original array
+ $primarchs = array_map(function ($item) {
+ return array(
+ 'name' => $item[0],
+ 'legion' => $item[1],
+ 'allegiance' => $item[2],
+ );
+ }, $this->primarchs);
+
+ // apply allegiance filter
+ if (isset($config['allegiance']) && $allegiance = $config['allegiance']) {
+ $primarchs = array_filter($primarchs, function ($primarch) use ($allegiance) {
+ return $allegiance === $primarch['allegiance'];
+ });
+ }
+
+ return $primarchs;
+ }
+}

0 comments on commit c6d69b9

Please sign in to comment.