Configurable Forms

This guide covers the use of configurable forms.

Components Using the Configurable Form

In Apogee there is a configurable form widget that is used in several places to easily define forms for the user. This document gives the reference information for using these configurable forms.

Two examples where these are used are the components Form Data Table and Dynamic Form. For an example of using these components, see the tutorial Configurable Form Components.

A Form Data Table is similar to a JSON Data Table except the user enters data into a configurable form rather than text editor. The configurable form is defined by the programmer. When the user changes the value, the save bar appears just as if the user changed the value of a data table. When the user saves, the data is saved to an internal data table which can be accessed from the code.

A Dynamic Form is a table that is like a non-modal dialog box. Here the programmer also configures the layout of the form, which should include a submit button to take action. The programmer defines a handler for the save button which can take any action he wants. Unlike with the Form Data Table, there is no data saved in the Dynamic Form.

In either of these components, the programmer must define the layout for the form, which is described in this document.

Configurable Panel and Configurable Elements

The name of the configurable form is actually ConfigurablePanel. It includes a list of entries, which are called ConfigurableElements. There are several types of configurable elements.

The layout for the form is JSON/javascript object which gives the list of configurable elements and the initialization of each.

We will show a quick example of using a configurable panel with a Form Data Table.

The following JSON gives a sample layout that includes the following elements:

  • Title

  • Text Field

  • Radio Button Group

[
	{
		"type": "heading",
		"level": 2,
		"text": "Test Form"
	},
	{
		"type": "textField",
		"label": "Test text entry: ",
		"value": "Hello There",
		"key": "text1"
	},
	{
		"type": "radioButtonGroup",
		"label": "Radio 1: ",
		"groupName": "rg1",
		"entries": [
			"antelope",
			"buffalo",
			"cat",
			"dog"
		],
		"value": "dog",
		"key": "radioGroup1"
	}
]

Using this layout JSON in a Form Data Table, we return this value from the layout code as follows:

This creates the following form:

If we change the radio buttons, we get the save bar, just as if we edited the value of a plain data table.

Pressing Save...

Now if we go to the Form Value view of the Form Data Component, we see what result value is associated with this form content.

Element Types

The section gives the available types of elements and the configuration rules for each. There are also some additional configuration options listed below in the section Shared Configuration Options.

CheckboxElement

This is a simple, singular check box.

Init Data:

  • type - "checkbox"

  • label - The label for the checkbox (optional)

  • value - initial value: true/false (optional)

  • key - The key used to report this value in the form result

  • onChange(elementValue,formObject) - handler called when the value of this checkbox changes (optional)

CheckboxGroupElement

This is a group of checkboxes.

Init Data:

  • type - "checkboxGroup"

  • label - The label for the checkbox group (optional)

  • entries - array of values, one for each checkbox (optional)

  • value - a list containing the values for the checked checkboxes

  • key - The key used to report this value in the form result

  • horizontal - if this is set to true the checkboxes will be arranged horizontally, to the extent this is possible. Otherwise they will be placed one to each line. (optional)

  • onChange(elementValue,formObject) - handler called when the value of this checkbox changes (optional)

DropdownElement

This is a dropdown element.

Init Data:

  • type - "dropdown"

  • label - The label for the dropdown (optional)

  • entries - array of values in the dropdown

  • value - this initial value for the dropdown (optional)

  • key - The key used to report this value in the form result

  • onChange(elementValue,formObject) - handler called when the value of this checkbox changes (optional)

HtmlDisplayElement

This is an element that displays arbitrary HTML.

Init Data:

  • type - "htmlDisplay"

  • html - This is the HTML string

HeadingElement

This is a heading element.

Init Data:

  • type - "heading"

  • text - This is the text for the heading

  • level - This gives the weight of the heading, like the weight in an HTML heading.

InvisibleElement

This is an element that holds a value but is non-interactive and not visible.

Init Data:

  • type - "invisible"

  • value - The value for the element

  • key - The key for the element

