Appendix: Using the DATAROW Element Tag

Appendix: Using the DATAROW Element Tag

The DATAROW element renders the values of one or more items in a JSON array, repeating those values for each row in the array. To achieve this, you must use the DATAROW element to wrap one DATA element for each value you want to return.

Implementation:

Click to open the Element Browser to the right of the window.
Use the Filter menu to select Tags.
Locate and select DATAROW.

The element has the following syntax:

<%= DATAROW(
Keyword
Path

Name

[other parameters as required]) %>



    <%# DATA(Keyword, Name.Item1, [...]) %>

    <%# DATA(Keyword, Name.Item2, [...]) %>

    ...etc.



<%= %>

Parameters can be entered in any order. Where a parameter is not required, it should be excluded.

You can include other markup inside the DATAROW tag if you want to apply formatting or structure to the resulting data. This additional content, like the data, will be repeated for each row returned.

The following parameters are required:

Parameter	Description
Keyword	The keyword of the intended JSON object.
Path	The path of the intended array.
Name	A user-defined alias for the path of the intended array. This alias should be used in place of Path in any DATA elements within the DATAROW construct. The default value is DataRow.

The following parameters are optional:

Parameter	Description
Where	The path - based on the Name alias - of an item you want to test for a specific value. The value is defined by the Value parameter, and only rows that have the specified path and value combination will be returned.
Value	The value used with the Where parameter to determine which rows are returned.
MaxRows	The maximum number of rows to be returned. Rows excluded by the Where parameter do not count toward this maximum. If MaxRows is not used, the function will return as many rows as it finds.
StartRow	The zero-based index of the first row in the array to be examined. The default value is 0.
IsAsync	A Boolean that determines whether the operation is asynchronous. The default value is True.
AsyncRendering	A message string that will appear to users while data is being rendered. Only applicable if IsAsync is True.
AsyncMethod	The name of a JQuery method to call when the operation is complete. Only applicable if IsAsync is True. The default value is RenderData.

While processing a DATAROW element, KnowledgeKube automatically generates two special keywords. Each is named according to the Name parameter assigned to the element, with the first using the suffix -Index and the second using -Count. The index keyword returns the zero-based index of the row being processed, while the count keyword returns the total number of rows returned by the element. For example, if the element uses the name ProductDetails, the automatically-generated keywords will be named ProductDetailsIndex and ProductDetailsCount. These keywords can be rendered like any other, for example using KEYWORD elements.

The following example contains a DATAROW element that examines the Result array stored in the UserDetails object, and assigns it the name UserList. It then uses DATA elements to render four values from each row of the array, namely CompanyGUID, CompanyName, Username and ApprovalStatus:

<%= DATAROW(

Keyword="UserDetails"

Path="Result"

Name="UserList"

Where="UserList.ApprovalStatus"

Value="Approved"

MaxRows="15"

StartRow="0"

IsAsync="true") %>



    <p>Item <%# EXPRESSION(UserListIndex + 1) %> of <%# KEYWORD(UserListCount) %>...</p>
    <p>GUID: <%# DATA(keyword="UserDetails" path="UserList.CompanyGUID") %></p>
    <p>Company: <%# DATA(keyword="UserDetails" path="UserList.CompanyName") %></p>
    <p>User Name: <%# DATA(keyword="UserDetails" path="UserList.Username") %></p>
    <p>Status: <%# DATA(keyword="UserDetails" path="UserList.ApprovalStatus") %></p>


<%= %>

Note how each DATA element refers to an item using the alias name (UserList), and not the literal path (Result). This DATAROW element is configured to return no more than fifteen rows, starting from the very first one, and it uses a Where condition to exclude any rows whose ApprovalStatus is not "Approved". The markup wraps each item of data returned in a new paragraph, causing the results to appear much like the sample below:

Item 1 of 15...
GUID: a8d65c10-00f0-4e9f-b75d-7a12ddef734d
Company: Victor Planes
User Name: Michael Gough
Status: Approved
Item 2 of 15...
GUID: 3619a130-9521-4eb5-aabf-55ca9d898edd
Company: Lucies Hats
User Name: lucie.hat
Status: Approved

...etc.

The first paragraph in each set of data uses the UserListIndex and UserListCount keywords to generate a distinct "Item x of 15..." for the current item.