Form scripting
The form is the central data entry component and plays a vital role in any Topincs store and any Topincs system can work fine with modelling and the standard form validation provided by the compound constraint. Yet, the requirements demand sometimes to add more behavior and this is were 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
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
Script 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 can hold multiple input element when 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 remainders 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);