PanelElement

This is an panel that contains a list of child elements.

InitData

  • type - "panel"

  • formData - This is the init data for the form, in the same format as the init data for the parent panel.

  • onChange - This is a handler for when the element changes. It differs from the onChange handler for the form in the panel only in that the panel form onChange function includes the panel entry as an argument. The Element on onChange function includes the parent panel as an argument, just as is done on the other elements.

  • key - The key for the element

RadioGroupElement

This is a group of radio buttons.

Init Data:

  • type - "radioButtonGroup"

  • groupName - the HTML radio button group name

  • label - The label for the radio button group (optional)

  • entries - array of values, one for each radio button

  • value - the value of the initially checked button (optional)

  • key - The key used to report this value in the form result

  • horizontal - if this is set to true the checkboxes will be arranged horizontally, to the extent this is possible. Otherwise they will be placed one to each line. (optional)

  • onChange(elementValue,formObject) - handler called when the value of this checkbox changes (optional)

SpacerElement

This is an element to add some vertical space to the form.

Init Data:

  • type - "spacer"

  • height - pixel height for the space (optional - current default = 15px)

TextFieldElement

This is a text field.

Init Data:

  • type - "textField"

  • label - The label for the text field (optional)

  • value - the initial value (optional)

  • key - The key used to report this value in the form result

  • password - if this is true, the field is a password field (optional)

  • size - the character width of the text field. (optional)

  • onChange(elementValue,formObject) - handler called when the value of this element changes (optional)

  • onChangeCompleted(elementValue,formObject) - handler called when the element loses focus and was changed (optional)

TextareaElement

This is a text area.

Init Data:

  • type - "textarea"

  • label - The label for the text field (optional)

  • value - the initial value (optional)

  • key - The key used to report this value in the form result

  • rows - The number of rows in the text area. (optional)

  • cols - The number of columns in the text area. (optional)

  • onChange(elementValue,formObject) - handler called when the value of this element changes (optional)

  • onChangeCompleted(elementValue,formObject) - handler called when the element loses focus and was changed (optional)

Custom Element

This is a custom element. It is made by explicitly constructing a configurable element so it has the proper functionality. (This is done because at the time there is no support for "class" in the code. If this is added you can pass in a constructor that extends ConfigurableElement).

Init Data:

  • type - "custom"

  • key - The key used to report this value in the form result

  • builderFunction - This is a function which converts a base ConfigurableElement into the custom element.

SubmitElement

This element provides a submit button and a cancel button, to control the panel

Init Data:

  • type - "submit"

  • key - The key used to identify the element

  • submitLabel - a label for the submit button. Default is "OK"

  • cancelLabel - a label for the second button. Default is "Cancel"

  • submitDisabled - this enables or disables the submit button (optional)

  • cancelDisabled - this enables or disables the cancel button (optional)

  • onSubmit(formValue,formObject) - handler called when the value of this element changes (optional)

  • onCancel(formObject) - handler called when the element loses focus and was changed (optional)

Additional Element Functions

  • submitDisable(boolean) - this enables or disables the submit button

  • cancelDisable(boolean) - this enables or disables the cancel button

Shared Configuration Options

In addition to the above listed initialization options, there are some additional options common to all elements.

  • state - The state for the form element. The following states are available:

    • apogeeapp.ui.ConfigurableElement.STATE_NORMAL - The element is visible and not disabled.

    • apogeeapp.ui.ConfigurableElement.STATE_DISABLED - The element is visible but disabled.

    • apogeeapp.ui.ConfigurableElement.STATE_HIDDEN - The element is not visible. However, any value it holds is included in the value of the form.

    • apogeeapp.ui.ConfigurableElement.STATE_INACTIVE - The element is not visible and the element value is NOT included in the value of the form.

  • selector - This can be used to display an element based on a parent selection. It is most often used for panels but can be used for any element. This is an object with the following fields.

    • parentKey - The key for the parent. The parent must be in the same panel and be before the child.

    • parentValue - This is the value of the parent that triggers display of the child.

    • keepActiveOnHide - If this is true the form value will return the value of any element wether it is hidden or not. This is how a tab would typically work. If the value is false or undefined then only the visible panel is included in the form value.

  • onChange(elementValue,formObject) - A standard event for elements. It is further described under each element.

