Client Side Handling of Items Controls

These functions need reference to MVCControlToolkit.Controls.Core-x.x.x.js.

Datagrid, SortableList, TreeView and DualSelect supports both client side events that are triggered each time an operation is done on an item, and a complete API to trigger all their operations from Javascript..

Item Events

An handler for all item events can be provided by subscribing to the jQuery event ItemChange event as follows:

 

$('#referenceNode').bind('itemChange', function (e, eventData) { ..... });

 

Where:

  • referenceNode selects the Html node that acts as a representative of the whole control. Any node that contains the whole control inside it can act as a reference node, since in javascripts all events are bubbled up. 
  • e is the usual argument of all jQuery events.
  • eventData is an object cantaining all informations on the item event. Specifically:
    • eventData.ItemChanged: the Item involved in the event or null, as appropiate. The item is provided as a  jQuery object containing the Html node that is the root of the item.
    • eventData.ChangeType: a string with the name of the king of events occurred.
    • eventData.Data: Supplementary data that depend on the type of event. For most of events it is undefined
    • eventData.Cancel: a boolean, that if set to true in the handler causes the action associated with the event to be aborted.

There are two events associated to each action: an event whose name ends in ing, that si triggered immediately before the action takes place, and an event whose name ends in ed that is triggered immediately after the action took place. An action can be aborted by setting eventData.Cancel  to true in its ing event handler.

The table below summarize all information about the supported events:

e.ChangeType e.ItemChanged e.Data Datagrid SortableList TreeView DualSelect
ItemCreating Item being created for the DualSelect. null for all other controls (1)

the number of the template for the TreeView. Undefined for all other controls

supported supported supported supported
ItemCreated item created the number of the template for the TreeView. Undefined for all other controls supported supported supported supported
NewHtmlCreated the newly generated node undefined supported(4)      
ItemDeleting Item being deleted undefined supported supported supported supported
ItemDeleted Item deleted for the DualSelect. null for all other controls (2) undefined        
ItemMoving Item being Moved -1 if the item is being moved one position down, and +1 one position up in the DualSelect. Undefined in all other cases NA unsupported(3) unsupported(3) supported
ItemMoved Item Moved -1 if the item was moved one position down, and +1 one position up in the DualSelect. Undefined in all other cases NA supported supported supported
 ItemUndeleting null  undefined supported NA NA NA
 ItemUndeleted item that was undeleted  undefined supported NA NA NA
 ItemGoingEdit Item passing in edit mode  undefined supported NA NA NA
 ItemGoneEdit Item passed in edit mode  undefined supported NA NA NA
 ItemUndoing Item passing back into display mode after a row undo operation  undefined supported NA NA NA
 ItemUndone  Item passed back into display mode after a row undo operation  undefined supported NA NA NA
 ItemResetting Item whose input fields are being reset after a row reset operation   undefined supported NA NA  NA 
 ItemReset Item whose input fields were reset after a row reset operation   undefined supported  NA  NA  NA 

ItemClosing

ItemOpening

Tree item whose branch is going to be closed/opened undefined NA NA supported NA

ItemClosed

ItemOpened

 

Tree item whose branch has been closed/opened undefined NA NA supported NA

(1) In the case of the DualSelect the item already exists, and is just passed from a box to another. In all other cases the item has not been created yet.

(2) In the case of the DualSelect the Item is just passed from a box to another. In all other cases the item is destroyed or detached from the DOM, so it cannot be accessed safely.

(3) In the case of SortableList and Treeview the item is moved by dragging it. It is not "user friendly" interfering with the dragging process. One can prevent some movements by working with node classes in the case of the TreeView and by calling the methods of the jQuery UI Sortable in the case of the SortableList.

(4) Due, to the changes tracking feature of the DataGrid, the Html of a new row is not created when a new row is added. This new event triggeres when the Html of a new row is created. It is a good opportunity for the developer to add some jQuery features to the newly created row (it is similar to the ready event for the whole page). Other controls doesn't need this event, because the new Html is created when the new element is added.

The reference node "closest" to the server control is the root of the server control. Below examples of how to find the root node of each item control(however events do not need to be applied to the root node but can be applied to any ancestor of the root node):

Datagrid

The Html nodes where all items were appended as children. See the example below:

 

