Click Handlers
Description
A click handler defined in the data source configuration will enable a click handler on all events for this data source. Kinetic Schedule will execute the defined click handler instructions instead of retrieving and displaying the event details in a dialog window.
A click handler defined in the calendar configuaration will enable a click handler for view container. This will allow Kinetic Schedule to execute a javascript function or open a URL when the user clicks in any open time slot in the schedule view.
A click handler defined in the resource confiruation will enable a click handler on all resource rows. This allows Kinetic Schedule to execute a javascript function or open a URL when the user clicks on a cell with a resource name. The javascript function or URL could contain code that looks up details about this resource and displays that information to the user.
Any number of parameters may be defined to send additional information to the javascript function or URL.
Types of Click Handlers
A click handler can be defined as either a URL click handler, or a Javascript click handler. A URL click handler opens the web browser to a URL, and a Javascript click handler runs a pre-defined javascript function.
Please see the URL Click Handler page or the Javascript Click Handler page for details about the different click handlers.
Click Handler Configuration
The configuration properties for click handlers vary depending on what type of object the click handler is associated with (calendar, resource, data source). But the basic configuration properties that all click handlers share is as follows:
"clickHandler": { "type": "typeValue - Either js or url", "callback": "callbackValue - js function or url", "target": "targetValue - ** URL click handler ONLY - either _blank or _self", "showDialogFirst": "false", "startTimeParameter": "startTime", "parameters": [ { "name1": "parameterName1", "value": "staticValue1" }, { "name2": "parameterName2", "value": "{{dynamicValue2}}" } ] }
type
The type property indicates whether the click handler should execueta a javascript function, or open a web browser to a URL.
Possible values are: "js" or "url"
callback
The callback property depends on the type of click handler. For a javascript click handler, the callback must be the name of a javascript function that is loaded when the page is rendered. For a URL click handler, the callback is the base URL that will be opened in a web browser.
target
The target property is only used for URL click handlers, and specified if the web browser should open the URL in a new browser window or tab (_blank), or in the current browser window or tab (_self).
showDialogFirst
When set to true, a dialog will prompt the user for confirmation to run the clickhandler. If false, the clickhandler will run immediately without prompting the user for confirmation.
startTimeParameter
The name of the parameter that should be used to indicate the date/time of the open time slot the user clicked in the scheduule view. This parameter is only used for the calendar configuration, it is ignored for the resource configuration and any datasource configurations.
parameters
Parameters are a way to send information to the click handler callback. This information can be specific to the object that was clicked, or hard-coded static values.
Parameters consist of a list of objects that contain a name and a value property. The name property will simply be the name of the parameter passed to the callback, and the value may be static text, data from the object, or a combination of both.
The number of properties that can be passed to the callback is unlimited. Simply comma-separate each parameter object in the list.
Static Parameters
Static parameters simply contain hard-coded values that will be passed to the callback. The value is sent to the callback as it is written, there is no property substitution with static parameters. An example of a static parameter is:
"duration": 60
Dynamic Parameters
Dynamic parameters contain the names of object properties that the application dynamically substitutes with the corresponding property value of the object that the user clicked. Properties that are to be substituted dynamically must be wrapped in double curly braces such as:
"parameterName1": "{{propertyName}}"
Please see the sections below for a comprehensive property list for each type of object that can be used as dynamic parameters.
Mixed Parameters
Mixed parameters contain both static text and dynamic properties. The static portion is sent as is, and dynamic portion is substituted with the object's property value. An example of a mixed parameter is:
"parameterName1": "Mixed value - {{propertyName}}"
Event Properties
The event properties that are available to use consist of the core event fields, and any filter mappings that have been configured on the data source.
Property Name | Description |
sourceMapResourceId | The unique key value of the resource this event is related to |
sourceMapDatasourceValuesKeyId | The unique key value of this event |
sourceMapName | The event name |
sourceMapDescription | The event description |
sourceMapStart | The event start date/time |
sourceMapEnd | The event end date/time |
filterFields['Name of Filter'] | A filter mapping field defined in the data source configuration. The name in the square bracket must match the name property of the filter mapping. |
Resource Properties
The resource properties that are available to use consist of the resource key and value fields, and any filter mappings that have been configured on the resource.
Property Name | Description |
sourceMapKey | The unique key value of this resource |
sourceMapValue | The resource name or label |
filterFields['Name of Filter'] | A filter mapping field defined in the resource configuration. The name in the square bracket must match the name property of the filter mapping. |
Calendar Properties
This is a list of the properties that are available to use in the calendar click handler parameters.
Property Name | Description |
uuid | The unique calendar Id |
webname | The unique calendar webname |
name | The calendar name |
description | The calendar description |
clickedDateTime | The date/time of the point where the user clicked the open calendar time slot (yyyyMMddTHH:mm:ss) |
An example click handler from a calendar configuration file. In this example, an object that contains eight parameters will be sent to the KD.calendar.Theme.exampleShowParameters javascript function. If the click handler was a URL type of handler, the parameters would be evaluated and sent on the URL as query string parameters.
"clickHandler": { "type": "js", "callback": "KD.calendar.Theme.exampleShowParameters", "target": "_blank", "showDialogFirst": "false", "startTimeParameter": "startTime", "parameters": [ { "name": "resourceId", "value": "{{sourceMapKey}}" }, { "name": "eventType", "value": "{{sourceMapDatasourceValuesKeyId}}" }, { "name": "duration", "value": "60" } ] }
The parameters can be named anything, but in this example they are named:
- resourceId
- eventType
- duration
These parameters can be used in the callback handler for any purpose. The example javascript function just displays an alert message that shows the parameter names and values.