byMarc.JS.dropDownCheckBoxList
A pure javascript drop-down checkbox list control for web developers.
Sample1 - simple demo with 6 items
Table of Contents:
  - Features
  - Usage Syntax
  - Minimum and Maximum Required Selections
  - Dynamic Selection Display
  - All and No Selections Text
  - Fixed Header Text
  - Auto Sort
  - Vertical Scrolling
  - Click Outside Auto Cancel
  - Cancel Selection Restoration
  - Select and Deselect All
  - Disabled Select List Items
  - Parent Container
  - Options
  - State Properties
  - CSS Styling
  - CSS Styles
  - Button Classes
  - NuGet Packaging
  - HTML Integration
   
 
Features:
  - allows the user to expand and collapse the checkbox list window,
  - uses a check box list to allow the user to select and deselect multiple options,
  - selections can be cancelled--restoring the previous selections,
  - clicking outside the drop-down cancels and closed the drop-down automatically,
  - applications can require the user to select a minimum number of items and not more than a maximum number of items,
  - items can be sorted by the control, if desired,
  - key elements have class names assigned to control various visual aspects of the control,
  - the control can display fixed text or a comma delimited list of selected values,
  - supports multiple controls on the same page,
  - automatic vertical scrolling,
  - auto cancel on click outside drop-down,
   
   
Usage Syntax:
  To create an instance of the control, the application must call the javascript function createDropDownCheckBoxList. The function accepts a single anonymous parameter. See the section Options, for specific details on each available option. The function will return an HTML element with an instance of the control. The application can then append the control as a child to any element in the DOM. Also, for convenience, the createDropDownCheckBoxList function can append the control to any element by using the parentElement option.
 
  function createDropDownCheckBoxList(data)
 
  Sample2 - minimalist demo with no options*
 
Minimum and Maximum Required Selections:
  The control allows the application to specify a minimum and a maximum number of selections that the user is required to make. This demo forces the user to select between 1 and 3 colors. If the required number of selections hasn't been made, the Ok button is disabled.
 
  Sample3 - demo requiring between 1 and 3 selections*
 
Dynamic Selection Display:
  By default, the control typically displays the selection titles as they are being made. The display will automatically display an ellipsis when the width of the selections exceeds the available space.
 
All and No Selections Text:
  In dynamic selection display mode, the control can optionally display "special" values when all or none of the select list items are selected (including disabled items). A checked disabled item will prevent the noSelectionsText value from being displayed and in contrast, an unchecked disabled item will prevent the allSelectionsText from being displayed.
 
  Sample4 - demo with special selection count text*
 
Fixed Header Text:
  The control can optionally disable the dynamic selection display and simply display a static header.
 
  Sample5 - demo of a fixed header text*
 
Auto Sort:
  The control can automatically sort the select list items. By default, the control does not sort the items.
 
  Sample6 - auto sorting demo*
 
Vertical Scrolling:
  By default, the drop-down will automatically increase in size with the number of select list items. By apply a height to the CSS style, the drop-down height can be fixed. When the number of select list items exceeds the available drop-down height, a scroll bar will appear automatically. For more information see the scrollDiv style in the CSS Styling section.
 
  Sample7 - vertical scrolling enabled demo*
 
Click Outside Auto Cancel:
  The control is designed to automatically cancel the drop-down, when the user clicks anywhere outside of the control. This feature provides the control a somewhat modal functionality. It also assists in the UI by automatically closing the windows when the user expands a different control.
 
Cancel Selection Restoration:
  The drop-down window includes a cancel button. When pressed, the previous selections are automatically restored.
 
Select and Deselect All:
  The drop-down window automatically includes as the first select item a special checkbox that can select or deselect all of the items.
 
