[RFC|Merged] Resource locator

[Arty]

Note: this requires merge of [RFC] Merge style components.

I've re-written this RFC and deleted old one.

Introduction

Styles have a nice feature: template inheritance. It allows creation of child styles that modify only few templates. Same applies to extensions: they can have custom styles that override style's templates.

Example of how it works for templates:

You have two extensions: ext1 and ext2, and two styles: prosilver and prored. Prored uses template inheritance and is set as default style. When template system is looking for template overall_header.html, it checks files in this order:

1. ext/ext1/styles/prosilver/template/overall_header.html
2. ext/ext2/styles/prosilver/template/overall_header.html
3. styles/prored/template/overall_header.html
4. styles/prosilver/template/overall_header.html

and displays whichever template it finds first. It is done by means of template locator class.

Wouldn't it be cool to apply same system to everything else? css files, javascript files, images? Yes, it definitely would. This RFC offers a solution that does not require introduction of new template tags.

RFC mentioned above merges style components, allowing to extend template inheritance to other parts of style. Problem is, there are no functions to locate other style resources.


Suggestion

I suggest to add a function:

Code: Select all

phpbb_style::locate($files, $return_default = false, $return_full_path = true);

This function will search for files in styles directories, using resource locator's template paths.

$files is array of file names to find. It can be array or string (if there is only 1 file to find).

If file exists, it will return:
- Full path to file if $return_full_path == true.
- File name (entry from $files array) if $return_full_path == false. This is useful to check which template is available before setting template specific data.

If file does not exist, it will return:
- False if $return_default == false
- Path to where file is supposed to be if $return_default == true

Examples

1. Locate javascript file. This will be useful for other RFCs like <!-- INCUDEJS --> RFC

Code: Select all

$result = $style->locate('style.js');

2. Locate language specific file, using current user's language as primary language and "default" as fallback. This is useful for implementation of RFCs like Style-specific language variables.

Code: Select all

$result = $style->locate(array('lang/en.php', 'lang/default.php'));

3. Check which email template is available:

Code: Select all

$result = $style->locate(array('jabber/message.txt', 'email/message.txt'), false, false);
switch ($result)
{
  case 'jabber/message.txt':
    // Jabber template is available, send message via jabber!
  case 'email/message.txt':
    // Email template is available, send message via email
  case false:
    // Template not found, don't send anything
}

Linked RFCs

This RFC makes it possible to implement the following:

• INCLUDEJS template tag
• Style-specific language variables
• Applying styles tree to theme (old RFC deleted, new ones isn't written yet)

Patch
Ticket: http://tracker.phpbb.com/browse/PHPBB3-10733
Pull request: https://github.com/phpbb/phpbb3/pull/678