JHtml and JDocument script/stylesheet/image improvements

[andrepereiradasilva]

Summary of Changes

This PR does some changes to JHtml image, stylesheet and script methods:

• Simplifies methods signatures for B/C and F/C. This will allow to add attribs to JHtml script and maybe more (since the signature is not fixed now) in a simpler way in the future.
• Adds versioning option to stylesheet, script and image methods.
• Deprecates MD5SUM version scheme
• Allows version in urls already with &
• Allows to add inline JS and CSS with inline = true
• Adds more options to generate mediaversion (by Fedik)
• Ability to add other attributes to the script tag (merges PR 8540)
• Allows to add relative path in template (ex: https://github.com/andrepereiradasilva/joomla-cms/blob/jhtml-versio/administrator/templates/isis/index.php#L32)

After this PR you can also scripts like this (the same is valid for stylesheet and image methods):

Scripts

/* 
 * Script default values:
 * - Load framework [framework] = No
 * - Relative paths [relative] = No
 * - Return only path [path_only] = No
 * - Try to load browser specific files [detect_browser] = Yes
 * - Try to load only debug script (not compressed) if debug mode [detect_debug] = Yes
 * - Media version [version] = none [NEW]
 * - Attributes [attribs] = none [NEW]
 *
 * Code examples: 
 * - 1: Load script disabling browser detect (faster).
 * - 2: Load script with framework.
 * - 3: Load script with relative path.
 * - 4: Load script with auto version.
 * - 5: Load script with custom version.
 * - 6: Load script with custom data attributes and id.
 */

/* Current method */
JHtml::_('script', 'media/jui/js/chosen.jquery.js', false, false, false, false, true);
JHtml::_('script', 'media/jui/js/fielduser.js', true);
JHtml::_('script', 'system/passwordstrength.js', false, true);
// Not supported
// Not supported
// Not supported

/* New method */
JHtml::_('script', 'media/jui/js/jquery.minicolors.js', array('detect_browser' => false));
JHtml::_('script', 'media/jui/js/jquery.searchtools.js', array('framework' => true));
JHtml::_('script', 'system/helpsite.js', array('relative' => true));
JHtml::_('script', 'media/jui/js/jquery.ui.core.js', array('version' => 'auto'));
JHtml::_('script', 'media/jui/js/jquery.ui.sortable.js', array('version' => 'v3.5.0'));
JHtml::_('script', 'media/jui/js/sortablelist.js', array('attribs' => array('id' => 'myid', 'data-value' => 'my-values')));

Styles

/* 
 * Stylesheet default values:
 * - Attributes [attribs] = none
 * - Relative paths [relative] = No
 * - Return only path [path_only] = No
 * - Try to load browser specific files [detect_browser] = Yes
 * - Try to load only debug style (not compressed) if debug mode [detect_debug] = Yes
 * - Media version [version] = none [NEW]
 *
 * Code examples: 
 * - 1: Load stylesheet disabling browser detect (faster).
 * - 2: Load stylesheet with relative path.
 * - 3: Load stylesheet with auto version.
 * - 4: Load stylesheet with custom version.
 * - 5: Load stylesheet with custom data attributes and id.
 */

/* Current method */
JHtml::_('stylesheet', 'media/jui/css/jquery.minicolors.css', array(), false, false, false, true);
JHtml::_('stylesheet', 'system/frontediting.css', array(), true);
// Not supported
// Not supported
JHtml::_('stylesheet', 'media/jui/css/jquery.searchtools.css', array('id' => 'myid', 'data-value' => 'my-value'));

/* New method */
JHtml::_('stylesheet', 'media/jui/css/jquery.minicolors.css', array('detect_browser' => false));
JHtml::_('stylesheet', 'system/system.css', array('relative' => true));
JHtml::_('stylesheet', 'media/jui/css/sortablelist.css', array('version' => 'auto'));
JHtml::_('stylesheet', 'media/jui/css/jquery.simplecolors.css', array('version' => 'v3.5.0'));
JHtml::_('stylesheet', 'media/jui/css/jquery.searchtools.css', array('attribs' => array('id' => 'myid', 'data-value' => 'my-value')));

Images

/* 
 * Image default values:
 * - Alternative text [alt] = none
 * - Attributes [attribs] = none
 * - Relative paths [relative] = No
 * - Return html tag without (-1) or with file computing(No). Return computed path only (Yes) [path_rel] = No
 * - Media version [version] = none [NEW]
 *
 * Code examples: 
 * - 1: Load image without alternative text.
 * - 2: Load image with relative path.
 * - 3: Load image with auto version.
 * - 4: Load image with custom version.
 * - 5: Load image with custom data attributes and id.
 */

/* Current method */
JHtml::_('image', 'media/mod_languages/images/icon-16-language.png', '');
JHtml::_('image', 'mod_languages/icon-16-language.png', '', true);
// Not supported
// Not supported
JHtml::_('image', 'media/mod_languages/images/icon-16-language.png', '', array('id' => 'myid', 'data-value' => 'my-value'));

/* New method */
JHtml::_('image', 'media/mod_languages/images/icon-16-language.png');
JHtml::_('image', 'mod_languages/icon-16-language.png', array('relative' => true));
JHtml::_('image', 'media/mod_languages/images/icon-16-language.png', array('version' => 'auto'));
JHtml::_('image', 'media/mod_languages/images/icon-16-language.png', array('version' => 'v3.5.0'));
JHtml::_('image', 'media/mod_languages/images/icon-16-language.png', array('attribs' => array('id' => 'myid', 'data-value' => 'my-value')));

[andrepereiradasilva]

@mbabker how about now. What do you think?
If you have comments or suggestions for improvements please say so. I really would appreciate your help on this.

I tested this PR in the patchtester and all seems fine (php 7).

Note: i did this only on my repo. will not push to joomla repo until is fine.

[mbabker]

This method isn't deprecated, don't add a tag here.

[mbabker]

Leave the since tag alone, this indicates the first version the method was available in the API, not the version it was last changed.

[andrepereiradasilva]

ok i'm making all the changes you said. Thanks a lot.

I would like more if the methods were called like (example):

JHtml::_('script', 'system/somejs.js', array('version' => null);
JHtml::_('stylesheet', 'system/somestyle.css', array('version' => null);
JHtml::_('image', 'system/someimage.png', array('version' => null);

In other words the $fileremaining in the method signature.
But i didn't find a way since the stylesheet already as an array in the second argument. If you have an hint how to solve this i would go that way.

Also do you think a similar signature revision should be made for the four addXxxx(Version) methods in JDocument?

[mbabker]

For stylesheet it'd only work if there were unique (required) keys in both the attribs and new signature's arrays. Since file's the only requirement if you leave that as a separate parameter it's hard to find something to go from.

I'd leave JDocument alone for the moment and just deal with JHtml.

[andrepereiradasilva]

so i can conclude that in your opinion, the only way is to leave as i made in this PR. the other opinion is having different signature for style which i don't want to, because it would be confusing.

[andrepereiradasilva]

ok, found a way
https://github.com/andrepereiradasilva/joomla-cms/blob/jhtml-versio/libraries/cms/html/html.php#L614-L626
Now i can have the more friendly signatures!

JHtml::_('script', 'system/somejs.js', array('version' => 'auto');
JHtml::_('stylesheet', 'system/somestyle.css', array('version' => 'auto');
JHtml::_('image', 'system/someimage.png', array('version' => 'auto');