Using the Selector

We will modify the example form above to add an option "custom" to the list of animals, and an additional text field to input the type of the custom animal. We will use the selector on the custom animal type field so that it is only visible is "custom" is selected from the list of animals.

[
	{
		"type": "heading",
		"level": 2,
		"text": "Test Form"
	},
	{
		"type": "textField",
		"label": "Test text entry: ",
		"value": "Hello There",
		"key": "text1"
	},
	{
		"type": "radioButtonGroup",
		"label": "Radio 1: ",
		"groupName": "rg1",
		"entries": [
			"antelope",
			"buffalo",
			"cat",
			"dog",
			"custom"
		],
		"value": "dog",
		"key": "radioGroup1"
	},
	{
		"type": "textField",
		"label": "Custom Animal: ",
		"key": "customAnimal",
		"selector": {
		    "parentKey": "radioGroup1",
		    "parentValue": "custom",
		    "keepActiveOnHide": false
		}
	}
];

In the selector on the new text field, the parentKey is "radioGroup1", which is the element we want to control the visibility of our new text field.

The parentValue is "custom". This means the new text field will be visible only if radioGroup1 holds the value "custom".

Lastly, we have included the field keepActiveOnHide. Since this is false, when the radioGroup1 is not "custom", the value of this field does not appear in the form value.

Here is the form when we do not select "custom".

And here is the form when we do select "custom".

Additional Reference

In more advanced usage of forms, such as if you are incorporating one in a custom form.

Configurable Form Panel

Methods

  • constructor(optionalContainerClassName) - Creates the form, passing the initialization value. Optionally, a container CSS class can be specified.

  • configureForm(formInitData) - This method constructs the form inside the panel. It can be called as many times as desired to reconfigure the panel.

    • formInitData format - This is a javascript/json object with the following fields:

      • layout - (REQUIRED) This is an array of initialization elements defining the elements in the form.

      • onSubmit - (OPTIONAL) This is a javscript/json object that adds a submit button to the form. The submit button may also be added as an individual layout element. The fields in this object are:

        • onSubmit - This function is a handler for the submit action. If it is not included there is no submit button.

        • onCancel - This function is a handler for the cancel action. if it is not included there is no cancel button.

        • submitLabel - This is an optional label for the submit button.

        • cancelLabel - This is an optional label for the cancel button.

      • onChange - (OPTIONAL) This handler is called whenever the form changes. The arguments are (formValue,formObject).

      • disabled - (OPTIONAL) If this field is set to true, the form will be disabled.

  • getEntry(key) - This gets a Form Element, by key, from the panel.

  • getValue() - This gets the value for the form.

  • setValue(formValue) - This sets the value for the form.

  • getElement() - This returns the DOM element for the panel.

  • getChildEntries() - This returns an array of form elements.

  • addSubmit(onSubmit,onCancel,optionalSubmitLable,optionalCancelLabel) - This is an additional way of adding a submit entry to a form, besides using the initData for the panel.

  • addOnChange(onChange) - This is called if the form changes value. The onChange function is passed the arguments (formValue, formObject)

  • setDisabled(isDisabled) - This enables or disables the form.

Configurable Form Elements

Methods

The following functions are available on each form element:

  • getKey() - returns the key for this element

  • getState() - returns the state for this element

    • the form value. (In all other states the value is included)

  • setState(state) - sets the state for this element

  • setValue(value) - sets the value for this element

  • getElement() - returns the DOM element for this for element

  • getForm() - returns the parent form for this element

PreviousApogee v0.8.8 - Programming GuidesNextCustom Components and The HtmlJsDataDisplay

Last updated

Was this helpful?