4. Control Documentation

This section will detail each control provided by the SDK, and the attributes used to configure them.

Note: All attributes specified in this section can be prefixed with data-ex-, data-, ex-, or just as-is. The data- prefixes will enable your pages to validate correctly according to the HTML5 spec, but are not necessary if this does not bother you.

ActivityView

The ActivityView control represents a boundary that maps to an activity on the server. Any HTML elements enclosed within this boundary can be mapped to fields and methods on that activity.

HTML Sample

Attributes

Name	Description
activityname	The name of the activity on the server to map to. Falls back to name attribute if not found.
activitystyle	The style of the activity to pass to the server.
key
keepopenforsession	By default, the activities will remain open on server, even after you navigate away from them. The SDK doesn’t close them by default, as it’s not unusual to navigate away from an activity and then back to it in an HTML application. In addition, you don’t want the activity to be closed when simply refreshing the page in the browser. However, you can change this behaviour by setting the keepopenforsession attribute on the activity element to false. Note that this attribute currently has no effect on activities opened in popup windows – closing a popup window will always close the corresponding activity on the server.
optimise	Field optimisation helps minimise the amount of data returned by the server. The fields used by a page will be sent to the server when creating an activity. The server will then only send the values for these fields back to the client in the response, rather than all the fields in the activity. By default, field optimisation is turned on, but you can turn it off by setting this attribute to false.
autoLoad	Any activities with this attribute set to false will not automatically be loaded by the SDK when the page loads. This is particularly useful when additional content for the activity is to be downloaded from the server before fields, methods, etc can be bound.
allowanonymous	Setting this attribute to true will enable the user to access this activity without having to log in first.
dofullserverrepublish	When set to true, sends the newUI=1 attribute to the server when the activity is created. Required when you have two or more pages that map to the same activity/style combination in your application, and you’re using field optimisation. Normally, when navigating to an activity that had previously been opened, the server will just republish the fields / data publications that had been requested previously, ignoring the optimised field list passed to it. This becomes a problem when different pages using the same activity/style combination require different fields / data publications from the server. This flag tells the server not to ignore the optimised field list being passed to it.
pollmethod	The name of a method to call on the activity at a regular interval (specified by the pollinterval attribute, by default every 60 seconds), used to poll the server for any new data
pollinterval	The interval (measured in seconds) at which the pollmethod method should be called on the server. Default value is 60 seconds.

ContextMenuView

The ContextMenuView control displays a context menu to the user, enabling them to select from a list of menu items. Note that the built in functionality is quite a minimal implementation, and probably not suitable for production use. However, if you choose to use them, the KendoUI adapters will override the default implementation and provide a much more functional context menu, with no configuration required to enable them.

HTML Sample

The ContextMenuView control cannot be configured in HTML, as it is designed to be instantiated automatically in response to a message from the server.

CustomContentView

The CustomContentView control can be used to render any results returned in a CustomContent element (in the XML response) from the server. This is particularly useful when the server is returning a custom data structure that the SDK cannot natively interpret and render. When using this control, you will need to write a custom adapter that can listen to events raised by this control and render the results from the server accordingly.

HTML Sample

Attributes

Name	Description
customcontentid	The id of the custom content that’s returned from the server to display in this control. If not provided, it will fall back an id attribute.

Events Raised

customcontent:contentPublished – raised when data has been returned from the server for this control.

DataFieldView

The DataFieldView control typically renders as a dropdown list. It mapped to both a field and a data publication on the server – the data publication providing the data to display in the list, and the field providing the selected value.

HTML Sample

or

For a radio button list:

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead.
dataid	An id used to identify the data publication to the server. If not supplied, the SDK will look for an id attribute, then a fieldid attribute, a name attribute, a query attribute, and finally a populatemethod attribute to use instead.
query	The name of a query to be used to populate the dropdown list with items (optional).
populatemethod	The name of a method to be used to populate the dropdown list with items (optional).
contextobject	The context object to pass to the server for the data publication.
autopopulate	You can tell the server to not automatically return items for this data publication by setting the autopopulate attribute to false.
anonymousboundmethod	The anonymous method to call to populate the list. Note: Don’t have a working example to demonstrate or confirm working.
class

