Sfairadora

Reference Guide

Data Provider

The data provider dispel is used mainly to create local variables in presentations. In addition thereto, it can provide local definitions of other symbols – data types, functions, constants, and dispels. It can also give a name to a subordinate object of the data available to it, and provide the object to subordinate dispels under the defined identifier. Another important feature is the possibility to define handlers – that is, functions invoked whenever some predetermined data is changed. Last but not least, you can use it to define a validator function invoked when the user attempts to close the window containing the data provider. The function can prevent window closing (ending data editing) if data has not been entered correctly. (The disp-folder has a similar functionality.)

The Definitions document section provides an analogical functionality at the global level.

Child

Definition of the dispel for which the definitions are provided.

Functionality – Data Links

This section allows you to assign an identifier to a sub-object of a data object; the identifier then provides the object to the dispels of the child. There is a table in which every row defines one data item provided to the child. The table has the following columns:

Column Name	Description
Object name of data for children	Identifier used to provide the data item to the child.
Data source – Name	Name of the object where the data that should be provided to the child is located. You can select one of the objects provided by parent dispels.
Data source – Reference	Reference to a data item within the above identified object.
Not for tools	Data provided to children is normally available to tools, too. If you check this option, data will be available only to children and not to tools.
Optional name	This option applies to data reference in the Enki language. If you check this option, the object identifier (specified in the Object name of data for children field) need not be specified; it is sufficient to specify the data reference – the object is looked up automatically by virtue of the reference (i.e. the name of the first found object containing the target of the reference is substituted). This applies, for example, to the behavior of the `this` standard identifier. See the Data References chapter in the section devoted to the Enki language. Example: suppose an object called address containing a street item is defined here, and the Optional name checkbox is checked. Then, when you write Enki language expressions in subordinate dispels, it is enough to write `street` instead of the equivalent `address.street`. If this checkbox is unchecked, you must always write the entire `address.street` reference.

‍

Functionality – Data Types

This section allows you to create local named data types available to subordinate dispels. There is a table in which every row defines one type. You must give a name, which must be an identifier, to every data type, and then you can use the data type editor to create a custom named type.

Functionality – Variables

This section allows you to create an object provided to subordinate dispels; the subordinate dispels may store temporary values of the presentation in this object. This object may also contain computed items, which presents a variable automatically recalculated when data it depends on is changed.

Item	Description
Name of variables	An identifier used to provide the variables to the child. The standard identifier is `vars`. Example: if you keep the `vars` variables identifier unchanged and define an `x` variable, the variable should be referenced in the Enki language by the expression `vars.x`. (If the Name of variables is optional option below is checked, it is enough to write just `x`). In subordinate editors, you should set Object name = `vars` and Data reference = `x`.
List of variables
Name	Variable name – must be an identifier.
Data type, type properties	Variable data type specified by the data type editor.
optional	The variable value need not be assigned.
Initial value	The value assigned to the variable when the data provider is created.
Variables not accessible by tools	The variables object is normally available to tools, too. If you check this option, it will be available only to children and not to tools.
Name of variables is optional	If checked, the identifier specified in the Name of variables field need not be specified in the Enki language. It is sufficient to specify directly the variable name. (`x` is enough instead of `vars.x`.) See the Optional name item in the Functionality – data links section above for more details.

‍

Functionality – Functions

This section allows you to define local functions that can be used in expressions in subordinate dispels. Functions are defined in a table, where every row corresponds to one function. You must specify a name (which must be an identifier) and the proper definition for every function. The definition is entered using the function editor explained in a separate chapter. It is recommended that function names are specified in lower case. If the name contains more than one word, underscore is recommended instead of spaces (spaces are forbidden) – for example number_of_customers.

Functionality – Constants

A constant is a named value of a particular type. Constants need not necessarily be scalars; you can also define constants of compound types. Constants are defined in a table, where every row corresponds to one constant. You must specify a name (which must be an identifier), data type, and value for every constant. It is recommended that constant names are specified in upper case in order to distinguish constants from variables; for variables, lower case is recommended.

Functionality – Dispels

This section allows you to define local named dispels that can be used in the child definition as a named dispel. Dispels are defined in a table, where every row corresponds to one defined dispel. For every dispel, you must specify a name (which must be an identifier) identifying the dispel. Next, there is a button opening a dispel definition editor and a Details button opening a window, in which you can specify the properties of the defined dispel. Details are explained in the chapter on dispel definitions in the Definitions document section.

