Token: CheckItem, Radio and CheckItem Lists

By

Providing the added interaction of check lists, or radio lists with automatic selection of all items under a group header checkbox item is made simple using the integrated syntax. All runtime actions like Sorting, Interactive Lists and Actions utilize the similar formatting structures contained within curly braces {...}. Check Lists, Radio Lists, Check List Items, and Check Items all have slightly different syntax - so follow the links to learn more about each of the syntax elements. Follow the syntax definitions provided to assist in building the appropriate output block.

Tip: Sometimes the easiest way to provide visual affect of the sorting, besides the actual rendered output is to show a flag indicating the direction of the sort. While this can be done in a complex manner of rendering special images per column, or changing a variety of visual indicators, it is easiest to simply define a background image within a CSS class definition, and simply change the name of the class in the anchor tag on each of the sort orders.

Check List Syntax

Check Lists are generally made up of a header and or footer group checkbox, providing the ability to check all child items or detail items currently visible by checking or unchecking the grouped header checkbox. Check Lists require a Check List Header which provides the group name and session variable name. The child items of that group should be defined as Check List Items, which provide the group name to which they belong, and the name of the column to place in the session variable array.

Header/Footer Check List Syntax:
{CHECKLIST,GroupName,SessionVariableName,Optional Boolean Value}

Detail Check List Item Syntax:
{CHECKLISTITEM,GroupName,ColumnName,Optional Boolean Value}

Example


Group Item Header

<table>
         <tr>     
                 <th>{CHECKLIST,Select,CurrentEventLogIDs}</th>
         </tr>            

Detail Item

         <tr>     
                 <td>{CHECKLISTITEM,Select,[EventLogID]}</td>
         </tr>            

Group Item Footer

</table>



Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Check lists and Check list Items are always contained within curly braces {...} with the first parameter identifying the type of interaction. In the case of this element, CHECKLIST or CHECKLISTITEM will be the first parameter. Other types of actions include SORT,SORTHEADER, and other types including CHECKLIST.

Group Name
To provide automated checking facilities within ListX, automatically checking all visible items within a specific group, a Group Name must be provided. The Group name can be anything - and in cases where you will have nested groups, the Group Name should contain a Column Value from the parent so that Outer Groups can be checked in unison with inner groups (cascading). 

Session Variable Name
The core of interactive elements on the web is provided by utilizing some type of shared variable which can be assigned or read from different modules within your overall system. ListX is capable of reading and writing to variable located in the Session array. Place the name of the session variable which will store the value of the column chosen in this interactive element. The variable in this case will contain an array list of elements. The array list is automatically transformed when used within Queries as a comma delimited representation. Values that were defaulted to Checked or Unchecked will be placed into either the Checked array, identified by the Session Variable Name, or in the Unchecked array, in the Session Variable Name, prefaced by "Un", as in "CheckedItemList" and "UnCheckedItemList".

Column Name
The name of the column which will be placed in the Session Variable assigned to the group. The variable may be a single column name, or could utilize the Column Value syntax to build combined - or formatted values.


Optional Boolean Value
Using standard column formatting, this value optionally allows you to specify the default value for this check item. The value can either be true/false, or 0/1. The default value specifies whether the item is defaulted to checked, or unchecked.


Singular Check Item Syntax

Check boxes which are provided in the output, but are not related to any specific group header, or check list header are defined as CHECKITEM elements. Check Items require a session variable name and the name of the column to place in the session variable array.

Check Item Syntax:
{CHECKITEM,SessionVariableName,ColumnName,Optional Boolean Value }

Example


Detail Item

         <tr>     
                 <td>{CHECKITEM,CurrentEventLogIDs,[EventLogID]}</td>
         </tr>            



Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Check Items are always contained within curly braces {...} with the first parameter identifying the type of interaction. In the case of this element, CHECKITEM will be the first parameter. Other types of actions includeSORT,SORTHEADER, and other types including CHECKLIST.