DataPublicationView

The DataPublicationView control can be used to render the results of a data publication returned from the server. These may be rendered as a simple table, or completely custom rendered using templates. More details on using this control can be found in the section earlier in this document titled Creating a Summary List.

HTML Sample

Attributes

Name	Description
dataid	An id used to identify the data publication to the server. If not supplied, the SDK will look for an id attribute, then a name attribute, then a query attribute, and finally a populatemethod attribute to use instead.
query	The name of a query to be used to populate the dropdown list with items (optional).
populatemethod	The name of a method to be used to populate the dropdown list with items (optional).
contextobject	The context object to pass to the server for the data publication.
autopopulate	You can tell the server to not automatically return items for this data publication by setting the autopopulate attribute to false.
anonymousboundmethod	The anonymous method to call to populate the list. Note: Don’t have a working example to demonstrate or confirm working.
class
candrilldown	This will turn the first cell of every row into a hyperlink (except for totals rows, blank rows, and rows where drill down has explicitly been turned off). By default, when a drill down hyperlink has been clicked, the SDK will raise a datapublication:rowDrillDown event on the data publication control. If this event is not marked as handled, it will simply set the context on the server to this row.
drilldownpage	When the drilldownpage
itemtemplatename	The id of the text template on the page that will be used to customise the rendering of the items in the data publication. If not provided, the SDK will search for a template consisting of the dataid suffixed with “ItemTemplate”. If neither are found, the data publication control will simply implement its default rendering.
headertemplatename	The id of the text template on the page that will be used to customise the rendering of the header of the data publication. If not provided, the SDK will search for a template consisting of the dataid suffixed with “HeaderTemplate”. If neither are found, the data publication control will simply implement its default rendering.
itemsperpage	If this attribute is provided, it will turn on client-side paging for the data publication, limiting it to displaying only the given number of items at a time.
noitemstext	A message to display if no items were returned by the server.
sortable	Whether the automatically generated column headers will be sortable. Defaults to true. Note that this will have no effect on data publications which use a custom header template – you will need to apply the sortField attribute to column header elements with the name of the field.
sortbyrowid	Rows will be sorted by the row Id if set to true (default); otherwise rows will be left in the order provided by the server.

Events Raised

datapublication:publishData – raised when data has been published to the control, prior to any rendering.

datapublication:rowDrillDown – raised when the user has drilled down on a row by clicking a hyperlink

datapublication:rowClicked – raised when the user clicks on a row

datapublication:rowDoubleClicked – raised when the user double-clicks on a row

datapublication:rendering – raised prior to the data publication being rendered on the page

datapublication:rendered – raised after the data publication has been rendered on the page

datapublication:renderingHeader – raised prior to the data publication’s header being rendered on the page

datapublication:headerRendered – raised after the data publication’s header has been rendered on the page

datapublication:renderingRow – raised prior to a row being rendered in the data publication control

datapublication:rowRendered – raised after a row has been rendered in the data publication control

datapublication:renderingPagingBar – raised prior to the paging bar being rendered in the data publication control

datapublication:executingAction – raised prior to an action being executed (actions are commands that can be executed on a row)

datapublication:requestingContextMenu – raised prior to a context menu being requested from the server

DependantFieldView

To deprecate?

HTML Sample

bind=dependant

Attributes

Name	Description
id
name
class

EnumCollectionView

The EnumCollectionView can be used to display a list of checkboxes based on data from an EnumCollection field on the server. The user can select one or more options from this checkbox list.

HTML Sample

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead.
class

FieldView

The FieldView control is a generic data input field. It will display the value of a field from the server, and pass any update to that value back to the server. It can also be used to populate a label control with the label for the field obtained from the server.