Functionality – Handlers

Handler is a function invoked whenever some predetermined data is changed. Detailed information on handlers can be found in the chapter on handlers in the Definitions document section.

Handlers are most frequently used to maintain data consistence – if certain data in the document is changed, it may be necessary to update also some other data. However, mostly you can achieve the same effect in a much easier way by using a computed item. A computed item can be created, among others, as a local variable in the data provider.

In contrast to global handlers defined in the Definitions document section, local handlers defined here are invoked also when data is attached and detached. Handler data is typically attached immediately after the data provider is displayed and detached immediately before it is removed from the presentation. Nonetheless, the required data item is not necessarily available while the data provider is displayed (this situation typically occurs with tools, but it may occur also with other dispels). In this case, the handler is invoked only after the data is attached. The data may be attached and detached multiple times while the data provider is displayed. Calling the handler upon attachment or detachment of data can be used to initialize or deinitialize local variables or other data.

Item	Description
Object name	Name of the object to which the handler should be attached.
Data reference	Reference to data within the above specified object. The reference can also contain asterisks replacing any name or index. This is especially useful when you need to assign the handler to table columns or to any element in a list. See the chapter on handlers in the Definitions document section for details and examples.
Transitive	Significant only when the data reference points to a table or sequence. If the transitive option is not checked, the handler is invoked only when an element of its own sequence is added or removed. If the handler is defined as transitive, it is invoked also whenever the value of any element of the sequences is changed. If the data reference does not point to a sequence, this setting is ignored.
Invoke on event
data attached	If checked, the handler is invoked when data is attached (reason = `DATA_ATTACHED`).
data changed	If checked, the handler is invoked when data is changed (reason = `DATA_CHANGED`).
data detached	If checked, the handler is invoked when data is detached (reason = `DATA_DETACHED`).
Expression	Expression evaluated when the handler is invoked. The expression is entered using the function editor. The value of reason is passed as parameter: `DATA_ATTACHED` (0) ‍ handler has been newly set – the first call of the handler enabling initialization, if applicable. `DATA_CHANGED` (1) ‍ monitored data has been modified. `DATA_DETACHED` (2) handler will be removed – the last call of the handler enabling the termination of data monitoring. You should use the symbolic names specified here, if necessary. The numeric values enclosed in parentheses are listed only as information for debugging.

‍

Functionality – Validator

Function invoked when the window displaying the data provider is about to be closed. The function may validate data edited by the window. The result represents information about the data condition: ok, warning, or error. You can also specify a reference to data related to the error and an error message.

If the result is error, a message is displayed, and the window cannot be closed until the error is corrected. If the result is warning, a message is displayed, and the user can choose either to correct the error or to close the window without correction. If a data reference is specified, and the window is not being closed, an editor of the data item identified by the reference is activated.

Function parameter:

err

output parameter of the Error type. The validator function can assign an error message to this parameter (e.g.:

err 
					= error("the value of X is too big");

) The message should start with a lowercase letter and should not end with a period – errors can be nested, and when they are listed, the first letter is automatically uppercased, and a period is placed at the end.

In addition, you can use the set_data_ref operator to specify reference to data related to the error. For strings you can also specify the line and column where the error occurs. (e.g.:

err<-set_data_ref( 
				[Dref]"data.age");

)

Result:

one of the following constants:

VLD_OK (0)

everything is ok (the value of the err parameter is ignored).

VLD_WARNING (1)

warning. The user receives the message set in the err parameter. He can choose either to close the window or to correct the error. If he chooses the latter, an editor of the data specified by the err<-set_data_ref operator is activated.

VLD_ERROR (2)

data is incorrectly specified. The user receives the message set in the err parameter. If a data reference is specified by the err<-set_data_ref operator, the respective editor is activated.

(The values of the constants are included in the parentheses for information. However, the symbolic names should be used and not their values.)

Example:

if(data.x>1000)

{

err = error("the value of x is higher than 1000");

err<-set_data_ref([Dref]"data.x");

return VLD_ERROR;

};

‍

if(data.y>100)

{

err = error("the value of y is higher than 100");

err<-set_data_ref([Dref]"data.y");

return VLD_WARNING;

};

‍

return VLD_OK;

‍

Common items

Definition type: Data_provider_def

Diotima