π Ύ Section β
Section object represents one section on a Page or an AppPage.
Specific Methods β
π Ό getExpanded() item β
- Description: Returns
true
if the section is expanded andfalse
if it is collapsed.
π Ό setExpanded(expanded) item β
- Description: Sets the expanded state of the section. If
true
, the section is expanded. Iffalse
, then it is collapsed. - Example:javascript
item.setExpanded(true); // Expands the section. item.setExpanded(false); // Collapses the section.
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:javascript
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:javascript
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:javascript
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()
andget(index)
methods. - Example: Rest all numbers inside a section to 0:javascript
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:javascript
var classes = item.getClasses();
π Ό getDisplayValue() itemapItem β
- Description: Returns the current value being displayed, useful for getting the current, but not yet committed, value.
- Example:javascript
var displayValue = item.getDisplayValue();
π Ό getHoverText() itemapItem β
- Description: Retrieves the current value set as hover text for the item.
- Example:javascript
var hoverText = item.getHoverText();
π Ό getHintText() itemapItem β
- Description: Returns the value set as hint text for the item.
- Example:javascript
var hintText = item.getHintText();
π Ό getId() itemapItem β
- Description: Retrieves the unique ID of the item within the application (e.g., F_FirstName).
- Example:javascript
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:javascript
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:javascript
var parentObject = item.getParent();
π Ό getPlaceholderText() itemapItem β
- Description: Returns the current value set as placeholder text for the item.
- Example:javascript
var placeholderText = item.getPlaceholderText();
π Ό getRequired() apItem β
- Description: Gets the value previously set using
setRequired()
, indicating if the item is required. - Example:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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:javascript
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 assetValue()
. 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:javascript
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:javascript
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:javascript
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:javascript
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 tofalse
clears any override, returning it to its original state. - Example:javascript
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:
javascriptitem.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:javascript
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:javascript
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:javascript
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
, andfull
. For time, valid options arenumeric
,short
, andmedium
. - Example:javascript
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:javascript
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
tofalse
marks the data as invalid and can prevent form submission, with an optional custom error message. - Example:javascript
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:javascript
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)
wherevisible
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:javascript
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:javascript
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:javascript
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)
whereheaders
is a JSON object containing the ID, title, and width for each column. - Example:javascript
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!")
Specific Events β
π ΄ onCollapse β
Event Name: onCollapse
Description: Called when the section is collapsed.
π ΄ onExpand β
Event Name: onExpand
Description: Called when the section is expanded.
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.