A tutorial for service.ddlist.jquery - Dropdown Select List

Version: 1.1.2

July 11, 2016

Overview

service.ddlist.jquery is a jquery component that provides the functionality of a dropdown list control. It can be instantiated in 2 ways:

• From a <select> element whereby the various list items are defined by one or more <option> elements.
• By means of any container element (e.g. a <div>) whereby the list items are defined through a JSON object (array).

In both cases the plugin supports the expected 'text', 'value', and 'selected' attributes for the list items but also allows additional 'description' and 'image' attributes.

In case the list is specified through <option> elements inside a <select> element then the plugin uses the well-known technique whereby the <select> element will be hidden and the list is 'reconstructed' by means of a jquery-generated <ul> list inside a <div> container.
In case the list is defined through a JSON array then the selector element will also be hidden and the <ul> list will be populated from the JSON array.

This plugin is developed with ddslick as example. It takes over some key features but also improves some aspects:

• Although the <select> will be hidden the plugin updates the 'selected' attribute of the original <option> element when a list item is selected. This means that correct state information will always be passed to the server when the <select> element is part of a submitted form.
• The plugin supports the 'disabled' attribute in the <select> element.
• The idea to support images (and description) using HTML5 data-imagesrc (and data-description) is completely based on ddslick.
• Once constructed and presented to the user the list items can be replaced/updated by invoking a setItemsSource plug-in method. The method expects the new items to be defined in a JSON object/array.
• This plugin is considerably simpler with respect to the classes that it injects in the DOM.
• Styling is assumed to be handled by a very limited set of classes in CSS, and not through plugin configuration/initialization; i.e. except for the width property other 'styling' options are not supported in the plugin constructor.

Not supported

The following features are not supported:

• Selector elements not having an 'id' attribute - The element which you bind to the plugin must therefore have an 'id' attribute.
• Multi-select (e.g. 'multiple' attribute in <select> element).
• 'Size' attribute in <select> element - You have to style the dropdown list with a 'max-height' if you want to limit the number of visible options.

Size

The minified version of the plugin is less than 5kB.

Demo

Click here for a demo.

Download

You can download the latest version of the plugin at GitHub.

Usage

To use the plugin start with adding the following in your header section:

<link rel="stylesheet" type="text/css" href="[your-path]/service.ddlist.jquery.css" />
<script src="[your-path]/service.ddlist.jquery.min.js"></script>

1. Using a select with option elements

In your html, define the dropdown list in the usual way; i.e:

<select id="myList">
  <option value="0">Text 0</option>
  <option value="1" selected="selected">Text 1</option>
  ...
  <option value="9">Text 9</option>
</select>

Then, write some javascript to construct the plugin object and link it to the dropdown list.

<script type="text/javascript">

  // Execute on page load
  $(function () {

      $('#myList').ddlist({
        width: 270,
        onSelected: function (index, value, text) {
          // Do something with selected option
          ...
        }
      });

  });

</script>

Force default selected option

There are 3 possible ways how the plugin can be told which of the listed options has to be displayed in its 'selection' element:

• If one of the option elements has the 'selected' attribute set, then that option will be taken.
• You can force a specific option to be 'selected' when you pass property 'selectionIndex' during plugin initialization.
• If none of the above methods apply, then the first option will be taken.

Example 1:

<select id="myList">
  <option value="0">Red</option>
  <option value="1" selected="selected">Green</option>
  <option value="2">Blue</option>
</select>

In example 1, 'Green' will be displayed in the selection element.

Example 2:

<select id="myList">
  <option value="0">Red</option>
  <option value="1">Green</option>
  <option value="2">Blue</option>
</select>

<script type="text/javascript">
  // Execute on page load
  $(function () {
      $('#myList').ddlist({
        width: 270,
        selectionIndex: 2,
        onSelected: function (index, value, text) {
          // Do something with selected option
          ...
        }
      });
  });
</script>

In example 2, 'Blue' will be displayed in the selection element.

Additional option attributes: description and image

In addition to the normal option text (which is the text between the opening and closing option tags) you can also specify 1 description and 1 image string for each option. You must specify this using HTML5 'data-imagesrc' and 'data-description' attributes as shown next.

<select id="myList">
  <option value="0" data-imagesrc="/images/option0img.png" data-description="A description for the option">text - 0</option>
  ...
  <option value="4" data-imagesrc="/images/option4img.png" data-description="A description for the option">text - 4</option>
</select>

2. Using a JSON items list

First, provide an empty container element. This can be a <select>, a <div>, etc.

<select id="myList"></select>

Then, write the necessary javascript to create a JSON object that holds the list items. Since this is simply javascript there are numerous ways how you get this object: create it statically, get it from an AJAX call to a server, etc.

The JSON object must be an array in which each entry defines a list item. Each list item must be a javascript object that holds a set of properties as follows:

var jsonItemsSource = [
  { text: "string",
    value: "string",
    selected: true/false,
    description: "optional string",
    imageSrc: "url to a picture" },
  ...
  { text: "string",
    value: "string",
    selected: true/false,
    description: "optional string",
    imageSrc: "url to a picture" },
];

In the above JSON array only the keys 'text' and 'value' are mandatory for each entry.

The code for constructing the plugin then look as follows:

<script type="text/javascript">

  // Execute on page load
  $(function () {

      $('#myList').ddlist({
        width: 270,
        itemsSource: jsonItemsSource,
        onSelected: function (index, value, text) {
          // Do something with selected option
          ...
        }
      });

  });

