Add-On Tabs

Using Custom Layouts, a URL tab or Document Template tab may be added to any data form which displays a custom web page. In addition to the content of the URL and Document Template, this page may optionally also contain HTML elements that will be used automatically by Clay for changing field values in the current record. I.e. these custom tabs may be used for both input and output. We shall call this functionality 'data entry fields'.

Note that the URL or Document Template may also contain javascript, graphical widgets and any other HTML element, so the sky is the limit in terms of its content, and the Clay field values for data entry are both supplied to and extracted from the HTML page using javascript as well using an encapsulating container iframe.

To configure a tab for data entry, add a URL or Document Template tab to the layout, check “Contains Data Entry Fields” and select the fields that it contains.

Note that with URL tabs, the URL may exist on an external web server, or in a local file on the client's hard drive. If the HTML page must be stored on the client's hard drive, then it is strongly recommended to copy it into the Addons folder (by default this is C:\DigitalClay\Addons\, but it may be configured in Tools/Options). For Web ClayStation, the addons folder must also be shared on the web server and the URL configured using the -addonurl setting. The addon folder location can be inserted into the URL string as a variable using the URL builder window. This allows each client to use its own add-on folder dynamically.

Important: Data entry URL tabs must be accessible by Digital-Clay clients (both desktop and web ClayStation), which means that the URL must not be in a different security zone or site than the zone where ClayStation is running. In other words, for desktop clients, the URL can only be on the local hard drive, and for web, the URL must be on the same web server which is hosting web ClayStation. This is due to web browser security limitations that restrict script access between two zones or sites. I.e. since, in these cases, Clay cannot read variables from the data entry HTML file and vice versa, data entry cannot work and you will receive javascript security errors. There is no workaround.

To auto-generate a default HTML file in the 'Addons' folder with a default two-column layout and javascript code that fills values and handles user-events, select the fields in the listbox, then click on “Create New File”. This file can then be modified and customized with any HTML and javascript editor.

Example

This is a sample HTML page demonstrating four custom data entry fields, each of which uses a different method for filling its value. The table this web page is configured for is Contacts, and the four fields are:

'Last Name' is set using a variable contained in the URL string.
'First Name' is set using the container data.
'Birthdate' is set dynamically to Now only when the user clicks on the button. This demonstrates the use of Javascript to populate a variable.
'Customer' uses a drop-down populated using the container data.

See below for more detailed explanations.

<HTML>
<HEAD>
<SCRIPT>
function getURLVar(urlName) {
 var urlVal='';var urlParms=String(document.location).split('?'); 
 if(urlParms[1]){ 
  var urlVars=urlParms[1].split('&');
  for(i=0; i<=(urlVars.length); i++){ 
   if(urlVars[i]){var urlPair=urlVars[i].split('='); if (urlPair[0] && urlPair[0]==urlName) { urlVal=urlPair[1]; }}
  }
 }
 return urlVal;   
}
</SCRIPT>
</HEAD>
<BODY STYLE="background-color:#F4F4F4;margin:10px;">

Last Name: <INPUT ID="clay7" VALUE=""><SCRIPT>document.getElementById('clay7').value=getURLVar('lname');</SCRIPT><BR>

First Name: <INPUT ID="clay6" VALUE=""><SCRIPT>document.getElementById('clay6').value=window.parent.clay.clay6.val;</SCRIPT><BR>

<CLAY ID="clay19"><INPUT TYPE="Button" Value="Set Birthdate to Now" onClick="document.getElementById('clay19').value=(new Date().valueOf()/1000);"><BR>

<SELECT ID="clay2">
<SCRIPT>
var ids=window.parent.clay.clay2.allids;var vals=window.parent.clay.clay2.allvals;
for (i=0;i<ids.length;i++) {document.write("<OPTION VALUE='" + ids[i] + "' " + (ids[i]==window.parent.clay.clay2.id?"SELECTED":"") + ">" + vals[i] + "</OPTION>");}
</SCRIPT>
</SELECT><BR>

</BODY>
</HTML>

Data Entry Fields/Input

The HTML page itself must be built or modified so that Digital-Clay may find the data entry fields:

For each field, there must be a corresponding DOM element in the HTML page. This element may be a standard HTML element like an <INPUT> textfield, an input element of type hidden (or any other input type), or it may even be a non-standard HTML tag like <FIELD>.

The DOM element must contain:

An 'ID' attribute with the word “clay” followed by the field number. Field numbers may be looked up using the Field Properties tool in ClayStudio.
A 'value' attribute. This attribute may be added dynamically to the HTML element using Javascript when appropriate

Note that date values are ideally transferred to and from Digital-Clay in Unixtime format (number of seconds since 1970), but may also be sent using a simple date format (e.g. '7/Jan/1985').

Output

The custom HTML page may retrieve data from Digital-Clay using any of the following methods:

If type is URL: Values taken from the URL itself. Add Digital-Clay fields or static variables to the URL using the URL builder form, and then retrieve them using Javascript such as with the 'getURLVar' function in the above example.

If type is Document Template: Using Document Template merge fields or queries (lists, analysis tables etc).