Session Variable Name
The core of interactive elements on the web is provided by utilizing some type of shared variable which can be assigned or read from different modules within your overall system. ListX is capable of reading and writing to variable located in the Session array. Place the name of the session variable which will store the value of the column chosen in this interactive element. The variable in this case will contain an array list of elements. The array list is automatically transformed when used within Queries as a comma delimited representation. Values that were defaulted to Checked or Unchecked will be placed into either the Checked array, identified by the Session Variable Name, or in the Unchecked array, in the Session Variable Name, prefaced by "Un", as in "CheckedItemList" and "UnCheckedItemList".

Column Name
The name of the column which will be placed in the Session Variable assigned to the group. The variable may be a single column name, or could utilize the Column Value syntax to build combined - or formatted values.


Optional Boolean Value
Using standard column formatting, this value optionally allows you to specify the default value for this check item. The value can either be true/false, or 0/1. The default value specifies whether the item is defaulted to checked, or unchecked.

How to Use Checklists in your Solution

For the sake of understanding and utilizing the Checklists, and an overview of how the checklists operate within your variable values, this section of the documentation is provided. The reasoning behind the operation of the Checklist, in terms of what items physically appear within your Checked and Unchecked variables, is at times a bit complicated to understand, because these variables do not physically store all items that *ARE CHECKED*, but rather, those items which are *NOW CHECKED*, based on their original unchecked state. So generally, this concept is missed because you need the big picture. Instead of assuming you have items 1 through 10 in a list, let’s say you have items one through 2 million in a list. If your idea is to let the user add and remove items from their list by checking and unchecking them - you are in the right. The problem is that we had to throw a curve ball into the mix.

If you are dealing with 2 million records (or even 10 pages of records), checking each entry in the box will setup the indicator as to whether an item was Checked or Unchecked. Meaning - we aren't physically recording everything that is checked in the database into your runtime session - that would be crazy - what if you checked everything. Instead - we are checking the state of what has changed.

Also - before we break down this sample – it’s important to know that the items are Checked and Unchecked immediately via AJAX, so as soon as you check the box – its change of state is now recorded in your variable on the web server.

Now for the proper handling of this scenario and others which may vary from your initial reason for using the checklist, please continue to read below this even if this doesn't sound like it makes sense for your needs. I will give another solution for smaller sets of data (like subqueries directly after this sample section).

Example

Assume are attempting to use a checkbox list for a list of 2 thousand attributes. The user will be checking and un-checking the items that are associated with their specific Location. For example - your table structure may be something like this:

Table: Attribute

AttributeID int

Name varchar(50)

Table: AttributeLocation

AttributeID int

LocationID int

Table: Location

LocationID int

Name varchar(50)

Assuming the information about the tables above, the AttributeLocation table will contain the list of locations per attribute (one attribute can have many locations and one location may have many attributes – many-to-many). So the user is presented with the Attribute Detail and a paged checklist of 2000 Locations left joined against the AttributeLocation table. The box next to each location is defaulted to “checked” when the AttributeID is not null (thanks to the left join).

To begin, assume that we are using the CheckedAttributeLocations Session variable for runtime storage of the changed states. This means that there will be a physical variable called UnCheckedAttributeLocations also - containing any LocationID that was Unchecked (meaning it was originally defaulted to checked, so the state is dirty and now unchecked).

At the time of rendering there may be 100 of the 2000 boxes checked and the remaining 1900 left unchecked. At that moment, our Session variables look like this:

CheckedAttributeLocations: Empty

UnCheckedAttributeLocations: Empty

Assume that Locations “1”, “2” and “3” are checked by default, with “4”, “5”, “6” left unchecked by default. If we uncheck “1”, “2”, “3” and check “4”, “5”, “6” our variables look like this:

CheckedAttributeLocations: 4, 5, 6

UnCheckedAttributeLocations: 1, 2, 3

Technically, by the understanding of this temporary state - of the original 100 entries that were checked, we have removed three checks and added three unchecks.