<tbody class='gridRoot'>
      @Html.DataGridFor(m => m.ToDoList, ItemContainerType.tr,
        "ToDoEditItem", "ToDoDisplayItem", null, "ToDoInsertItem", "ToDoUndeleteItem",
         itemCss: "normalRow", altItemCss: "alternateRow",
         toTrack: new FieldsToTrack<ToDoItem>().
         Add(f => f.Code).Add(f => f.Name).Add(f => f.Description).Add(m => m.Important)
                                   .Add(f => f.ToDoRoles).Add(f => f.ToDoRole))
                                   
 </tbody>

 

 

 <script type="text/javascript">
    $('.gridRoot').bind('itemChange', function (e, data) { alert(data.ChangeType); });      </script>

 

SortableList

The ItemsContainer. It can be accessed either with Html.PrefixedId(m => m.MyList).ToString()+"ItemsContainer", or by applying a Css class to the Items Container as in the example below:

 

@Html.SortableListFor(convertedKeywords,
 _S.L<string>(
    (x) => x.TypedTextBoxFor(m => m, watermarkCss: "watermark", overrideWatermark: "insert keyword").ToString() +
    x.SortableListDeleteButton("Delete",  ManipulationButtonStyle.Link).ToString()
                    ), 
  "KeywordInsert", 0.8f,
  htmlAttributesContainer: new Dictionary<string, object> { { "class", "SortableList" } },
                               itemCss: "normalRow", altItemCss: "alternateRow")
                  
<script type="text/javascript">
   $('.SortableList').bind('itemChange', function (e, data) { alert(data.ChangeType); });  
</script>

 

TreeView

The overall Items container. Since TreeView may be go in Edit or DisplayMode, the safest way to access the overall ItemsContainer is by applying a Css class as shown below:

 

@Html.TreeViewFor(
    m => m.EmailFolders,
    i => i == 0 ? "Children" : null,
    ExternalContainerType.span,
    "filetree treeview-red treeToedit",
    new object[] 
    {
       _S.L<EmailFolder>(h => 
         "<span class='folder'>" +h.DisplayFor(m => m.Name).ToString()+"</span>"),
                            
       _S.L<EmailDocument>(h => 
         "<span class='file'>" +h.DisplayFor(m => m.Name).ToString()+"</span>") 
     },
     (x, y) => x is EmailFolder ? 0 : 1,
     "filetree treeview-red treeToedit",
     new object[] 
      {
        _S.L<EmailFolder>(h => string.Format(
          "<div class='folder' >{0} {1} {2} {3} {4}</div>", 
           h.TypedEditDisplayFor(m => m.Name, simpleClick: true).ToString(),
           h.TreeViewDeleteButton(Url.Content("~/Content/folder_delete_16.png"), 
              ManipulationButtonStyle.Image).ToString(), 
           h.TreeViewAddButton(1, Url.Content("~/Content/document_add_16.png"), 
              ManipulationButtonStyle.Image).ToString(),
           h.TreeViewAddButton(0, Url.Content("~/Content/folder_add_16.png"), 
              ManipulationButtonStyle.Image).ToString(),
           h.Hidden("IsFolder", true).ToString())),
                            
       _S.L<EmailDocument>(h => string.Format(
         "<div class='file' >{0} {1} {2}</div>",
            h.TypedEditDisplayFor(m => m.Name, simpleClick: true, editEnabled: true).ToString(),
            h.TreeViewDeleteButton(Url.Content("~/Content/document_delete_16.png"), 
                ManipulationButtonStyle.Image).ToString(),
            h.Hidden("IsFolder", false).ToString())) 
      },
      (x, y) => x is EmailFolder ? 0 : 1,
        TreeViewMode.InitializeDisplay,
        (x) => "allnodes",
        (x, y) => TreeViewItemStatus.initializeShow)
                    
<script type="text/javascript">
   $('.treeToedit').bind('itemChange', function (e, data) { alert(data.ChangeType); });
</script>

 

DualSelect

A dummy Html node whose name is Html.PrefixedId(m => m.MyList). The simplest way to accessit is by applying a Css class to the dummy Html node as shown below:

 

@{ 
   var RoleSelect = Html.DualSelectFor(m => m.Keywords, ChoiceList, new Dictionary<string, object> { {"class", "dualselect"}});
   
 }
.......
......
<script type="text/javascript">
   $('.dualselect').bind('itemChange', function (e, data) { alert(data.ChangeType); });
</script>

 

Datgrid Client-Side API

