🅾 Dropdown

Dropdown object represents a Dropdown input item on a Page or an AppPage.

Item-Specific Methods

🅼 getOptions() item

• Description: Returns the array of options currently shown in the drop-down. Each object in the array has a "title" property that is shown in the interface, and a "value" property that is saved into the data.
• Example:

  var theTitle = "";
  var opts = page.F_DropDown.getOptions();
  for(var i=0; i<opts.length; i++) {
    var theItemTitle = get(get(opts,i), 'title');
    var theItemValue = get(get(opts,i), 'value');
    if(theItemValue === 'Red') {
      theTitle = theItemTitle;
    }
  }

🅼 setOptions(options) item

• Description: Changes the list of options to show in the drop-down. It must be an array of objects. Each object must have a "title" property that is shown in the interface, and a "value" property that is saved into the data.
• Example:

  var options = new Array();
  options.push({title: 'Banana', value: 'BA'});
  options.push({title: 'Apple', value: 'AP'});
  options.push({title: 'Orange', value: 'OR'});
  item.setOptions(options);

Inherited Methods

The following methods are common to all Item objects: Ⓓ Ⓞ

🅼 addClasses(classes) itemapItem

Description: This method adds one or more custom CSS class names to an item, allowing for dynamic styling. You can pass a single class name, multiple class names separated by spaces, or an array of class names. If any class names are invalid, the method returns false and no classes are added.

Example:

item.addClasses("emphasized error");

In this example, the item will have the CSS classes emphasized and error added to it for styling purposes.

🅼 clearRequiredMessage() itemapItem

Description: Validates the item data but prevents any required field error messages from being displayed. This is useful in scenarios where you want to perform validation without user feedback.

Example:

item.clearRequiredMessage();

Use this method when you need to validate the item but do not wish to show error messages to the user.

🅼 connectEvent(eventName, callbackFunction) itemapItem

Description: Connects a method to an item event, allowing for dynamic behavior based on user actions or item changes. It returns a handle object that represents the connection, which can be used to disconnect the event later.

Example:

var hndl = item.connectEvent('onItemChange', function ()
{
    if (item.getBOAttr().getValue() === 'Yes') {
        form.getBO().F_SectionA.setVisible(true);
    }
}
)
;

Here, we connect a method to the onItemChange event that makes a section visible if the item's value is 'Yes'.

🅼 disconnectEvent(eventHandle) itemapItem

Description: Disconnects a previously connected event handler using the handle object returned by item.connectEvent. This is essential to prevent multiple instances of the event handler from being attached.

WARNING

If you connect an item event, you must also disconnect it in the same event. Otherwise, multiple versions of the connected code are attached every time the event is triggered.

Example:

var hndl = item.connectEvent('onItemChange', function()
{
    if (item.getBOAttr().getValue() === 'Yes')
        form.getBO().F_SectionA.setVisible(true);
}
)
;
item.disconnectEvent(hndl);

This example demonstrates connecting to an event and then immediately disconnecting it to ensure the event handler does not persist unnecessarily.

🅼 getActive() itemapItem

Description: Returns true if the item is active and false if it has been made read-only by a rule, stage, or custom JavaScript.

Example:

var isActive = item.getActive();

Use this method to check whether an item is active or read-only in your application logic.

🅼 getAppPage() apItem

• Description: Retrieves the page object to which the current item belongs.
• Example:

  var page = apItem.getAppPage();

🅼 getBO() item

• Description: Returns the Business Object (BO) for the entire form. This object represents the data model the form interacts with.
• Example:

  var businessObject = item.getBO();

🅼 getBOAttr() item

• Description: For items collecting data, this method returns the Business Object Attribute (BOA) containing that data. Returns null for interface-only items.
• Example: Get data for an item and set its value:

  item.getBOAttr().setValue(45);

🅼 getChildren() item

• Description: If an item contains children (e.g., a Section or Tab Folder), it returns a list object providing access to all direct children items. This list has getLength() and get(index) methods.
• Example: Rest all numbers inside a section to 0:

  var list = item.getChildren();
  for(var i = 0; i < list.getLength(); i++) {
    if(list.get(i).getType() === 'number') {
      list.get(i).getBOAttr().setValue(0);
    }
  }

🅼 getClasses() itemapItem

• Description: Returns an array of custom class names currently applied to the item.
• Example:

  var classes = item.getClasses();

🅼 getDisplayValue() itemapItem

• Description: Returns the current value being displayed, useful for getting the current, but not yet committed, value.
• Example:

  var displayValue = item.getDisplayValue();

🅼 getHoverText() itemapItem

• Description: Retrieves the current value set as hover text for the item.
• Example:

  var hoverText = item.getHoverText();

