Home

Overview

The start page is meant to give you an overview of the framework's functionality. Don't worry if its too complicated for you.

This extension builds on top of WordPress in order to create a fast, structured and extensible object-oriented framework for creating themes while using a templating engine.

While currently the framework is focused on Twig as the templating engine, it can be easily used without one, as we will do in the first few pages of the Wiki, or with a different framework.

Data structure

Most WordPress objects are not directly used within the framework. Instead, there are numerous object wrappers and collections for them, which enable a nice and consistent experience, while also simplifying a lot of tasks.

Before going forward, it's important to note that at least currently, all of the objects below are read-only and there is not saving logic.

WordPress Object	Framework Object	Framework Collection
WP_Post	Rila\Post_Type	Rila\Collection\Posts
WP_Term	Rila\Taxonomy	Rila\Collection\Terms
WP_User	Rila\User	Rila\Collection\Users
WP_Comment	Rila\Comment	Rila\Collection\Comments

For easy access, the framework provides rila_[post|term|user|comment] functions, which allow you to convert a WordPress object to it's alternative from within the framework. All of those functions can construct an object based on an ID or the existing WP one, with rila_term being the only exception, as you cannot get a term based on it's ID.

Here's how to use them:

$post = rila_post( 1 );
$term = rila_post( get_category( 1 ) );
$user = rila_user( 1 );
$comment = rila_comment( 1 );

Those classes allow you to translate properties (ex. title returns post_title) and map values (ex. _thumbnail_id to an image). However, in the ideal case, you wouldn't need to use any of them, as the framework tries to prepare everything for you.

The site object

While the objects above are classes, which can be instantiated and collected, there is also the global site object, which is an instance of the Site singleton.

Than object allows you access to generic site functions like menus and also to options. The options can also be mapped and translated, because just as posts and terms, the site extends the Item class too.

Data mapping and dictionaries

As said, the main purpose of the classes/objects above is to allow easy and template-friendly access. But what does that mean?

# The WordPress way (without a full loop)
echo get_the_title( $post->ID );

# The framework way
echo $post->title;

What you see here might seem quite simplistic, but it represents the ideology behind the framework: Within templates (at least), you should not care about functions, arguments, IDs and so on. Instead, the plugin does it for you.

Even through title seems like a standard property, it's actually loaded dynamically and applies the same filters as get_the_title().

The example showcases two of the main features of the framework: Dictionaries and Mapping.

Dictionaries

Dictionaries are an internal mechanism that allows a property to be translated. In this case, title is internally translated to post_title before anything else is done.

To add translations to an object's dictionary, you need to use the translate function and give it an array in the request => target format.

Mapping

Mapping refers to a mechanism that allows properties to be mapped to functions, filters, classes and methods.

It's power comes from the fact that you can seamlessly transform properties and process them without complicated code. As mentioned, the example above applies the the_title filter to the title. This is not done through a separate function, there is just a call that looks like this within the built-in Post_Type class:

$this->map(array(
    'post_title' => 'filter:the_title'
));

Here it's important to also note, that this filter will not be applied until the moment when the property gets accessed, meaning that there is are no performance hits here. Even on the contrary: Once it's done, it's cached and will not be done again for the same post.

Templating

The last example looks like this in Twig:

{{ post.title }}

WordPress templates

Here is how the ideal single.php (try replacing single with anything) template should look when using the framework:

echo rila_template( 'single' );

and a basic corresponding template:

<h1>{{ post.title }}</h1>

{{ post.image.featured }}

{{ post.content }}

{% if post.related %}
   <h2>Related posts:</h2>
   <ul>
   {% for article in post.related %}
      <li>{{ article }}</li>
   {% endfor %}
   </ul>
{% endif %}

Extending the framework

In the core, the Rila Framework is only working with some base classes. Please feel encouraged to extend them within your theme or plugin.

With custom classes, you can add your own functionality to any post type, taxonomy or widget. The other objects, like Site, User and Comment are static, but allow you to extend them through the usage of hooks.

Those types will be explained in the following articles. When you read them, please visit the Extending the framework article to see how to add more functionality.

Advanced Custom Fields Compatability

As you will see later, this extension plays very well with data, saved by ACF. Even more - with the appropriate data architecture, you will not even need to use any of ACF's functions in the front-end, as all of the data will be loaded and parsed accordingly, including flexible content and repeater fields.

We recommend the usage of the ACF_Group class by DigtialWerk in order to allow quick custom fields definitions and nicer content blocks.

Performance

Every line of code for the plugin is written with performance in mind.

Even though there are a lot of PHP classes that are involved in rendering a page, there are zero-to-none additional database calls. Also, most of those classes, loops and collections are only loading data when it's needed, avoiding any un-needed performance hits.

Next article: Views and templates