This approach offers a more powerful solution versus the classical drop down boxes chained together for a number of reasons: it takes significantly less space in the page; it can contain any number of nested levels, navigation would not be harmed; it can be styled according to the overall page design from CSS and most of all, it looks better.
The purpose of the plugin is to replace the classic chained dropdown lists that have 2 or more selects and get populated with options once you select an option from a previous one.
If an option is selected and the script that verifies the user’s entry returns an error (for example the e-mail address is invalid), the plugin offers the possibility to display the last selected option leaving it selected and accessible in POST / GET depending what method you used on the form.
To retrieve the value selected by the user, you need to give a variable name and retrieve it from POST / GET based on that name. When creating the class instance, that variable name is specified using the selectName parameter. For example, if you give this parameter a value like “selected_option”, when the user submits the form, you can retrieve the selected options from $_POST['selected_option'].
The tree structure generated by the PHP script is basically a multidimensional array having as keys the nodes ids (that can come from a database) and as values the children array. The ChainSelect plugin assumes that the main node is 0 and all other nodes descend from it. Once a value is set as id (key) for an entry, it cannot be used again.
1 2 3 4 5 6 7 8 9 10 11
<?php // this is the main node and has 0 as key always $tree = array(1=>'First', 2=>'Second', 3=>'Third'); // children of First, the key is 1 same as the key First has in the array above $tree = array(4=>'First child in First parent', 5=>'Second child in First parent'); // children of Second; we add only one $tree = array(6=>'First child Second parent'); // we add a child to the child of Second $tree = array(7=>'First child from First child of Second parent'); // got it? good. ?>
The plugin parameters are:
- element: the div that mimics the dropdown (default:null)
- optionsContainer: id of the element containing all the options (default:null)
- selectName: POST/GET variable name (default:null)
- selectedValue: the selected value set as default value (ie: if page refreshed and you want to keep the option) (default:null)
- selectedMessage: the selected text corresponding to the selectedValue id(ie: if page refreshed and you want to keep the option) (default:null)
- defaultMessage: default message displayed into the fake select (default:’Please select an option’)
- navHome: title for the first panel of options (default:’Main options’)
- optionsURL: the URL to the file that generates the JSON string (default:null)
- fromTop: aditional distance between the fake select and the options container (default:15)
To use this plugin, add the MooTools framework and ChainedSelect.js into the head section of the document and create an instance of the plugin with at least the parameters stated below:
1 2 3 4 5 6 7 8 9
The styling of the options list is made based on the optionsContainer parameter and all inner elements are styled as descendant from it. So basically, if you want to use a different id for the optionsContainer you will change the id in the stylesheet and leave all the other CSS styling names as they are.
July 20′th 2009
- new parameter added keepSelection. When set to true, after selecting an options, it will keep the option selected inside the options list. When set to false, after selecting, it will reset to the first level of options.
September 1’st, 2009
- new parameter added displayHistory. When set to true, after selecting an option it will display the full path to it ( ie: Parent1 – Parent2 – Selected option ).