How do I build a select drop-down, radio button or checkbox group?

Written Oct 31, 2012 04:39

These three form elements: select drop-downs, checkbox groups and radio button groups all accept lists of options i.e. value+label pairs. This FAQ shows you several ways in which ChronoForms can create option lists. Most of the FAQ will look at select drop-downs but the same methods can be used with checkbox groups or radio button groups.

Although they look different these three elements are similar in the way that they work. Radio button groups and standard select drop-downs allow the user to make a single selection from a list of options; checkbox groups and select dropdowns with the 'multiple' option allow several options to be selected.

Simple label list

The simplest way of creating an option list is to type a list of labels into the Element Options box:

Blue
Yellow
Red
Green

This will generate a set of options where the value - the result that will be returned by the form if the option is selected - is the same as the label - the text displayed for the user to see.

This is simple to do and will work very well in some cases.

You should not use a simple label list if any of the labels contain special characters (quotes, slashes, commas, etc.) or they are very long. Use a value + label list instead.

Value + label list

This is the most common kind of option list and is used in the default values shown in the element Options boxes. Here each line has value=label which lets you use simple short values that are clear and unambiguous combined with descriptive text in the labels.

a4yr=A4 yellow ruled pad
a4wp=A4 white plain pad
a5gs=A5 green squared pad
a4wm=A4 music ruled pad

Dynamic Data list

The previous lists will work provided that you have a fixed list of options. Often though the options will change over time or depending on some other condition and you want to have the flexibility to change them when the form is loaded. To support this elements all have a Dynamic Data tab where you can define a set of options that will be added when the form loads.

Apart from the Enable/Disable select box the Dynamic Data tab has three boxes:

Data Path: the data to create the options needs to be in the $form->data[] array and this tells ChronoForms where to look for it.
It might have a simple model ID like 'my_option' if it is in the $form->data['my_option'] sub-array, or like 'my_options.aaa' if it is in the sub-sub array $form->data['my_options']['aaa']. The more complex model IDs are usually used with option data retrieved from a database table (see below).
Value Key: this tells ChronoForms which entries contain the value.
If this is, for example, 'value' then it will refer to an entry like $form->data['my_option'][0]['value'] where the [0] is the sequence number of this value+label pair.
Text Key: this tells ChronoForms which entries contain the label text.
If this is, for example, 'text' then it will refer to an entry like $form->data['my_option'][0]['text'].

The most important thing here is just to understand the purpose of the boxes, you only need the more detailed information if you are planning to hand-write the code to create your dynamic option list.

Dynamic Data from a database table

You can use the ChronoForms DB Multi Record Loader action (or the DB Read action in CFv5) to create a data-set to use as your option list. You need to drag a copy of the action into the On Load event of your form and move it up before the Show HTML action. On the action General Tab you need to set at least the Table and Fields boxes (you may well need to complete others to select the records that you want to use).

For example, we might select the jos_content table and then add id,title in the Fields box. Note that the Model ID will default to josContent unless you set another value.

Save the action and go back on the Dynamic Data tab on the element. Enable the Dynamic Data; enter the Model ID josContent in the 'Model ID' box, then id in the 'value' box and title in the 'text' box.

Save the element and test the form, you should see a list of options that display the article titles as labels and return the matching article id when the form is submitted.

If you want to create a simple list where the value and label are the same you can just put title in both of the 'value' and 'text' boxes.

Ready made lists (for advanced developers)

I have a Custom action that you can buy if you often need to create select drop-downs. It comes complete with a set of fifteen commonly used lists like Countries, US states, time-zones, months, 'levels of agreement' and more; it has multi-lingual list support; and has built-in short-cuts for numeric ranges, year ranges, and article lists. There's an example form {rokbox text=|here| size=|1000,600| }http://greyhead.org/index.php?option=com_chronoforms&chronoform=custom_select_gh&tmpl=component{/rokbox}and you can get more info and buy the action {rokbox text=|here| size=|1000,600| }http://greyhead.net/how-to-docs/cfv4-custom-select-gh-action{/rokbox}