Need to re-enable support for read-only fields without using attribute attribute (commented out code in FieldView)

Need a way to say “don’t use” (ignore?) on an element, so it won’t be populated with anything

Global configuration option to not auto search for elements to apply data to?

HTML Sample

Standard use:

Boolean input with display as a checkbox:

Displaying the label from the server along with the field:

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead.
anonymousboundmethod	The anonymous method to call to populate the list. Note: Don’t have a working example to demonstrate or confirm working.
class
checkedvalue	If the value element for the field is a checkbox, rather than sending a 1 to the server in response to it being selected (the default behaviour), you can get it to send whatever value you assign to this attribute instead.
uncheckedvalue	If the value element for the field is a checkbox, rather than sending a 0 to the server in response to it being deselected (the default behaviour), you can get it to send whatever value you assign to this attribute instead.
showError	Whenever an error occurs related to a field (for example, an email address with an invalid format has been entered), the SDK will add an element next to the field displaying the error message. This attribute enables you to disable this behaviour. TODO: Errors don’t appear when using the new way of defining fields without requiring a surrounding div. Should have a way of globally configuring this behaviour too.
valuetransformfunction	The name of a function that can modify the field’s value before the field displays it. The function should accept a value as its first argument, and return the modified value. Note that this attribute currently is to be applied to the sub-elements which have their attribute attribute value set, not the root element.
attribute
renderashtml	This attribute is used to tell the field to render the value as HTML instead of as text (which for security reasons is the default). You must ensure that you don’t simply echo user input to a field with this value set without sanitising it first, as it opens you up to Cross-Site Scripting (XSS) attacks.
appendcolon
ignore

FileUploadFieldView

The FileUploadFieldView control can be used to upload a file to the server.

Warning: This control will only work with HTML5 compliant browsers. In particular, it will not work with IE9 and below. It will work with IE10 however. If you want to support older browsers, use the KendoFileUploadAdapter adapter in conjunction with it.

HTML Sample

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead.
supportedfiletypes	A comma separated list of the file extensions that the user can upload. Optional.
maxfilesize	The maximum size of the file that a user can upload. Optional.
class

ImageFieldView

The ImageFieldView control can be used to display an image, given a URL.

HTML Sample

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead.

LoginView

Provides functionality for login screens.

Popup login screen.

Forgot password functionality?

HTML Sample

-

Should create the form for you (if wanted)

Attributes

Name	Description
name
type
authenticationMode

MainMenuView

The MainMenuView control renders the process map to the page.

HTML Sample

-

Attributes

Name	Description
id
renderhomeitem	Set this attribute to true if you want a menu item pointing to the home page rendered in the menu.
homeitemlabel	The text to display in the home menu item.
homeurl	The URL to navigate to when the user selects the home menu item.
renderlogoutitem	Set this attribute to true if you want a menu item enabling the user to log out of the application rendered in the menu.
logoutitemlabel	The text to display in the logout menu item.
renderbackitem	Set this attribute to true if you want a menu item that navigates to the previous page rendered in the menu.
backitemlabel	The text to display in the back menu item.
displayEmptyItems	Used to configure whether process areas with no activities should be rendered in the menu. Not currently used, and considered obsolete in favour of a global configuration option.

MessagesView

The MessagesView control is used to display any messages returned from the server.

HTML Sample

MethodView

The MethodView control calls a method on the server in response to a button/hyperlink click.

HTML Sample

As a button:

As a hyperlink:

Attributes

Name	Description
id	An identifier for this control (optional)
method	The name of the method to call on the server in response to a button/hyperlink click. If the method attribute doesn’t exist, then it will fall back to the name attribute, and then the id attribute.
methodattributes	You can send additional attributes with a Method request to the server using this attribute. The attributes are separated by semi-colons, and the key/value pair are separated by a colon. For example, methodattributes="key1:value1;key2:value2" will render in the server request as key1="value1" key2="value2" If you need to include the value of an input field as the value of one of the method attributes (useful when calling an anonymous method), then use the id of the input field as the value, surrounded by percentage characters. For example: methodattributes="key1:%inputid%"
contextobject	The context object to pass to the server for the method.
class