🅼 getHintText() itemapItem

• Description: Returns the value set as hint text for the item.
• Example:

  var hintText = item.getHintText();

🅼 getId() itemapItem

• Description: Retrieves the unique ID of the item within the application (e.g., F_FirstName).
• Example:

  var itemId = item.getId();

🅼 getInvalidMessage() apItem

• Description: An interface item that is collecting data, this method returns the Business Object Attribute that contains that data. If it is an interface-only item, then it returns null.

🅼 getPage() item

• Description: Returns the page object to which the item belongs. This can be useful for accessing the form object or other page-level attributes.
• Example: Get the form object:

  var form = item.getPage().getForm();

🅼 getParent() itemapItem

• Description: Retrieves the object that is the direct parent of the item, which can be a page, section, or tab folder.
• Example:

  var parentObject = item.getParent();

🅼 getPlaceholderText() itemapItem

• Description: Returns the current value set as placeholder text for the item.
• Example:

  var placeholderText = item.getPlaceholderText();

🅼 getRequired() apItem

• Description: Gets the value previously set using setRequired(), indicating if the item is required.
• Example:

  var isRequired = item.getRequired();

🅼 getRows() item

• Description: Returns the current value set as the number of rows displayed by the item. This is specifically for multi-line input areas.
• Example:

  var rows = item.getRows();

🅼 getStartLabel() item

• Description: Retrieves the label displayed at the start of a numeric or choice slider. This is useful for providing context or indicating the minimum value of the slider.
• Example:

  var startLabel = item.getStartLabel();
  console.log(startLabel); // Might print "Low" for a satisfaction slider

🅼 getStopLabel() item

• Description: Fetches the label displayed at the end of a numeric or choice slider, which usually represents the maximum value or condition.
• Example:

  var stopLabel = item.getStopLabel();
  console.log(stopLabel); // Could output "High" for a satisfaction slider

🅼 getStyle() item

• Description: Returns the current display style of an item. Note that this method is primarily applicable to Date and Time input fields.
• Example:

  var style = item.getStyle();
  console.log(style); // Outputs the style setting, like "MM/DD/YYYY" for a date field

🅼 getTitle() itemapItem

• Description: Retrieves the current value used as the field title, which is the text label associated with the item on the form.
• Example:

  var title = item.getTitle();
  console.log(title); // Prints the title of the item, such as "Date of Birth"

🅼 getType() itemapItem

• Description: Returns a string that identifies the object type. This can be useful for conditional logic based on the item type.
• Example:

  var itemType = item.getType();
  console.log(itemType); // For example, "date" for a date picker item

Return values

Palette Item	Type
Attachment	attachment
Button	button
Check Box	checkBox
Currency	currency
Date	date
Dropdown	comboBox
Email Address	emailAddress
Folder Tab	tabFolderTab
HTML Fragment	htmlArea
Image	image
Line	horizontalLine
Media	media
Number	number
Numeric Slider	horizontalSlider
Page	page
Page Navigation	pageNavigator
Paragraph Text	textArea
Password	password
Section	section
Select Many	checkGroup
Select One	radioGroup
Single Line	text
Survey	survey
Survey Question	surveyQuestion
Tabbed folder	tabFolder
Table	aggregationListContainer
Text	richText
Time	time
Timestamp	timeStamp
Web Link	staticWebLink
Website	weblink
Name Picker	name
Data Grid	dataGrid
Rich text	richTextArea

🅼 getValid() apItem

• Description: Retrieves the validity status of an item as previously set by setValid(). This method is crucial for form validations.
• Example:

  var isValid = item.getValid();
  console.log(isValid); // Outputs true or false based on validity.

