Child pages
  • KB84836549: WebCenter - How to use the JavaScript button in the Attribute Category (explanation and examples)
Skip to end of metadata
Go to start of metadata

 

Description

In WebCenter 14, there is a new feature in Attribute Categories, called JavaScript Button. This article describes how to add the button along with few example scripts.

Read the WebCenter 14 User Documentation on help.esko.com to learn more about the Button functionality.

Procedure

Follow these steps to add a Button to your Attribute Category:

  1. Choose Attributes > Attribute Categories from the main Admin menu.
  2. Click an existing Attribute Category name to modify it (or add a new one).
  3. Click the Button  icon to add a new Button to your Attribute Category.
  4. Set the Button's Function to JavaScript. You can now add your own script in the JavaScript Code field.

Available objects

When entering the JavaScript code, a set of pre-built objects are made available to the script. These objects are all of type Array. They function as associative arrays. 

The available objects depend on which page the button is used. 

Pageattprojattdocattbomatt
Project attribute edit pageProject attributes(error)(error)(error)
Project creation pageProject attributes(error)Document attributes of documents in the project creation's documents sectionDocument attributes of documents in the project creation's bill of materials section
Document attribute edit pageDocument attributes

Project attributes

In case the document is in more than one project (linked documents), it will return project attributes of the 'first' project, which is quite random, so don't use in this case (unless you are sure the values will be the same anyway).

(error)(error)
Document fold-outs in Task execution page and in Bill of Materials pageDocument attributesProject attributes(error)(error)
Task execution pageTask specificationsProject attributes(error)(error)

att

att is an associative array containing the values of all attributes or specifications as in the above table. att['attribute 1'] is the value of attribute 1 in the current project or document or task (whichever you are editing). 

att['attribute 2']  = att['attribute 1'] + 1  (will set attribute 2 to 21 if attribute 1's value is 20). 

The JavaScript type of att['attribute x']  depends on the WebCenter type of the attribute.  It is

  • String for text attributes
  • Undefined for rich text attributes (you cannot use rich text attributes in JavaScript buttons, not to read or write)
  • Number for integer, float or unit based attributes. 
  • Date for date/time attributes

When changing the value of an attribute, make sure you give the right type. WebCenter will throw an error if it detects a wrong type.

Example:

att['Milestone Date'] = '1 Jan 2015';  (throws an error, expects a Date type but gets  a String type)

att['Milestone Date'] = new Date('Jan 1 2015') ;  (works fine)

projatt

When editing document attributes or task specifications, projatt contains the values of the project attributes. 

att['Brand'] = projatt['Brand']  will set the value of the document attribute Brand (or the task specification Brand) to the value of the project attribute Brand.

projatt is read only. You cannot set project attributes from the document attribute edit page or from the task execution page.

docatt

docatt is an array of arrays. You get one associative array for each document in the documents section of the project creation. 

docatt[0] is the first document. docatt[3]['attribute 1']  is the value of attribute 1 in the fourth document in the documents section. 

docatt.length is the number of documents in the documents section.

docatt is read only. You can read document attribute values from the project creation page but you cannot change them.

bomdocatt

Works like docatt but for the documents in the Bill of Materials section of the project creation page. If the section does not exist, bomdocatt is not defined or empty.

Remarks/frequent mistakes

  • As always with JavaScript, everything is case sensitive. att['Brand']  is something else than att['brand']. Also projAtt is something else than projatt. projAtt is not defined unless you did so (but that's a really bad idea).
  • docatt starts counting from 0, so does bomdocatt.
  • att['Brand']  can also be written as att.Brand. However this does not work anymore if the attribute has spaces and other reserved characters. So always use the notation with []. 
  • Make sure to add sufficient checking to your scripts. You are yourself the first victim of insufficient checking. Your script won't work and you will have no clue why. Check all your assumptions and throw alerts when they are not fulfilled. 
  • You can empty the value of an attribute by setting it to the empty string. So att['Milestone Date'] = ''; is valid. It will empty the field.
  • Multi-value attributes (which are always text based) are delivered with their encoded value. The values are separated with ' | ' (the pipe symbol between 2 spaces). So a multi-value attribute 'Country' with values Belgium and France will be equal to 'Belgium | France'. Make sure when delivering back the values to also correctly encode them.
  • After setting the value of an attribute which is part of a cascading drop-down, an attempt is made to execute the cascading. This attempt is not perfect. Since scripting can create lots of different unforeseen situations, the outcome can be somewhat unpredictable. 

Validation and error handling

Scripts can be used 'On Save'. This means that the script is executed just before saving the values to the server (and database). An additional object errorObj may be defined by your script and then returned. In case WebCenter gets a non-null object returned by the script, it will fail saving and show a validation error (you remain on your editing page). When returning a non-null object in other places (clicking a button during the session), the error will be displayed as a normal message. 

You can put your error message into errorObj.errorMsg

Example:

var errorObj = null;
if (!att['Target Date']) {
	errorObj = {errorMsg: 'Please set target date'};
} else {
	// put other code here
}
 
return errorObj;

Example scripts

Simple Calculation

Example:

// This script will take the product of the Unit Price and Number of Units attributes and put them in the Total Price attribute.
 
if (att['Unit Price'] == 0 || att['Number of Units'] == 0)
{
	alert('Please fill out the Price fields'); 
}

att['Total Price'] = att['Unit Price']*att['Number of Units'];

Fill out date attributes

When obtaining the value of a date attribute, you will get a Date object. You can do operations on this object and store it again. To store a value in a date attribute, only a Date object is accepted.

Example:

// This script will add 7 days to Date1 and fill it out in Date2
var date = new Date(att['Date1']);
date.setDate(date.getDate() + 7 )
att['Date2'] = date;

It is a good idea to create a new object from an obtained Date. This way, you will not accidentally overwrite the read attribute when doing operations on the object.

Check format of attribute

It is possible to check the value of an attribute with regular expressions.

Example:

// This script will check if the attribute ColorCode consists of 6 hexadecimal characters
var colorCode = att['ColorCode'];
if (colorCode && colorCode.match(/^[0-9A-Fa-f]{6}$/g))
{
	alert('ColorCode format is correct.'); 
} else {
	alert('ColorCode has to consist of 6 hexadecimal characters.'); 
}

Check barcodes

Barcode.js contains the code you can add in the JavaScript text input. You can paste the contents of this file in the JavaScript field.

You need to add the following attributes in your attribute category: Barcode Type and Barcode.

When clicking the Check Barcode button, your barcode will be checked. 

Article information
Applies to

WebCenter 14

Created12-Mar-14
Last revised20-Mar-17
AuthorHADW, BVON
CW Number-
Contents