The Datagrid API contains just one js function that when called with adequate parameters causes the same effect than the click of the various Data Buttons:

mvcct.html.trackedGrid.dataButtonClick(itemRoot, dataButtonType) version >= 3.0.0

MvcControlsToolkit_DataButton_Click(itemRoot, dataButtonType) version < 3.0.0

Where:

  • itemRoot is the Html node that is the root of the item, or a string containing the Name of the item. Attention, it is not a jQUery object but just a simple node, so if you have a jQuery object jItem you have to take jItem[0]. A root node may be obtained from the arguments passed to an ItemChange event handler; It is not safe to obtain a pointer in other ways since the pointer change each time the item pass from Edit to Display mode or vice-versa. The Name of an item can always be used safely, since it doesn't depend on the state of the item. It is obtained by calling Html.PrefixedId(string.Empty) within any item template.
  • dataButtonType is the name of the data button whose action you would like to invoke on the item passed as first parameter. It is one of the following Javascript variable names:

    mvcct.html.trackedGrid.dataButtonDelete, mvcct.html.trackedGrid.dataButtonEdit, mvcct.html.trackedGrid.dataButtonInsert, mvcct.html.trackedGrid.dataButtonCancel, mvcct.html.trackedGrid.dataButtonResetRow (version >= 3.0.0).

    DataButtonDelete, DataButtonEdit, DataButtonInsert, DataButtonCancel, DataButtonResetRow (version < 3.0.0).

 

SortableList Client-Side API

The SortableList API contains three function, for creating, deleting and moving an item.

mvcct.html.sortableList.addNew(root, [item], [after]) version >= 3.0.0

MvcControlsToolkit_SortableList_AddNew(root, [item], [after], [replace], [prepend]) version < 3.0.0

where:

  • root is the Html node that is the container of all items. It is a simple node not a jQuery object.
  • item. An item already contained in the SortableList. If this parameter is supplied the newly created item is inserted immediately before or after it, according to the value of the third parameter. If this argument is not supplied the new item is appended as last item.
  • after. If after is true the newly created item is inserted immediately after item otherwise before it.
  • replace. If replace is true the newly added item replaces item.
  • prepend. If prepend is true the append operation performed when item is not supplied is substituted by a prepend operation.

This function returns the newly created item.

mvcct.html.sortableList.move(item, target, after)  version >= 3.0.0 

MvcControlsToolkit_SortableList_Move(item, target, after) version < 3.0.0

where:

  • item is the item to move.  It is a simple node not a jQuery object. The id of an item can be obtained by calling  Html.PrefixedId("Container") within an item template.
  • target. Another item specifying where to move item.
  • after. If after is true item is inserted immediately after target otherwise before it.

This function doesn't return any value. It may be called only on SortableLisst having the canSort option set to true.

mvcct.html.sortableList.click(target, dataButtonType) version >= 3.0.0

MvcControlsToolkit_SortableList_Click(target, dataButtonType) version < 3.0.0

This function can be used both to delete an item or to show/hide the new item to be inserted when the SortableList has the enableMultipleInsertions set to false(enableMultipleInsertions is always assumed true starting from version 3.0.0).

target is the item to operate on. It is a simple node not a jQuery object. The id of an item can be obtained by calling  Html.PrefixedId("Container") within an item template.

The value of dataButtonType id one of the Javascript variables: 

mvcct.widgets.manipulationButton.remove, mvcct.widgets.manipulationButton.hide, mvcct.widgets.manipulationButton.show (version >= 3.0.0).

ManipulationButtonRemoveManipulationButtonHideManipulationButtonShow (version < 3.0.0)

This function doesn't return any value

 

TreeView Client-Side API

The TreeView API contains four functions, for creating, deleting,  moving an item, and changing the state(opened-close) of a node. The function to change the node state is the only one that can be used also when the ThreeView is in Display mode.

All functions have tree nodes  as parameters. They can be supplied either passing their pointers, if they are available someway, or by passing their names. The name of a node is obtained by calling Html.PrefixedId("Container"), within a node template.

mvcct.html.serverTreeview.changeNodeState(node, operation) version >= 3.0.0

MvcControlsToolkit_TreeView_ChangeNodeState(node, operation) version < 3.0.0

