[RFC|Merged] Resource locator

These requests for comments/change have lead to an implemented feature that has been successfully merged into the 3.1/Ascraeus branch. Everything listed in this forum will be available in phpBB 3.1.
Post Reply
User avatar
Arty
Registered User
Posts: 970
Joined: Wed Mar 06, 2002 2:36 pm
Location: Mars
Contact:

[RFC|Merged] Resource locator

Post by Arty » Thu Mar 29, 2012 8:57 pm

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: Patch
Ticket: http://tracker.phpbb.com/browse/PHPBB3-10733
Pull request: https://github.com/phpbb/phpbb3/pull/678
Formerly known as CyberAlien.

Free phpBB styles | Premium responsive XenForo styles

Post Reply