Understanding Resource Strings

#1. Introduction

If you have ever heard of MVC (Model-View-Controller) you might happen to know that using HTML strings in your PHP code is bad style of coding. Though since the early LDU days there has been a lot of them in the core. In Cotonti we aimed at eliminating those strings and giving template designers total control over markup and layout.

In order to achieve this goal the concept of Resource Strings (often shortened as rc) was introduced in Cotonti 0.7.0. This article describes what they are and gives recommendations on how to use them and convert old code to pure MVC + RC.
 

#2. Resource strings in general

Resource Strings are just PHP string variables which are supposed to be used in HTML (or any other) output of a website. The main difference is that they are contained in the global $R array and are physically separated from the core/module PHP code.

A set of predefined standard resources is located in system/resources.php. If a theme maker wants to customize some resource string, he just redefines it in themes/THEME_NAME/THEME_NAME.php. Module and plugin developers can also provide standard resources for their code in other specific resource files, which still can be overriden by exact theme's definitions.

Global $R array is used to contain all the resources just like $L is used for language strings. Prefixes are used to keep them in order. First of all, resources are organized by module, so module prefix comes first (e.g. 'pfs_'). Resources which are common for all over the Cotonti have no module prefix. Then there is usually a resource type prefix like 'icon_', 'link_', 'code_', etc. Here is an example resource string definition:

$R['pfs_icon_folder'] = '<img class="icon" src="themes/'.$theme.'/img/system/icon-folder.gif" alt="'.$L['Folder'].'" />';

As you can see, it defines HTML structure of a frequently used element and utilizes global static variables such as $L, $theme, $cfg, $usr, etc.

Here is the list of common resource type prefixes used in resource names:

• code_ - a generic piece of HTML/JavaScript code
• icon_ - icon image tag
• input_ - a form element
• link_ - a hyperlink, may be a composite link

#3. Static and dynamic resources

Many resource strings such as icons are static: you define them once and use just as they are. The above $R['pfs_icon_folder'] example is a static resource. In PHP code you utilize it explicitly, e.g.:

$some_folder = $R['pfs_icon_folder'] . $something;

It can also be used in TPL files this way:

<a href="/some/folder">{PHP.R.pfs_icon_folder} {FOLDER_NAME}</a>

But sometimes you need widgets which have parts assigned on the fly in your PHP script. Such resources are known as dynamic. Here is an example of dynamic resources:

$R['pfs_icon_type'] = '<img class="icon" src="images/pfs/{$type}.gif" alt="{$name}" />';

As you see most of it is still static HTML. But there are substitution parts like {$var_name} which remind you of PHP strings and some template engines. Make sure to use single quotes (ticks) so that they are not considered as PHP variables though.

Unfortunately you cannot effectively use dynamic resources in TPL files because they are specific to PHP code. There is a special function called cot_rc() which is used for that. Here is how you could use it for above resource:

$some_icon = cot_rc('pfs_icon_type', array('type' => $type, 'name' => $name));

Or if you are in global scope and $type and $name are globals, you could simply call it

$some_icon = cot_rc('pfs_icon_type');

By default cot_rc() searches the global $R array at given resource index. But you could pass some specific resource string directly, e.g.

$something = cot_rc('Every <b>{$pet}</b> likes <i>{$food}</i>', array('pet' => 'dog', 'food' => 'meat'));

The second parameter is an associative array of dynamic substitutions. If cot_rc() encounters {$var_name} and there is no 'var_name' passed in substitutions, it tries to use $var_name from the global scope.
There is also short syntax for parameters list represented by a query string:

$some_icon = cot_rc('pfs_icon_type', "type=$type&name=$name"));

Use short format for simple short parameter lists where values do not contain characters like '=', '&' and other complex formatting.
 

#4. Assembling the links

You can often see something like:

$out = '<a href="' . cot_url('mod', 'arg1=val1&arg2=val2') . '" title="' . $title . '">' . $text . '</a>';

here and there in the code. Sure you could use dynamic resources and cot_rc() for that but it would be no way shorter. So we have cot_rc_link() function to make hyperlinks on the fly. Let's transform most recent example into:

$out = cot_rc_link(cot_url('mod', 'arg1=val1&arg2=val2'), $text, array('title' => $title));

Well, it's not perfect as something perfect would look like do_all_i_want_now(). But it applies dynamic resource concept on links and eliminates HTML from core. For purists.

Function signature is simple. The first parameter is an URL (use cot_url() for good). The second one is tag contents (you can use $R, cot_rc() or whatever too). The third one is optional tag attributes either as an associative array or just a plain string (escaping HTML sequences and validity is caller's duty).
 

#5. Recommendations for developers

Now that you are familiar with Resource Strings I need to give some recommendations in case you are eventually going to eliminate HTML from your PHP code. It involves some aspects besides resource strings too. But I'll keep it short.

1. Use resource strings for small reusable things like "widgets": icons, buttons, inputs, etc.
2. Provide your widgets with CSS classes.
3. Try to keep things as simple as possible, don't use dynamic resources for overcomplicated code snippets.
4. Tables, lists and other design/layout structures must be moved to TPL files rather than resources.