where:

  • node is the node whose state have to be changed. I can be either the node pointer or the node name.
  • operation is one of the Javascript variables: 
    mvcct.html.serverTreeview.treeViewMvcOpen, mvcct.html.serverTreeview.treeViewClose, mvcct.html.serverTreeview.treeViewToggle (version >= 3.0.0)
    MvcControlsToolkit_TreeView_OpenMvcControlsToolkit_TreeView_CloseMvcControlsToolkit_TreeView_Toggle (version < 3.0.0)

This function returns no value.

mvcct.html.serverTreeview.addNew(root, templateChosen, [item], [after]) version >= 3.0.0

MvcControlsToolkit_TreeView_AddNew(root, templateChosen, [item], [after]) version < 3.0.0

where:

  • root is the Html node that is the father that will contain the new item. It is a simple node pointer or the node name.
  • templateChosen is the index of the template to use for the new node.
  • item. An item already contained in the TreeView. Only the pointer of the node is accepted. If this parameter is supplied the newly created item is inserted immediately before or after it, according to the value of the third parameter. If this argument is not supplied the new item is appended as last item of root.
  • after. If after is true the newly created item is inserted immediately after item otherwise before it.

This function returns the newly created item.

mvcct.html.serverTreeview.deleteNode(node) version >= 3.0.0

MvcControlsToolkit_TreeView_Delete(node) version < 3.0.0

node is either a pointer to the node to delete or its name.

This function doesn't return any value.

mvcct.html.serverTreeview.move(item, target, after) version >= 3.0.0

MvcControlsToolkit_TreeView_Move(item, target, after) version < 3.0.0

where:

  • item is the item to move. Only the pointer of the node is accepted.
  • target. Another item specifying where to move item. Only the pointer of the node is accepted.
  • after. If after is true item is inserted immediately after target otherwise before it.

This function doesn't return any value.

mvcct.html.serverTreeview.moveAppend(item, target) version >= 3.0.0

MvcControlsToolkit_TreeView_MoveAppend(item, target) version < 3.0.0

where:

  • item is the item to move. Only the pointer of the node is accepted.
  • target. Another item specifying where to move item. item will be appended as last children of target.

This function doesn't return any value.

 

DualSelect Client-Side API

The DualSelect has both functions to set and get the list of values and to perform the same actions of its buttons. The functios to set and get the array of values have the same format as the ones of the simple server controls, therefore they are:

mvcct.widgets.DualSelect.set(element, newValue, null, valueType) version >= 3.0.0

MvcControlsToolkit_DualSelect_Set(element, newValue, null, valueType) version < 3.0.0

and

mvcct.widgets.DualSelect.get(element, valueType) version >= 3.0.0

MvcControlsToolkit_DualSelect_Get(element, valueType) version < 3.0.0

The third parameter of the first function is not used because it should be the format string for displaying the values, but itall items are taken from already existing lists. 

element is the representative Html node of the control. Its id can be obtained with Html.PrefixedId(m => m.MyList).

valueType is an enumeration specifying the data type of the items. The possible values are listed in Validation and Formatting functions.

newValue is an array of values of the type specified by valueType. The same type of array is returned by the .get method.

The DualSelect controlt has also the setById and getById versions of the above methods.

The functions that perform the same actions of the DualSelect buttons are:

mvcct.widgets.DualSelect.moveElement(dualSelectId, bDoSelected) version >= 3.0.0

DualSelect_MoveElement(dualSelectId, bDoSelected) version < 3.0.0

and 

mvcct.widgets.DualSelect.moveAll(dualSelectId, bDoSelected) version >= 3.0.0

DualSelect_MoveAll(dualSelectId, bDoSelected) version < 3.0.0

that move respectively all selected items and all items from one box to the other. If  bDoSelected is true the elements are moved into the box containing the selected elements, if it is false the items are moved in the other direction.

Similarly,

mvcct.widgets.DualSelect.moveUp(dualSelectId, bDoSelected) version >= 3.0.0

DualSelect_Move_Down(dualSelectId, bDoSelected) version < 3.0.0

and 

mvcct.widgets.DualSelect.moveDown(dualSelectId, bDoSelected) version >= 3.0.0

DualSelect_Move_Up(dualSelectId, bDoSelected) version < 3.0.0

move all selected items respectively, one position down and one position up in the box they belongs to.

The dualSelectId argument may be obtained with: Html.PrefixedId(m => m.MyList).ToString()+"___PackedValue"


Last edited Jun 22, 2014 at 11:58 AM by frankabbruzzese, version 26

Comments

No comments yet.