User tests: Successful: Unsuccessful:
This PR tries to improve & fix some issues in the curre JLayout system
Currently there is a fix that makes that includePaths cannot be changed by developers. See #3451
This was caused because the refreshIncludePaths() method was called always on render method. Not the logic attached to load the default include paths is only triggered when there are no includePaths explicilty defined.
Now you can use different methods to set the include paths:
$layout = new JLayoutFile('mylibrary.item');
// Explicitly set the array of include paths
$layout->setIncludePaths(array(JPATH_LIBRARIES . '/mylibrary/layouts'));
// Add a layout folder on top of the default includePaths
$layout->addIncludePath(JPATH_LIBRARIES . '/mylibrary/layouts');
// Add more than one folder on top of the default include paths
$layout->addIncludePaths(
array(
JPATH_LIBRARIES . '/mylibrary/layouts',
JPATH_SITE . '/layouts'
)
);
Now there is a method to clear the list of include paths. Usage:
$layout = new JLayoutFile('mylibrary.item');
// Clear any existing include path
$layout->clearIncludePaths();
// Add our own paths
$layout->addIncludePaths(
array(
JPATH_LIBRARIES . '/mylibrary/layouts',
JPATH_SITE . '/layouts'
)
);
// Note that you don't need to clear include paths to replace them. This would be faster:
$layout->setIncludePaths(
array(
JPATH_LIBRARIES . '/mylibrary/layouts',
JPATH_SITE . '/layouts'
)
);
Now we can get the list of active paths that are going to be used to render a layout:
$layout = new JLayoutFile('mylibrary.item');
// Get the active include paths. If they are not set default include paths will be returned
$defaultPaths = $layout->getIncludePaths();
// Replace include paths
$layout->setIncludePaths(
array(
JPATH_LIBRARIES . '/mylibrary/layouts',
JPATH_SITE . '/layouts'
)
);
// Get the list of new paths assigned
$newPaths = $layout->getIncludePaths();
This allows a more dynamic way of setup layouts. Examples:
$layout = new JLayoutFile('mylibrary.item');
// Set our custom include paths
$layout->setIncludePaths(array(JPATH_LIBRARIES . '/mylibrary/layouts')
// Enable debug
->setDebug(true)
// Load our prefixes
->setSuffixes(array('bs3', 'bs2'));
// Render the layout
echo $layout->render(array('item' => $item));
Most rendering systems include a way to dynamically set & set data. Now you can do it like:
$layout = new JLayoutFile('mylibrary.item');
// Set a data value
$layout->set('name', 'Roberto');
// Sample of how it can be used
if ($useTooltips)
{
$layout->set('tooltip', 'I hate tooltips');
}
// Check if a data value has been set. It will return the value if set or the default value if not set
// public function get($key, $defaultValue = null)
$age = (int) $layout->get('age', 0);
// You can still pass additional data on render and this data will be merged
$data = array(
'sex' => 'almost never',
'height' => 2.05
)
// Layout will receive: name, tooltip, sex & height values
echo $layout->render($data);
Note that to be able to use the set & get methods the data passed to layouts has to be ALWAYS AN ARRAY. Otherwise the system will only use the data received in the render method to keep B/C.
Now debug messages can be cleared dynamically with $layout->clearDebugMessages()
. Now that method is only used internally but may be useful even if it's only to people extending JLayoutFile
Now all the file searches are cached by the system so if the same layout is searched in the same include paths and with the same suffixes it will return a cached path.
This was a proposal by @javigomez and I found it really useful for frontenders I've been working with. When debug mode is enabled from backend joomla configuration all the layouts will have an HTML comment before and one HTML after.
Something like:
<!-- Start layout: /home/roberto/www/jcms3x/layouts/joomla/content/info_block/block.php -->
<dl class="article-info muted">
<dt class="article-info-term"> Details </dt>
</dl>
<!-- End layout: /home/roberto/www/jcms3x/layouts/joomla/content/info_block/block.php -->
Now there is a method to automatically load suffixes based on the active language. Usage:
$layout = new JLayoutFile('joomla.content.info_block.block');
// Load the language suffixes
$layout->loadLanguageSuffixes();
// Render the layout
$layout->render(array());
/*
When en-GB language is enabled this will be the suffixes applied
Suffixes: Array
(
[0] => en-GB
[1] => en
[2] => ltr
)
*/
/*
Sample file search:
Searching layout for: joomla/content/info_block/block.en-GB.php
Searching layout for: joomla/content/info_block/block.en.php
Searching layout for: joomla/content/info_block/block.ltr.php
Searching layout for: joomla/content/info_block/block.php
*/
I added also a method to generate automatic suffixes based on the version of the system. Usage:
$layout = new JLayoutFile('joomla.content.info_block.block');
// Load the version suffixes
$layout->loadVersionSuffixes();
// Render the layout
$layout->render(array());
/*
Suffixes loaded for latest Joomla:
Suffixes: Array
(
[0] => j350
[1] => j35
[2] => j3
)
*/
/*
Sample file search:
Searching layout for: joomla/content/info_block/block.j350.php
Searching layout for: joomla/content/info_block/block.j35.php
Searching layout for: joomla/content/info_block/block.j3.php
Searching layout for: joomla/content/info_block/block.php
*/
Sometimes is useful to know the id of the layout being rendered. I added a method to do it. Sample usage:
$layout = new JLayoutFile('joomla.content.info_block.block');
// Will print joomla.content.info_block.block
echo $layout->getLayoutId();
I have also deprecated the old setLayout()
method in favour of setLayoutId()
so describes better what it does.
Returns an array of loaded suffixes. Sample usage:
$layout = new JLayoutFile('joomla.content.info_block.block');
// Load version suffixes
$layout->loadVersionSuffixes();
// Print the active suffixes
print_r($layout->getSuffixes());
/*
Array
(
[0] => j350
[1] => j35
[2] => j3
)
*/
Now there is also a method to check if debug is enabled. It makes sense mainly for internal use. Sample usage:
public function addDebugMessage($message)
{
if ($this->isDebugEnabled())
{
$this->debugMessages[] = $message;
}
return $this;
}
Also there is now a method to change debug mode without adding the debug setting to the options :
$layout = new JLayoutFile('joomla.content.info_block.block');
// Enable debug mode
$layout->setDebug(true);
echo $layout->render(array());
Additionally there are new methods to fastly debug a layout.
$layout = new JLayoutFile('joomla.content.info_block.block');
// Standard rendering
echo $layout->render($data);
// Render with debug information
echo $layout->debug($data);
There is also a new method in the JLayoutHelper
class:
echo JLayoutHelper::debug('joomla.content.info_block.block', $data);
So only replacing the render with debug you see the output with the debug info.
This has been removed because it causes tests to fail and there is no time before v3.5
This was a request from @alex-filat
Now the debug messages are only added and returned when debug is enabled.
Status | New | ⇒ | Pending |
Labels |
Added:
?
|
PR is currently failing because of downtime in pecl.php.net - as you can see the rest of the tests pass in other PHP versions - so assume they will pass in 5.5 and 5.6 for now and we will restart the build when it comes online
I have tested this item successfully on 825719f
Applied patch. Viewed some articles which used JLayouts by default to ensure that existing layouts continued to work as expected successfully.
Tested in my own module which currently is forced to override JLayoutFile to change the include paths (https://github.com/JoomJunk/shoutbox/blob/development/mod_shoutbox/libraries/layout.php) and tested replacing it with setIncludePaths
and it worked successfully. I also tested doing version specific overrides here.
Enabled Debug mode and successfully observed the debug html comments - which are actually a great idea. Kunena use a similar concept which is super useful
Overall really useful and a successful test. Thanks @phproberto
I have tested this item successfully on 825719f
Works great @phproberto I realy like the html Debug comments!
I have just send a quick CS PR here: phproberto#3 if we can get that in we can move this RTC.
Milestone |
Added: |
Milestone |
Added: |
Category | ⇒ | Layout Libraries |
This PR has received new commits.
Status | Pending | ⇒ | Ready to Commit |
Thanks @phproberto -> RTC
Labels |
Added:
?
|
Status | Ready to Commit | ⇒ | Closed |
Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2015-11-02 11:47:42 |
Closed_By | ⇒ | roland-d |
Labels |
Removed:
?
|
I'm going to remove the debug requirement to render debug messages because it doesn't really improve performance and causes tests to fail.