Simple double drop-down

A double drop-down is a pair of linked select drop-downs (usually these are select boxes rather than check box or radio button groups). When the first drop-down is changed the option list in the second drop-down changes to match. For example, the first drop-down is a list of states, and the second drop-down shows a list of the counties/regions in the state.

ChronoForms has a built-in Dynamic Dropdown action in the Power Fields group. In the simplest use you can ignore the two AJAX boxes and enter your lists of options directly into the Extra Options Extension box. The format is to add one source value and the matching list of value+name pairs on each line:

state_1:region_1a=Region A,region_1b=Region B,regions_1c=Region C
state_2:region_2x=Region X,region_2y=Region Y

Note: you need to add entries in the Field ID box of each of the seelct drop-down elements and you should put an entry like ? in the Show Empty box of the first element.

Please see this FAQ for a more detailed explanation.

Double drop-down with Ajax

If the options list are long, or are themselves dynamic then you can set up the options list using Ajax to get the updated information directly from a database table on the server.

Ajax is the name of a technique that lets JavaScript on the form page in the user's browser talk to your site server to get information that can be used to update the page on the fly. The technical details of this are mostly handled by ChronoForms using the MooTools JavaScript library.

To use Ajax with the Dynamic Dropdown action you need to set Use AJAX? to 'Yes' in the action and add the name of a new form event in the AJAX Event name box. This can be any convenient name, we'll use 'ajax' here.

There is a little bug in the action that means that you must add something to the Extra Options Extensions box, just an 'x' is enough - if the box is completely empty the action will not run correctly.

Save the action then click the Add Event link at the bottom of the Events tab. Set the Event Name to 'ajax' (or the name you just chose).

In the Ajax event we need to do four things:

Get the data we need from the database table
Format the data for the Dynamic Dropdown action
Send the data back to the form
Stop the processing so that we don't send the template code as well.

We'll use a DB Multi Record loader action to ge the data and a Custom Code action for the rest of the code.

For this example the first drop-down has the name and id 'categories' and shows a list of article categories; the second drop-down has the name and id 'articles' and will show a list of article titles in the selected category.

Get the data

We'll add the DB Multi Record Loader action to the 'ajax' event, link it to the #__content table and set the Fields box to id,title. We also need it to select just the articles from the selected category and we can do this with the DB Field and Request Param boxes. The DB Field for the category is 'catid', and the Dynamic Dropdown action will send the selected category id using the name of the first select box so 'categories' goes into the Request Param box. Lastly we can set an Model ID as 'articles' (if you don't set it it will be #_Content - with #_ replaced by your table prefix).

Format the data

We'll add a new Custom Code action into the 'ajax' event for the remaining code.

The data needs to be in the format value=name with each pair on a separate line but the DB Record Loader will return an array so we need to read the array, join the id and title together and put the results on separate lines. Here's the code to do that:

<?php
$results = array();
// the next line set the first 'nothing selected' option.
$results[] = '=??';
foreach ( $form->data['articles'] as $v ) {
  $results[] = $v['id'].'='.$v['title'];
}
$results = implode("\n", $results);
?>

Send the data back

This just takes one line of code:

<?php
echo $results;
?>

Stop the processing

And this takes two more:

<?php
$mainframe =& JFactory::getApplication();
$mainframe->close();
?>

Save everything and test - that's all that's needed.

When you put all the custom code together you can tidy up and remove the ?><?php pairs

<?php
$results = array();
$results[] = '=??';
foreach ( $form->data['articles'] as $v ) {
  $results[] = $v['id'].'='.$v['title'];
}
$results = implode("\n", $results);
echo $results;
$mainframe =& JFactory::getApplication();
$mainframe->close();
?>

There is a short-fall with this approach that it doesn't reload the second drop-down if the form is republished (after a Captcha error for example). There is a working solution for this in this forum post.

FAQs