How to make drop-down boxes ( select elements) with JHTML

Authors:
  • Eric Goldman

6 Jul 2009   ::   Web Development   ::   #Joomla #JHTML #HTML #forms #select

 

JHTML is a very odd class to work with because most of the time you are only calling JHTML::_() and passing some cryptic string that magically gets interpreted into HTML for you. The first thing you should know is that JHTML is a service class, which actually calls a subclass based on the first parameter. I am not sure why you do not natively just call the direct class you want as opposed to this notation which I find odd, but I have decided that I might as well learn all the weird Joomla styles and use them for greater understanding across the community when they look at my code.

So in order to help you get started with this beast, we will look at how to create a drop-down box, formally known as a select element in a form.

Before we get started, it will be a lot clearer if you check out the API from the actual class that will doing the work, we will then work our way back up. When I approached it this way, it made a whole lot more sense later. The class is so obviously named JHTMLSelect. Now, we are going to start with the most basic, yet at the same time most complex method, genericlist. The other methods are just more specific version of this, so if you get can the hang of this you will be pretty well set.

I found the API’s prototype explanation to be pretty confusing, so I will go through it for you in detail:

string genericlist (array $arr, string $name, 
  [string $attribs = null], [string $key = 'value'], 
  [string $text = 'text'], [mixed $selected = NULL], 
  [ $idtag = false], [ $translate = false])
  • $arr: This is an array which will hold the options (each line) of your select list. There is a special way to define this, and I will cover this in a second.
  • $name: This is the element name, as in what you expect to see when you later retrieve the value for processing. In other words, this sets the name attribute of the <select /> tag.
  • $attribs: These are additional attributes you would like to set in the <select /> tag. Most of the time you will just be setting this to null, but the HTML spec has these defined if you want to take advantage.
  • $key: This refers to the value in the $arr that refers to the option value. This is the value that you will be actually receiving when you do processing. In most cases, you will just reset this to “value”.
  • $text: This refers to the value in the $arr that refers to the actual option value you see. In most cases set this to the default of ‘text’.
  • $selected: This sets the element of the list that will be selected when the page loads. This should be one of the values you defined in the $arr array.
  • $idtag: This will set the CSS id for this select, for style, AJAX, etc. I guess you could technically set this in $attribs, but this is clearer for later editing.
  • $translate: This will run the output of each option/line of the <select /> through JTEXT. I would recommend leaving this to false, and individually using JTEXT when you create $arr.

So, still a little confusing I bet. It makes a lot more sense if we look at how $arr is created. Let’s look at any example, then I’ll explain in some more detail:

$arr = array(
  JHTML::_('select.option', 'dog', JText::_('Dog') ),
  JHTML::_('select.option', 'cat', JText::_('Cat') ),
  JHTML::_('select.option', 'rat', JText::_('Rat') )
);

There is that JHTML again, but for right now we don’t need to go into a lot of detail. If you are really interested, this refers to the option method of JHTMLSelect. What we do need to understand is what’s going on here. We are creating an array of values that will populate our select list. Each item is created using the JHTML call. The first parameter is always going to be 'select.option'. The second parameter specifies the option value, which correspond with $key above and is going to be the key for the submitted form array. The third parameter is what the user will actually see. It is a good idea to pass this value to JTEXT here instead of using the $translate=true above, since you might not want every value translated. The choice of even using translation is up to you, but that is the cool thing to do.

Now, I hope its beginning to get a little more clear. Through JHTMLSelect::genericlist() we are loading a list of variables, then defining some attributes that will be used to build the other attributes of the select tag. Now of course, we don’t call JHTMLSelect directly. Instead we call it through JHTML::_(), but that should look a lore more clear now. I will show you an example of creating a simple Yes/No dropdown that store the result as true (0) or false(1).

$currentValue = '0'; //Set this value from DB, etc. 
$arr = array(
  JHTML::_('select.option', '0', JText::_('True') ),
  JHTML::_('select.option', '1', JText::_('False') )
);

 echo JHTML::_('select.genericlist', $arr, 
   'activated', null, 'value', 'text', $currentValue);

You will notice I set a bunch of things to their default values in order to get to the 7th parameter, which will select which option is initially selected. Note, in this case $currentValue must be in the set {0,1} or in the example above {dog, cat, rat}. If the $currentValue is not set to any of the existing options, either the default option will be selected, or no option will be selected depending on the browser default. I wish the order was a little different, but if it’s really that big of a problem, you could write another helper function to format it the way that you like (not recommended for future-proofing or distribution). You will see that the call to JHTML::_() looks the same as JHTMLSelect::genericlist() after the first paramter. The first parameter simply tells JHTML to then call genericlist() function within the JHTMLSelect class, or in other words go to the html select builder, then go to the genericlist function.

The other functions follow a similar logic, and you can also make a radio list here instead of a dropdown. Check out the API for more specifics. I hope I have given you enough to easily comprehend what is going on.

On 26 May 2010, a comment from the old comment system asked the following:

It’s very nice article, but unfortunately it doenst tell the argument definitions for 'select.genericlist'.

JHTML::_('select.genericlist', $arr, 'activated', null, 'value', 'text', $currentValue);
  • select.genericlist - Some thing like keyword
  • $arr - is the data for the select list
  • 'activated' - What is this?
  • null - Why this is null?
  • text - What it is?
  • $currentValue - To default a value?

 

On 26 May 2010, I provided the following response:

Let me try to explain this back up, you need to refer to the definitions above.

  • 'activated' = the name of the form element, so in this case…
  • null ==> this field is for additional attributes that would go inside of the select tag, which could be anything that is allowed
  • 'value' and 'text' are the hash keys (the part inside of square brackets) from the $arr array - these are the defaults when you create $arr using JHTML::_('select.option', 'value', 'text'). You can create a custom array using other variable if you want.
  • $currentValue = is manually set in this example, but it would obviously depend on how you store and retrieve the variable (e.g., could be set using a variable pulled from the database, JRequest, etc.

Hope this helps to clarify. You need to play around and do some live examples to understand what is going on.