Disabled Select List Items:
  The control is capable of rendering select list items disabled by setting the "Disabled" property on specific select list items. The application can specify whether a disabled select list item is checked or not. Disabled select list items perform exactly the same way as non-disabled items except that the user will not be able to check or uncheck disabled item. The "Select All" feature cannot be used to check or uncheck disabled items. When a select list item is disabled, the control appends the byMarc-ddcbl-checkbox-disabled to the checkbox element and the byMarc-ddcbl-itemlabel-disabled to the label element.
 
  Sample8 - disabled items demo*
 
 
  Sample9 - disabled selections with 2 or 3 required selections demo*
 
Parent Container:
  When the control generates the required DOM, it can optionally append the control to a parent container element. This can be accomplished using the parentElement option. If an element is provided in the parentElement property, the control will be appended to it; otherwise, if the parentElement is not null the control will perform a getElementById to retrieve an element from the DOM using the value of the parentElement option. If found, the control will be appended to it.
 
 
Options:
  The control accepts an options anonymous parameter. These options control various features of the control. The following options are supported:
   
 
Property Data Type Description
name string The name that is assigned to the select list items when rendered.
onOkClick string Javascript to execute when the
selectListItems {}[]

The select list items to be displayed. It is an array of anonymous class objects with the following properties:

Property Data Type Description
Text string This is the text to display.
Value string This is the value of the item.
Selected boolean True, to initially set the item as checked; false to initially set as unchecked.
Disabled boolean True, to disable the select list item; false, otherwise.

 
minSelections number Specifies the minimum number of selections required before the Ok button is enabled.
maxSelections number Specifies the maximum number of selections allowed before the Ok button is disabled.
noSelectionsText string The text to display, when there are no items selected. Ignored, if fixedHeaderText is specified.
allSelectionsText string The text to display, when all item are selected. Ignored, if fixedHeaderText is specified.
parentElement html element or string If null, the control will not be added as a child to any elements. If a string is specified, a call to getElementByID will be used to retrieve an element from the DOM and this property will be updated to a reference of the element; otherwise, a reference to an html element is required.
autoSort boolean True, for the control to sort the select list items; false, otherwise. False, by default.
fixedHeaderText string If specified, the display will always show this value regardless of the selected items.
 
State Properties:
  The control uses an anonymous object to maintain state. The table below identifies the variables used:
   
 
Property Data Type Description
selectedCount number Indicates the number of items selected.
displayElement html element The element used to display the value.
selectAllElement html element The (Select All) select list item.
buttonElement html element The element used for the button.
isCollapsed boolean Indicates the state of the drop-down.
restoreValue string Stores the value to be restored, if the drop-down is cancelled.
dropDownElement html element The drop-down element that is hidden and shown.
element html element The top-most element that contains the entire control.
okButtonElement html element The Ok button element.
cancelButtonElement html element The Cancel button element.
   
CSS Styling:
  The control uses CSS to style the control and to also support application specific configuration. By making use of CSS selectors and the parent element ID, CSS styling can be selectively applied to one or more controls. See the Vertical Scroll Bar section for a sample of this feature.
   
  #sample7 .byMarc-ddcbl-scrollDiv {
height: 50px;
}
   
CSS Styles:
  The following table below identifies the class names used by the control.
   
 
Style Description
byMarc-ddcbl-table The top-most table.
byMarc-ddcbl-commandsTableRow The <tr> used to contain the Ok and the Cancel buttons.
byMarc-ddcbl-displayDiv The <div> used to display the value. It provide the container functionality so that the inner <span> element can render an ellipsis when needed.
byMarc-ddcbl-item The <td> elements that contain the checkboxes.
byMarc-ddcbl-itemRow The <tr> element that contains a select list item.
byMarc-ddcbl-checkbox-disabled The class that is added to the checkbox element when the select list item is disabled.
byMarc-ddcbl-checkbox Each checkbox <input> element.
byMarc-ddcbl-itemlabel The <td> elements that contain the labels for each select list item.
byMarc-ddcbl-itemlabel-disabled The class that is added to the <td> element for a select list item label when the select list item is disabled.
byMarc-ddcbl-commandsTableCell The <td> element that contains the Ok and Cancel buttons.
byMarc-ddcbl-command The <input> elements for the Ok and Cancel buttons.
byMarc-ddcbl-command-disabled The class that is added to the <input> Ok button when the Ok is disabled.
byMarc-ddcbl-dropdown The drop-down <table> element that is hidden and shown on demand.
byMarc-ddcbl-inputbox The <tr> element that holds the display and the drop-down button.
byMarc-ddcbl-input The <span> element that displays the ellipsis when needed.
byMarc-ddcbl-scrollDiv This style is applied to the <div> control that contains all of the select list items. This is also the control that will provide the vertical scrolling functionality. By default, no height is applied. See the Vertical Scrolling section for more details. By appling a height or a max-height style, the scrolling functionality can be activated.
   
