Appendix C. JHtml Methods
The folder libraries/joomla/html contains a number of useful methods for creating Joomla! applications. In this appendix, we briefly describe some of them. Note that these methods are all static methods. The details for using these methods are documented at the site http://api.joomla.org/li_Joomla-Platform.html.
Calling JHtml Methods
JHtml methods are designed to be convenient to use by designers and others who are not experienced PHP coders. One handy thing about these methods is that they can be automatically imported as needed. The syntax for this is simple. Consider this example:
<?php echo JHTML::_('string.truncate', $item->introtext, $params->get('introtext_limit')); ?>
Here we use the _() method of JHtml (libraries/joomla/html/html.php) to call the truncate() method of the JHtmlString class (libraries/joomla/html/html/string.php).
The first argument of the _() method is the identifier for the method to call. It can have an optional prefix before a period, followed by the method name. The prefix is the name of the class, by default in the folder libraries/joomla/html/html. In this case, the prefix of “string” means the class name is JHtmlString. The second part of the identifier is the method name—in this case, truncate().
If there is no prefix, we call a method in the JHtml class itself. For example, this code
<?php echo JHtml::_('link', $url, $v, array('target' => 'helpFrame'));?>
calls the link() method of JHtml.
The rest of the arguments passed to the _() method get passed through to the method being called.
Custom JHtml Classes
It is easy to add our own JHtml classes using the addIncludePath() method. For example, this code from the administrator/com_admin component
JHtml::addIncludePath(JPATH_COMPONENT.'/helpers/html'),
adds the path administrator/com_admin/helpers/html to the include path. That means we can put custom JHtml classes into this folder and call them with the JHtml::_() method. When we do that, they will be loaded automatically, just like core JHtml classes.
For example, this line in the administrator/components/com_admin/views/sysinfo/tmpl/default_directory.php file
<?php echo JHtml::_('directory.message',$dir,$info['message']);?>
calls the message() method of the custom JHtmlDirectory class in the administrator/com_admin/helpers/html folder.
JHtml Class Methods
Link
This method creates an HTML anchor element. It has three arguments: (1) the URL, (2) the text for the element, and (3) an optional associative array of attributes for the element. For example,
$output = JHtml::_('link', JRoute::_($url), $text, $attribs);
Image
This method creates an HTML image (img) element. It has five arguments: (1) the file for the src attribute, (2) the alt attribute, (3) an associative array of other attributes, (4) a boolean to indicate whether the path is relative, and (5) a boolean to indicate whether to search for an override file in the template. For example,
$text = JHtml::_('image','system/new.png', JText::_('JNEW'), NULL, true);
Stylesheet
This method creates a <link rel="stylesheet" style="text/css" /> element. It has five arguments: (1) path to the CSS file, (2) array of optional attributes, (3) boolean to indicate if the path is relative to the media folder, (4) boolean to indicate whether to search for an override in the template folder, and (5) boolean to include browser-specific CSS files. For example,
JHtml::_('stylesheet',$component.'/administrator/categories.css', array(), true);
Script
This method creates an HTML script element. It has five arguments: (1) path to the JavaScript file, (2) a boolean to tell whether to load the MooTools framework, (3) a boolean to indicate if the path is relative to the media folder, (4) a boolean to indicate whether to search for an override in the template folder, and (5) a boolean to include browser-specific JavaScript files. For example,
JHtml::_('script','media/popup-imagemanager.js', true, true);
Calendar
This method creates a pop-up calendar using the MooTools calendar behavior. It has five attributes: (1) current date value, (2) name of the text field, (3) id of the text field, (4) date format, and (5) optional array of attributes. For example,
return JHtml::_('calendar', $this->value, $this->name, $this->id, $format, $attributes);
Date
This method displays a date with a given format and time zone. It has four arguments: (1) the date to show, (2) the format, (3) the time zone, and (4) a boolean to indicate whether to use the Gregorian calendar. For example,
<?php echo JHtml::_('date',$item->created, JText::_('DATE_FORMAT_LC4')); ?>
HTML Folder Classes
The folder libraries/joomla/html/html is the folder where the JHtml::_() method searches by default for classes and methods. Some of the most frequently used classes are discussed briefly in this section. Each of these class names begins with the letters “JHtml”.
Batch
Implements the batch operations in the back-end manager screens. Includes access(), item(), and language() methods to create the batch operation markup for changing access levels, categories, and language. For example,
<?php echo JHtml::_('batch.access'),?>
<?php echo JHtml::_('batch.language'), ?>
Behavior
Implements the various JavaScript behaviors. See Chapter 12 for more information.
Category
Returns a cached list of categories for a given extension. Used to create list boxes for categories in back-end manager screens. For example,
<?php echo JHtml::_('select.options', JHtml::_('category.options', 'com_banners'), 'value', 'text', $category);?>
Content
Has one method, prepare(), that fires the onContentPrepare plugin event. Used to fire this event for nonarticle content, such as contacts, custom HTML modules, and others. For example,
$module->content = JHtml::_('content.prepare', $module->content);
ContentLanguage
Has one method, existing(), that creates a list of existing languages. Used to create the list box for language selection. For example,
<?php echo JHtml::_('select.options', JHtml::_('contentlanguage.existing', true, true), 'value', 'text', $this->state->get('filter.language'));?>
Has one method, cloak(), that replaces an e-mail address with a link where the e-mail address is cloaked. For example,
$item->email_to = JHtml::_('email.cloak', $item->email_to);
Form
Has one method, token(), that displays a hidden token field to reduce the risk of cross-site request forgery security exploits. For example,
<?php echo JHtml::_('form.token'), ?>
Grid
Contains a number of methods used for creating controls for the various manager screens in the back end. Methods include the following:
• boolean(): Creates clickable on/off controls—for example, to enable or disable a user
• sort(): Creates clickable links in column headings that allow the table to be sorted by that heading
• id(): Creates the checkbox for items in a grid
• order(): Creates an icon for saving a reordered table in a manager screen
Image
Contains two methods, admin() and site(), that load either the template override image or the default image.
JGrid
Provides a number of methods used in back-end manager screens. Some methods replace methods with the same name in Grid. Methods include the following:
• checkedOut(): Shows a check-out icon that allows an authorized user to check an item in by clicking
• isDefault(): Indicates if an item is currently the default setting (for example, a language or template)
• published(): Shows a clickable published icon that allows an authorized user to toggle the published state of an item
• publishedOptions(): Shows an array of standard published state filter options
List
Provides methods for creating different select lists. Contains a method called ordering() that creates the options list for selecting ordering when editing an item (for example, a contact).
Select
Provides methods for creating HTML selection lists. Methods include the following:
• genericList(): Creates an HTML selection list
• groupedList(): Creates an HTML selection list for a nested array; used, for example, to show alternative layouts grouped by template
• options(): Creates the option tags for an HTML select list
• radioList(): Creates an HTML radio list
Sliders
Provides the methods for creating the slider controls used in the back end for parameters and options. Methods include the following:
• start(): Creates the panels and loads the slider JavaScript code
• panel(): Starts a new panel
• end(): Ends the current panel
String
Provides two methods for working with strings in layouts:
• abridge(): Shortens a text string showing the first and last part of the string, separated by . . . (for example, “Really Long, Long Title” becomes “Really . . . Title”)
• truncate(): Truncates a string to a given length and closes any open HTML tags
Tabs
Provides the methods used to create tabs—for example, in the Global Configuration screen. Methods include the following:
• start(): Creates the panels and loads the slider JavaScript code
• panel(): Starts a new panel
• end(): Ends the current panel