</script>

Force default selected option

As with the <select><option> approach 3 methods are provided to configure the 'selected' list item when using a JSON array:

• Specify the index during plugin initialization.
• Specify in the item's object (in the JSON array) the 'selected' key with the value set to 'true'.
• If nothing is specified then the first item will be selected.

Additional option attributes: description and image

The 2 additional properties 'image' and 'description' can be specified for each list item in the JSON array by providing values for the keys 'description' and 'imageSrc'.

Update dropdown list

You can replace the content of a constructed dropdown list by invoking the setItemsSource method. The method expects as argument a JSON array that holds the new list entries. The javascript call looks as follows:

$('#myList').ddlist('setItemsSource', jsonItemsSource);

Styling

To style the dropdown list the plugin comes with a CSS file that contains various classes to present the internal elements of the list. The classes are inserted by the plugin but if you want to setup your own styles you need to understand how the list is defined inside the DOM.

<div id="ddList-[select-id]" class="ddListContainer">
  <a>
    <img src="option-image-url" />
    <label>option-text</label>
    <small>option-description</small>
  </a>
  <span class="ddListArrow"></span>
  <ul>
    <li>
      <a>
        <img src="option-image-url" />
        <label>option-text</label>
        <small>option-description</small>
    </li>
    ...
    <li>..</li>
  </ul>
</div>

• The root container will be assigned an element id that consists of "ddList-" followed by the id of the <select> element.
• The first <a> tag forms the 'selection' part of the dropdown list (the part that is always visible).
  • The <label> tag is there to hold the option text.
  • The <img> and <small> tags are optional. They are present when you specify and image and/or a description string for an option.
• The second <span> element is to construct the 'up' or 'down' arrow of the dropdown.
• The third <ul> element holds all the options from the <select> element. Each option is held inside an <a> element that is constructed in the same way as the <a> tag of the 'selection' part.

If you look to the CSS file you will find styles for the following classes:

• ddListContainer - This class is applied to the root container.
• ddListDisabled - A class that is added to the root container when the dropdown list is disabled.
• ddListIsOpen - A class that is added to the root container when the dropdown list is opened.
• ddListArrow - You can style the selection arrow with this class.
• ddListOptionIsSelected - This classes is added to the <a> element of the option <li> that has been selected.

Hide top selection box when activated

You can configure the plugin to hide the top selection box while in the active state; i.e. when the user taps the control and the option's list is presented. Initialize the plugin with the option hideTopSelectedElement set to true when you want this type of style.

API

Initialization method

[jqObject(s)].ddlist(options)

The options argument is a javascript associative array (an object with key/value pairs) that allows you to initialize the plugin with some properties.

Properties

width

Type: Integer
Default: 260
This property defines the width of the dropdown list.

---

itemsSource

Type: Object
Default: null
This property references a JSON array that holds all the list items. When provided, it is used to populate the dropdown list with entries that are coming from a JSON array. The array and its content must have the format defined in chapter 'Using a JSON items list' of this document.

---

selectionIndex

Type: Integer
Default: 0
This property forces the component to select the item which corresponds with the given index (position).

---

disabled

Type: Boolean
Default: false
When you pass this option with a value of 'true' then the dropdown list is disabled.

---

showSelectionTextOnly

Type: Boolean
Default: false
When set to false this property instructs the plugin to show in its 'selection' element the text of the selected item and a possible image and description.
When set to true only the item's text is displayed.

---

hideTopSelectedElement

Type: Boolean
Default: false
When set to false this property instructs the plugin to permanently show the selected option in a seperate element box. When activated the options list will be presented right underneath the top selection box.
When set to true the top selection box is only visible when the dropdown list is inactive. It will be hidden when the user opens the list.

---

onSelectedOnInit

Type: Boolean
Default: false
When set to false this property instructs the plugin to not invoke the onSelected callback during initialization.
When set to true the callback is invoked.

---

onSelected

Type: callback function
Signature: onSelected: function (index, value, text) { }
index: The index (position) of the selected item in the options list.
value: The value of the selected item as defined in its <option> element.
text: The text of the selected item.
This callback is called when the user selects an option. If property onSelectedOnInit is set then the callback is also called when the plugin is initialized and when the list entries are (re-)configured as a result of calling the plugin's setItemsSource method.

Other methods

enable

Signature: [jqObject(s)].ddlist('enable', isEnabled);
isEnabled: Boolean - Set to true if you want to enable the dropdown list. Set to false when the list must be disabled.
You can enable/disable the plugin using this method.

---

select

Signature: [jqObject(s)].ddlist('select', { index: integer, value: string, text: string });
index: Integer - When this property is provided it specifies the index (0..) of the item that must be selected.
value: String - When this property is provided it specifies the value of the item that must be selected.
text: String - When this property is provided it specifies the text of the item that must be selected.
This method can be used to tell the plugin to select a given item in the dropdown list. You can specify the item either through its index, its value, or its text.

---

setItemsSource

Signature: [jqObject(s)].ddlist('setItemsSource', itemsSource);
itemsSource: Object - The parameter references a JSON array that holds all the new list items. The array must contain list entries as defined higher in this document.
This method can be used to initialize, update and replace the list items of the dropdown list. You can invoke this method at any point in time on a constructed plugin.

Comments

comments powered by Disqus