Form scripting
The form is the central data entry component and plays a vital role in any Topincs store. A system can work fine with modelling and the standard form validation provided by the compound constraint. Yet, the requirements sometimes demand to add more behavior and this is where form scripting comes in.
Here is some typical examples of what you can achieve by scripting:
- Whitelist: restrict the options when selecting a counter player.
- Complete other fields: given some input, compute the value of another input element.
- Augment info: add some info for display computed from the current form input.
Basic idea
Hint: In the Topic Maps Data Model statements (names, occurrences, associations) have identity. This is a very important feature for Topincs under the hood. But during programming, on the server with the Topincs API and here on the client with the form API can be neglected without any loss.
The form runs in the browser and therefore we use JavaScript to add additional functionality to the form. Every form edits eactly one topic, yet we actually never deal with the topic directly only the current state of the topic within the browser window, therefore we speak of form. A form is composed of paragraphs which consider the statements as a mere scalar value without further structure. This is best illustrated by a simple code example.
A first look at scripting
// Given a topic type Person with first name and age.
console.log(form.firstName.value);
console.log(form.age.value);
// Console output for new topic:
null
null
// Console output for old topic:
Mary
8
Source code location
The script is defined per topic type, therefore you find the location of the script on the topic types source code in the tab JavaScript under form.
Paragraph Interface
value
You already saw how to access the current value of a paragraph in the first look above. But what if the paragraph holds multiple input elements since maximum carindality is bigger than 1. In this case the value of the paragraph correponds to the first input element. If you need access to the all values you must use the array values. Support for values is rudimentary since in most scripting cases so far deal with a single value.
onChange
You can listen to changes in the form by attaching an onChange handler to the paragraph. This is straight forward as the following example illustrates:
An onChange handler
form.age.onChange(function(event) {
console.log(event.oldValue);
console.log(event.newValue);
console.log(event.form);
console.log(event.source);
});
source
The source of the current value of the paragraph is a string telling you where the value comes from:
user– the user chose that value by interacting with the form.store– if the form shows an old topic all non-null values come from the store.prefill– the value is specified through a URL prefill.script– the script set this value.
Using source
console.log(form.age.source);
initChildForm
The form editing the main topic may contain embedded child forms, either row or sheet embedded. Since these forms may be created any time during editing the main form their exact number is now known from the start. For this reason there is two methods initChildForm and onNewChildForm.
This is a method for initializing a child form in the same way the main form is initialized by the code in form.js. This is run before any child form of the corresponding paragraph is displayed. Any form, no matter whether it edits an old or a new topic, will be affected.
onNewChildForm
This method only runs when the user adds a new form either by a manual action or by a prefill, but the topic edited is always new. It can be used to set certain fields based on the input in the main form. The following source code example works on a typical order B2B form where the user selects the customer, a company, and then has to provide a contact person. If the contact person is new, the company selected will match the one selected already in the order form.
Setting the company of a contact person
form.contactPerson.onNewChildForm(function(event) {
event.childForm.company.set(event.parentForm.company);
});
Form interface
Apart from the dynamic members for accessing the paragraphs, the form currently offers only methods to set and remove the state. The state is a CSS class on the form element which makes it easier to hide and show a group of form paragraphs.
setState/removeState
We explain these two related methods by a simple example.
Using setState and removeState in form.js
Hint: The JavaScript show here is in form.js, but you can achieve this just as well with a compound constraint. Only the form is this there.
form.age.onChange(function(event) {
if (event.newValue >= 10) {
form.setState("teenager");
} else {
form.removeState("teenager");
}
});
Accompanying SCSS code
// By default two fields are hidden:
.t123, .t222-111 {
display: none;
}
// Display them only for teenagers:
.teenager {
.t123, .t222-111 {
display: block;
}
}