Let's say you change your mind - and now Uncheck “5”. This is what the variable now contains:

CheckedAttributeLocations: 4, 6

UnCheckedAttributeLocations: 1, 2, 3

Notice – “5” is now not in either list - because it's state has not changed from the original request.

With that said - how do we fold the changes back into the database? Within the actions - when you want to save your changes you simply do this.

First - delete everything that was UnChecked from your AttributeLocation table, because it is void from the system now that it has been unchecked officially:

Assume @AttributeID is your AttributeID

Assume @UnCheckedItems is equivalent to your [UnCheckedAttributeLocations,Session] object

Delete from AttributeLocation where AttributeID = @AttributeID and LocationID in (@UnCheckedItems)

Next, insert the newly checked records into your AttributeLocation table -

 

Assume @AttributeID is your AttributeID

Assume @CheckedItems is equivalent to your [CheckedAttributeLocations,Session] object

Insert into AttributeLocation(AttributeID,LocationID) select @AttributeID,LocationID from Location where LocationID in (@CheckedItems)

That's it - you only made changes to the ones that physically were altered, the rest remained as they were in the original state.

With all that said, if you have a very short list, it's actually more useful to use a standard checkbox approach - as long as you do not need to page through your data. This is because if you add the following hypothetical items to your template you will automatically receive the delimited list of checked items by checking on the form variable:

<Input type=checkbox name=chkValue id=chkValue value=”1” checked>

<Input type=checkbox name=chkValue id=chkValue value=”2” checked>

<Input type=checkbox name=chkValue id=chkValue value=”3”>

<Input type=checkbox name=chkValue id=chkValue value=”4” checked>

<Input type=checkbox name=chkValue id=chkValue value=”5” checked>

The result of the form variable would mean that [chkValue,Form] would equal a comma delimited list of 1,2,4,5

Radio Item Syntax

Radio buttons which are provided in the output and are related to specific selections in groups are defined as RADIO elements. Radio Items require a group name, session variable name and the name of the column to place in the session variable array.

Radio Item Syntax:
{RADIO,SessionVariableName,ColumnName}

Example


Detail Item

         <tr><td>{RADIO,Select,[EventLogID],CurrentEventLogIDs}</td></tr>               


Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Radio Items are always contained within curly braces {...} with the first parameter identifying the type of interaction. In the case of this element, RADIO will be the first parameter. Other types of actions includeSORT,SORTHEADER, and other types including CHECKLIST.

Group Name
To provide automated grouping facilities within ListX, automatically deselecting related radio items visible items within a specific group, a Group Name must be provided. The Group name can be anything - and in cases where you will have nested groups, the Group Name should contain a Column Value from the parent so that Outer Groups can be combined in unison with inner groups (cascading). 

Column Name
The name of the column which will be placed in the Session Variable assigned to the group. The variable may be a single column name, or could utilize the Column Value syntax to build combined - or formatted values.


Optional Boolean Value
Using standard column formatting, this value optionally allows you to specify the default value for this check item. The value can either be true/false, or 0/1. The default value specifies whether the item is defaulted to checked, or unchecked.

Session Variable Name
The core of interactive elements on the web is provided by utilizing some type of shared variable which can be assigned or read from different modules within your overall system. ListX is capable of reading and writing to variable located in the Session array. Place the name of the session variable which will store the value of the column chosen in this interactive element. The variable in this case will contain an array list of elements. The array list is automatically transformed when used within Queries as a comma delimited representation. . Values that were defaulted to Checked or Unchecked will be placed into either the Checked array, identified by the Session Variable Name, or in the Unchecked array, in the Session Variable Name, prefaced by "Un", as in "CheckedItemList" and "UnCheckedItemList".

Average ( Ratings):
 
Want to help out?
 
 

New York, NY • Baltimore, MD • Vienna, VA • St. Louis, MO • Seattle, WA • info@openwebstudio.com

Bookmark & Share Bookmark and Share