🅼 getValue()` itemapItem

• Description: Returns the current value of an item. The type of the returned value depends on the item's data type (e.g., String, Number, Boolean, Date, Object).
• Example:

  var value = item.getValue();
  console.log(value); // Outputs the item's value, format depends on the item type.

Here are some examples of what is returned:

• String - check and radio list objects return a delimited list with # as the delimiter
• Number - number, currency,
• Boolean, Date - date, timestamp, time
• Object - attachment

🅼 getVisible() itemapItem

• Description: Determines whether an item is visible on the form. It returns true if visible, false if hidden by a rule, JavaScript, or if its parent item is hidden.
• Example:

  var isVisible = item.getVisible();
  console.log(isVisible); // true or false

🅼 isMissing() apItem

• Description: Returns true if this item is required and it has no value.

🅼 isRequired() apItem

• Description: Returns true if the item is required, otherwise false.

🅼 isValid() apItem

• Description: Returns true if the data is valid. Returns false if the data is invalid.

🅼 removeClasses(classes) itemapItem

• Description: Removes one or more custom CSS class names from an item. The classes parameter can be a single class name, multiple class names separated by spaces, or an Array of class names.
• Example:

  item.removeClasses("emphasized");
  // This will remove the "emphasized" class from the item.

🅼 setActive(active) itemapItem

• Description: Sets whether an item is active or read-only. An item made inactive by a rule or stage cannot be made active with this method.
• Example:

  item.setActive(false);
  // This will make the item read-only.

🅼 setDisplayValue(pValue) itemapItem

• Description: Takes a string or number in pValue. This method sets the value being displayed. If the user is editing, then it will update the value they are trying to enter. If the user is not editing, then it will be the same as setValue(). This method works on direct input items such as single line, multi line, number, currency, email and website. This method is applicable to direct input items like single line, multi-line, number, currency, email, and website fields.
• Example:

  item.setDisplayValue("John Doe");
  // Sets the display value of an item to "John Doe".

🅼 setFocus() itemapItem

• Description: Causes the item to receive focus, making it the active element on the page. This method only works if the item can receive focus, is visible, and is not read-only.
• Example:

  item.setFocus();
  // The item will gain focus, allowing the user to start typing or interacting with it directly.

🅼 setHintText(pValue) itemapItem

• Description: Sets the hint text for an item, which is displayed as hover text over input fields. Providing an empty string will remove any existing hint text.
• Example:

  item.setHintText("Please enter your full name");
  // Sets the hover hint text for the item to guide the user on what to input.

🅼 setHoverText(pValue) itemapItem

• Description: Sets the hover text for an item, providing users with helpful information when they hover over the item. An empty string removes the hover text.
• Example:

  item.setHoverText("This field is for your email address");
  // Sets hover text for the item, offering additional guidance or information.

🅼 setRequired(required) apItem

• Description: Overrides the item's default requirement state. Setting this to true makes the item's data required, preventing form submission if the item is not filled. Setting it to false clears any override, returning it to its original state.
• Example:

  item.setRequired(true);
  // Now, the form cannot be submitted unless this item is filled out.

🅼 setRows(pValue) item

• Description: Adjusts the number of rows displayed by a text area item. This is useful for ensuring that the text area size accommodates the expected length of user input.

  TIP

  It is recommended not to exceed 40 rows for usability reasons.

• Example:

  item.setRows(5);
  // Sets the text area item to display 5 rows.

🅼 setPlaceholderText(pValue) itemapItem

• Description: This method updates the placeholder text in input items, which is the grayed-out text inside the input box before any information is entered by the user.
• Example:

  item.setPlaceholderText("Enter your name");
  // Sets the placeholder text to "Enter your name".

🅼 setStartLabel(pValue) item

• Description: Sets the label displayed at the beginning of a numeric or choice slider, typically representing the minimum value or start of a range.
• Example:

  item.setStartLabel("Low");
  // Sets the start label of a slider to "Low".

🅼 setStopLabel(pValue) item

• Description: Updates the label displayed at the end of a numeric or choice slider, usually indicating the maximum value or end of a range.
• Example:

  item.setStopLabel("High");
  // Sets the stop label of a slider to "High".

🅼 setStyle(pValue) item

• Description: Configures the display style for date and time input fields. Valid values for dates include numeric, short, medium, long, and full. For time, valid options are numeric, short, and medium.
• Example:

  item.setStyle("medium");
  // Sets the date or time display style to "medium".

🅼 setTitle(pValue) itemapItem

• Description: Assigns text to be used as the title for field items. This text is typically displayed above the input field or item as a label.
• Example:

  item.setTitle("Email Address");
  // Sets the title of an item to "Email Address".

🅼 setValid(valid, msg) apItem

• Description: Overrides the current validity state of data in an item. Setting valid to false marks the data as invalid and can prevent form submission, with an optional custom error message.
• Example:

  item.setValid(false, "This field is required.");
  // Marks the item data as invalid and provides a custom error message.

🅼 setValue(pValue) itemapItem`

• Description: Updates the value of an item based on the Business Object Attribute's type. It's important to provide data in the correct type, although some type conversion is handled automatically (e.g., Number to String).
• Example:

  item.setValue("John Doe");
  // Sets the item's value to "John Doe".

Here are the merged sections as per your example:

🅼 setVisible(visible) itemapItem

• Description: Controls the visibility of an item on your form. It's useful for showing or hiding elements based on certain conditions. setVisible(visible) where visible is a boolean indicating whether the item should be visible (true) or hidden (false). Note that if an item is hidden by a rule, stage, or because its parent item is hidden, you cannot make it visible using this method.
• Example:

  item.setVisible(true); // Makes the item visible
  item.setVisible(false); // Hides the item