Button Classes:
 

In addition to the CSS styles above, the drop-down button is assigned a class name depending on the current state of the control. There are 2 internal properties (see the State Properties section for more details) that determine the corresponding state: isCollapsed, selectedCount. The table below indicates which class names are assigned for each state. The button element will be assigned five class names--one from each group below:
   
 
Class Name Collapsed Expanded All Items Selected No Items Selected Some Items Selected
byMarc-ddcbl-button Yes Yes Yes Yes Yes
           
byMarc-ddcbl-button-collapsed Yes   Yes Yes Yes
byMarc-ddcbl-button-expanded   Yes Yes Yes Yes
           
byMarc-ddcbl-button-collapsed-all Yes   Yes    
byMarc-ddcbl-button-collapsed-some Yes       Yes
byMarc-ddcbl-button-collapsed-none Yes     Yes  
byMarc-ddcbl-button-expanded-all   Yes Yes    
byMarc-ddcbl-button-expanded-some   Yes     Yes
byMarc-ddcbl-button-expanded-none   Yes   Yes  
           
byMarc-ddcbl-button-all Yes Yes Yes    
byMarc-ddcbl-button-some Yes Yes     Yes
byMarc-ddcbl-button-none Yes Yes   Yes  
           
byMarc-ddcbl-button-collapsed-notAll Yes     Yes Yes
byMarc-ddcbl-button-collapsed-notSome Yes   Yes Yes  
byMarc-ddcbl-button-collapsed-notNone Yes   Yes   Yes
byMarc-ddcbl-button-expanded-notAll   Yes   Yes Yes
byMarc-ddcbl-button-expanded-notSome   Yes Yes Yes  
byMarc-ddcbl-button-expanded-notNone   Yes Yes   Yes
           
byMarc-ddcbl-button-notAll Yes Yes   Yes Yes
byMarc-ddcbl-button-notSome Yes Yes Yes Yes  
byMarc-ddcbl-button-notNone Yes Yes Yes   Yes
 
NuGet Packaging:
  The latest version of the NuGet package can be found here.
 
HTML Integration:
  Install the latest version of the NuGet package. Three byMarc/dropDownCheckBoxList folders should appear in the Content, Images and Scripts folders. They should contain the .css, .png and .js files.
 
 
 

To use the control on a page, links to the .js and .css styles are needed.
  <link href="Content/byMarc/dropDownCheckBoxList/byMarc.JS.dropDownCheckBoxList.css" rel="stylesheet" />
<script src="Scripts/byMarc/dropDownCheckBoxList/byMarc.JS.dropDownCheckBoxList.min.js"></script>
   
  Create a <div> element with an ID. This element will be used as the parent container element.
  <div id="dropDownCheckBoxList"></div>
   
  Instances of the control can be created by calling the createDropDownCheckBoxList javascript method. To seat the control, supply the parentElement option.
  <script>createDropDownCheckBoxList({ parentElement: dropDownCheckBoxList })</script>
   
 
 
  The drop-down should by working:
 
 
 
 
byMarc is a registered trademark by Enterprise Solutions & Technology Consulting. All rights reserved. This documentation created using Adobe Dreamweaver.