Skip to content
This repository has been archived by the owner on Jan 28, 2022. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
First version of content providers docs.
  • Loading branch information
farazdagi committed Jun 29, 2011
1 parent 875b19b commit c6d69b9
Show file tree
Hide file tree
Showing 3 changed files with 308 additions and 0 deletions.
225 changes: 225 additions & 0 deletions entries/en/documentation/providers.twig
@@ -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>
30 changes: 30 additions & 0 deletions entries/en/samples/provider.primarchs.twig
@@ -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>
53 changes: 53 additions & 0 deletions plugins/Provider/Primarchs.php
@@ -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.