🅼 validate() apItem

• Description: Triggers the validation process for a data item. Use this method to manually initiate the validation rules applied to the item, ensuring the data entered by the user meets the required criteria before proceeding. validate() takes no parameters.
• Example:

  item.validate(); // Triggers validation for the item

🅼 getColumnHeaders() item

• Description: Retrieves the current configuration of column headers for a table, including each column's ID, title, and width. This can be useful for dynamically adjusting table headers based on certain conditions. getColumnHeaders() returns a JSON object with the details of each column header in a table.
• Example:

  var headers = item.getColumnHeaders();
  for(var h in headers) {
    console.log("ID=" + headers[h].id + ", Title=" + headers[h].title + ", Width=" + headers[h].width);
  }

🅼 setColumnHeaders(headers) item

• Description: Allows you to dynamically set or update the column headers of a table. This method is particularly useful for changing the language of column headers or adjusting their presentation based on user input. setColumnHeaders(headers) where headers is a JSON object containing the ID, title, and width for each column.
• Example:

  var headers = [
    {id: "F_Currency1", title: "Currency", width: 20},
    {id: "F_Date1", title: "Date"}
  ];
  item.setColumnHeaders(headers);

Objects available in the item event context

🅾Application object (GUI type)

• Variable: app
• Description: Contains methods for accessing global general information.
• Example: app.isSingleFormView();

🅾 Page object (GUI type)

• Variable: page
• Description: For accessing the Page and the items on it.
• Example: page.F_Text.setContent('This is a Label');

🅾 Form object (GUI type)

• Variable: form
• Description: For accessing the pages and controlling page navigation.
• Example: form.getPage('P_Page1');

🅾 Item object (GUI type)

• Variable: item
• Description: The object representing the current item.
• Example: item.setVisible(true);

🅾 Business Object (DATA type)

• Variable: BO
• Description: Top-level data object for the form.
• Example: BO.F_Username.getValue();

🅾 Business Object Attribute object (DATA type)

• Variable: BOA
• Description: Object representing the Data for the current item. Only present for data items.
• Example: BOA.setValue("Please enter your Name");

🅾 App Page Object (GUI type)

• Variable: appPage
• Description: For accessing the app page and the items on it.
• Example: appPage.F_SingleLine1.getValue()

🅾 Item on an App Page (GUI/data type)

• Variable: apItem
• Description: The object representing the current item on an app page.
• Example: apItem.setValue("app pages are great!")

Dropdown Events

🅴 beforeOptionsUpdate

Event Name: beforeOptionsUpdate

Parameters: The array of options is passed in as pOptions and can be modified by the event code.

Description: This event is called before the options in a drop-down list are updated from a service call or from an API call. By default, when a new options list is set into a drop-down list and the current selected item is not in the new list, it is added into the new list automatically. If you return false from this event, it does not copy the missing option into the new list.

Example:

pOptions.push({title: 'Pizza', value: 'fooditem3'});
return false;

Inherited Events

The following events are common to all Items:

🅴 onClick

Event Name: onClick

Description: Called every time that the item is selected by the user.

🅴 onHide

Event Name: onHide

Description: Called every time that the item is hidden, whether just itself or the entire page.

🅴 onInvalid (only data items)

Event Name: onInvalid

Description: Called when a data item goes from being valid to invalid.

🅴 onItemBlur

Event Name: onItemBlur

Description: Called when the item is blurred (focus is lost).

🅴 onItemChange

Event Name: onItemChange

Description: Called when the item data is changed and saved into the Business Object. For some types of items, it occurs when the user tabs or switches focus, for example, when users select Number, Single Line, Multi-Line, and Currency form items. For other items, it occurs every time they make a change, such as Check Box, Survey, or drop-down.

Note

You cannot change the value of an item within this event as its value has changed, and it is locked.

🅴 onItemFocus

Event Name: onItemFocus

Description: Called when focus is received by an item.

🅴 onItemLiveChange

(items which can be incrementally changed)

Event Name: onItemLiveChange

Description: Called every time data is entered but not yet updated to the Business Object, such as Number, Single Line, Multi-Line, and Currency.

🅴 onMouseOut

Event Name: onMouseOut

Description: Called every time the mouse moves out of the item bounding area (not including label).

🅴 onMouseOver

Event Name: onMouseOver

Description: Called every time the mouse moves into the item bounding area (not including label).

🅴 onShow

Event Name: onShow

Description: Called every time the item goes from being hidden to being shown, whether from a page flip or because of a rule or JavaScript™ change.

🅴 onValid

(only data items)

Event Name: onValid

Description: Called when a data item goes from being invalid to valid.