This repository has been archived by the owner on Jan 28, 2022. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
First version of content providers docs.
- Loading branch information
Showing
3 changed files
with
308 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,225 @@ | ||
permalink: /en/documentation/providers/ | ||
--- | ||
<h1 id="main">Content Providers</h1> | ||
<div class="toc-box"> </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 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); | ||
|
||
// find who is loyal and who is not! | ||
if (isset($config['allegiance']) && $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 | ||
--- | ||
<h1 id="all-primarchs">All Primarchs:</h1> | ||
<ul> | ||
{% raw %}{% for primarch in this.providers.all_primarchs %} | ||
<li><b>{{ primarch.name }}</b> of {{ primarch.legion }} ({{ primarch.allegiance}})</li> | ||
{% endfor %}{% endraw %} | ||
</ul> | ||
|
||
<h1 id="loyal-primarchs">Loyal Primarchs:</h1> | ||
<ul> | ||
{% raw %}{% for primarch in this.providers.traitor_primarchs %} | ||
<li><b>{{ primarch.name }}</b> of {{ primarch.legion }} ({{ primarch.allegiance}})</li> | ||
{% endfor %}{% endraw %} | ||
</ul> | ||
|
||
<h1 id="traitor-primarchs">Traitor Primarchs:</h1> | ||
<ul> | ||
{% raw %}{% for primarch in this.providers.traitor_primarchs %} | ||
<li><b>{{ primarch.name }}</b> of {{ primarch.legion }} ({{ primarch.allegiance}})</li> | ||
{% endfor %}{% endraw %} | ||
</ul> | ||
</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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; | ||
} | ||
} |