Using javascript by accessing the container iframe: The web page is actually displayed as an IFRAME embedded inside a container. This container holds Javascript data for each field that you configured in the Custom Layouts Data Entry list. To access this Javascript data, use the 'window.parent.clay object', followed by 'clay' and the field number (e.g. the Contact First Name field is 'window.parent.clay.clay6'). For each field, the following variables are added:
- 'val' contains the current field value.
- 'id' contains the current field value if the field is a linked field.
- 'vals' and 'ids' contain the field values (an array) if the field is a many-to-many field. To send values back to Digital-Clay, return a semi-colon separated list of IDs.
- 'allids' and 'allvals' contains an array of linked field values that may be used to populate a drop-down.
- 'allvals' contains an array of values for lookup list drop-downs.

Using Clay REST API and the current session ID variable inside a Document Template. See the note on Web Browser Security Restrictions however.

Events

Bi-directional events may be handled with custom javascript code contained in the HTML file. The events are either sent from the Digital-Clay form to the HTML document, or sent from the HTML document to the Digital-Clay form.

Note to programmers: Events are handled using DOM objects and javascript code in an HTML container that loads the custom HTML file. In other words, the HTML file with the data entry fields is actually displayed in an iframe which is contained inside a transparent auto-generated HTML container that stores the DOM object and javascript code for communicating with Digital-Clay.

The supported events are:

Field Changed

This is an event fired by the HTML file and sent to Digital-Clay in order to potentially fire Automation User-Generated events based on field changes. If an automation modifies the record as a result of the user-event, the Data Changed event will be sent back to the HTML file.

To fire this event, call the 'window.parent.clayFireEventFieldChanged(field)' function, where 'field' is the field ID that has changed.

Auto-generated file: By default, the auto-generated file contains javascript code for firing this event for every field.

Field Changed & Lost Focus

Identical to the previous, except this should be fired only when the field has changed and lost focus (blur).

To fire this event, call the 'window.parent.clayFireEventFieldChangedLostFocus(field)' function, where 'field' is the field ID that has changed.

Auto-generated file: The auto-generated file contains javascript code for firing this event for every field.

Data Changed

This is an event fired by Digital-Clay whenever the currently opened record has changed, either due to User-Events, or due to the user switching between tabs, or due to changes by another user or automation rules.

To handle this event, implement a 'clayDataChanged(clay)' javascript function in your HTML file, where 'clay' is a javascript object containing all of the field values (it is the window.parent.clay object).

Auto-generated file: The auto-generated file contains a clayLoad() function that loads values into their HTML components which is called by the event handler.

Auto-Fill

This is an event fired by Digital-Clay when a user-event has fired an auto-fill action for filling drop-down values with dynamic query results.

To handle this event, implement a 'clayAutofill(field,vals,ids)' javascript function in your HTML file, where 'field' is the field that is receiving new values, 'vals' is an array of display values to be shown in the drop-down, and 'ids' (only relevant for linked fields, not lookup fields) is an array of internal ids for the display values.

Auto-generated file: The auto-generated file contains a default clayFill() function that loads the new values into their drop-down components.

Save & Close

This is an event fired by the HTML file to instruct Digital-Clay to save the record (after retrieving current values from the HTML file), and optionally to close the form.

To fire this event, call the 'window.parent.clayFireEventSave(closeForm)' function, where 'closeForm' is a boolean value.

Auto-generated file: By default, the auto-generated file contains javascript code for firing this event based on the enter key being pressed in text & numeric fields.

Open Record

This is an event that may be fired by the HTML file to instruct Digital-Clay to open another record, including a new record in another table. This may be used to edit records in linked fields, or to add a new linked record. If the user saves the opened record, Digital-Clay responds with the 'Linked Data Changed' event.

To fire this event, call the 'window.parent.clayFireEventOpen(field,table,id)' function, where 'field' is the field id of the linked field (for tracking responses and what field they should be applied to), 'table' is the foreign table id, and 'id' is the internal id of the record (which may be retrieved from the linked field drop-down, or which may be set to 0 for a new record).

Auto-generated file: By default, linked fields in the auto-generated file contains javascript for opening the linked record via the Enter key, and also displays a button for adding a new record and linking back to it.

Linked Data Changed

This is an event fired by Digital-Clay whenever a record has changed that has been opened via the 'Open Record' event. This is useful when the user needs to edit/view a linked record, or add a new record which needs to be linked to in the current form.

To handle this event, implement a 'clayLinkedDataChanged(field,id,name,obj)' javascript function in your HTML file, where 'field' is the original field id that fired the event, 'id' is the internal id of the record (after it has been saved), 'name' is the display value of the record, and 'obj' is a javascript object containing all of the field values for the changed record (similar to window.parent.clay object).

Auto-generated file: The auto-generated file contains a clayLinkedDataChanged() function that either changes the currently displayed name in the linked field, or adds a new value in the drop-downs if the record is new.

Run Create Action

This is an instruction to Digital-Clay to run a Create Item action that has been previously configured in Digital-Clay ('Menus for Item Creation' feature).

To fire this event, call the 'window.parent.clayFireEventCreateAction(id)' function, where 'id' is the internal id of the action which must be manually looked up in the database in the 'NewMenus' table.

Run Edit Action

Similar to the above, except it calls an Edit Action. Note that if the current record is changed, a 'Data Changed' event will be fired back to the HTML file.

To fire this event, call the 'window.parent.clayFireEventEditAction(id)' function, where 'id' is the internal id of the action ('EditMenus' table).

Run Template Action

Similar to the above, except it calls a Template Action.

To fire this event, call the 'window.parent.clayFireEventTemplateAction(id)' function, where 'id' is the internal id of the action ('TemplateActions' table).

Digital Clay Knowledge Base

Table of Contents