PicklistWindowView

The picklist window is displayed in response to the server asking for a picklist to be displayed. It will display as a popup window containing a list of items, and enabling the user to select one.

HTML Sample

The PopupView control cannot be configured in HTML, as it is only ever instantiated by the SDK.

PopupView

The PopupView control provides base functionality for displaying an inline popup window to the user.

Needs to be able to work without using kendo

Default implementation uses jQuery UI – to test

HTML Sample

The PopupView control cannot be configured in HTML, as it is only ever instantiated by the SDK.

UIMessage

The UIMessage control is used to display a popup message box to the user, containing a message and one or more buttons. It is instantiated and displayed when requested to by the server, which tells it what message to display, and what buttons to show. When the user clicks on a button, a corresponding method will be called on the server.

HTML Sample

The UIMessage control cannot be configured in HTML, as it is designed to be instantiated automatically in response to a message from the server.

VariantFieldView

The VariantFieldView control can be used to render a control based on the type and value of a variant field on the server. Variant fields are in the form of a question and an answer. They are usually defined by the user, who specifies a question for each field, and can configure the corresponding type of input that the user should be able to enter for the answer - as a text box, a check box, or a group of radio (option) buttons.

Variant fields can be used in one of two display modes, namely one question at a time or as a list of questions. The default display mode is list view. Each mode will be detailed separately below.

Displaying One Question at a Time

To configure the VariantFieldView to display one question at a time, you must define a separate field control that will render the question by mapping it to the .QText sub-field of the given variant field.

In addition to the field for the question, you must define the variant field itself which is used to capture the answer to the question. The answer may be captured via a text field, radio buttons, or via checkboxes. To indicate that the variant field is to display one question at a time, you should add the SDK display attribute set to oneAtATime. When displaying the variant field one question at a time, you must also provide navigation buttons to move back and forward through the questions. Optionally you may also provide a field to capture comments per question.

For example:

<br />

<label data-ex-attribute="label">Comments:</label>
<input id="commentsInput" data-ex-attribute="value">

</div>
<input id="prevButton" type="button" data-ex-bind="method" data-ex-method="TestItems.NavigatePrev" value="Prev" />
<input id="nextButton" type="button" data-ex-bind="method" data-ex-method="TestItems.NavigateNext" value="Next" />

</div>

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead. Note: You will always need to map the field id to the .Answer sub-field for this control to work.
display	Must be set to oneAtATime when used in this display mode.
class

Displaying as a List

To configure the VariantFieldView to display as a list, there are a number of attributes that should be set to control how the view is rendered. Each of these attributes are outlined in the table below. You may optionally provide a button to refresh the datapublication associated with the variant field - this will be required if autopopulate is set to false.

For example:

<button data-ex-bind="method" data-ex-method="listItemsForSurvey">Refresh</button>

Attributes

Name	Description
fieldid	The id of the field to map to on the server. If not supplied, the SDK will look for a name attribute and then an id attribute to use instead. Note: You will always need to map the field id to the .Answer sub-field for this control to work.
display	Can be set to *list* when used in this display mode (however this is the default display mode).
dataid	An id used to identify the data publication to the server. If not supplied, the SDK will look for a fieldid attribute, a name attribute, a query attribute, and finally a populatemethod attribute to use instead.
populatemethod	The name of a method to be used to populate the question/answer list with items.
fieldcontextobject	The context object to pass to the server for the field.
autopopulate	You can tell the server to not automatically return items for this data publication by setting the autopopulate attribute to false.
class

Dashboard Field

Not currently used, so working status is unknown.

HTML Sample

bind=dashboardfield

Attributes

Name	Description
id
name
dashboardname
class

requiresRole