Representations events
Events are actions initiated automatically by the supervisor to handle various events and change the default standard behavior of the supervisor layers through additional lines of code. This document describes how they are invoked and the available context.
Because the same principles used for the classes apply on calls nesting as well as code of events invoked by the representation, it is recommended to read the Developer Guide Classes Events documentation first.
| Scripts files and event implementation | Scripts files name normalization |
| Events associated with the standard CRUD code | Variables, properties, and methods available in events |
1. Scripts files and event implementation
In the representation dictionary, the development partner defines in the first section (block Scripts) a list of ordered scripts (standard, vertical, and specific). In every script, two labels called $PROPERTIES and $METHODS that define script sections must exist. A Gosub instruction passes the lead to this script sections that enables the development partner to test three variables:
CURPROis a character string stating the concerned property (for property associated methods in $PROPERTIES).CURPTHis a character string stating the class path used for the child class, explained later in this document.ACTIONis a character string stating the requested action code.
This is the same behavior as classes, with an additional level of nesting. For example:
- For a representation called 'DOCUMENT', the instance is 'MYREP'.
- If the representation manages a class 'DOCUMENT', the instance will be 'DOC'.
- If this representation manages a class 'DOCUMENT' with a nested collection of 'LINES' child class, the instance will be 'DOCLINE(i)'.
- If this representation manages a class 'DOCUMENT' with a nested collection of 'LINES' child class having a nested collection of 'SUBLINE' child class, the instance will be 'DETAIL(j)'.
If we consider a "before" event, the nesting of the calls will be as follows:
AINSERT_CONTROL_BEFORE
called in the files associated with DOCUMENT representation:
- on representation DOCUMENT
- for the document representation instance
- this is the MYREP representation instance
- CURPTH is empty (the control is done for the current representation)
called in the files associated with DOCUMENT class:
- on class DOCUMENT
- for the document instance
- this is the MYREP.DOC class instance
- CURPTH is empty (the control is done for the current class)
called in the files associated with DOCUMENT representation:
- on representation DOCUMENT
- for the document instance
- this is the MYREP class instance
- CURPTH is "DOC"
For every LINE instance in the document (loop on I):
| AINSERT_CONTROL_BEFORE called in the files associated with LINE class:
| - on class LINE for the current line DOCLINE instance
| - this is the MYREP.DOC.DOCLINE(I) class instance
| - CURPTH is empty (the control is done for the current class)
| AINSERT_CONTROL_BEFORE called in the files associated with DOCUMENT class:
| - on class DOCUMENT for the MYREP.MYDOC.DOCLINE(I) instance
| - this is the MYREP.DOC class instance
| - CURPTH is "DOCLINE" (the control is done for the child class)
| AINSERT_CONTROL_BEFORE called in the files associated with DOCUMENT representation:
| - on class DOCUMENT for the MYREP.DOC.DOCLINE(I) instance
| - this is the MYREP.DOC.DOCLINE(I) class instance
| - CURPTH is "DOC.DOCLINE" (the control is done for the grand child class)
| For every SUBLINE in the line instance (loop on J):
| | AINSERT_CONTROL_BEFORE called in the files associated with SUBLINE class:
| | - on class SUBLINE
| | - for the current SUBLINE instance
| | - this is the MYREP.DOC.DOCLINE(I).DETAIL(J) class instance
| | - CURPTH is empty (the control is done for the current class)
| | AINSERT_CONTROL_BEFORE called in the files associated with LINE class:
| | - on class LINE
| | - for the current LINE instance
| | - this is the MYREP.DOC.DOCLINE(I) class instance
| | - CURPTH is "DETAIL" (the control is done for the child class)
| | AINSERT_CONTROL_BEFORE called in the files associated with DOCUMENT class:
| | - on class DOCUMENT
| | - for the current DOCUMENT instance
| | - this is the MYREP.DOC class instance
| | - CURPTH is "DOCLINE.DETAIL" (the control is done for the grand child class)
| | AINSERT_CONTROL_BEFORE called in the files associated with DOCUMENT representation:
| | - on representation DOCUMENT
| | - for the current MYREP instance
| | - this is the MYREP class instance
| | - CURPTH is "DOC.DOCLINE.DETAIL" (the control is done for the grand grand child class)
| Next SUBLINE instance (loop on J)
Next LINE instance (loop on J)On an "after" event, the nesting of the calls will be reversed as described for the classes events, but with an additional level of nesting for the representation.
For the "INIT" and "CONTROL" events, the order of nesting is the following:
- Events are first called in the representation.
- The events are then called in the main class after the representation.
- Lastly, events are called in the child classes after the main class.
2. Scripts files name normalization
A normalization exists for the Sage X3 script files names declared in a representation:
- A default standard script called CLASSNAME_RSTD is defined with rank 1000.
- The ranks in multiples of 100 are reserved for standard extensions.
- Specific and vertical script file names should start with X, Y, or Z and can use other ranks.
- As ranks are not significant, only the relative order is considered and can be changed if a conflict exists: two scripts cannot have the same rank.
3. Events associated with the standard CRUD code
All events associated with the standard CRUD code are exactly the same as the class events. The list of methods available on the main class is automatically reported in the representation. This means that the 'AREAD', 'AINSERT', 'ADELETE', 'AUPDATE' methods, and the corresponding events, exist only if the class associated with the representation is of a Persistent or Interface type.
| Constructor events |
|---|
| C_CLASSNAME |
| R_REPNAME |
| CRUD events |
| AINSERT |
| AREAD |
| AUPDATE |
| ADELETE |
| Properties events |
| INIT |
| GET |
| CONTROL |
| PROPAGATE |
| CRUD control events |
| AINSERT_CONTROL_BEFORE |
| AINSERT_CONTROL_AFTER |
| ADELETE_CONTROL_BEFORE |
| ADELETE_CONTROL_AFTER |
| AUPDATE_CONTROL_BEFORE |
| AUPDATE_CONTROL_AFTER |
| CRUD update events |
| AINSERT_BEFORE |
| AINSERT_AFTER |
| ADELETE_BEFORE |
| ADELETE_AFTER |
| AUPDATE_BEFORE |
| AUPDATE_AFTER |
| CRUD error handling events |
| AINSERT_ROLLBACK |
| ADELETE_ROLLBACK |
| AUPDATE_ROLLBACK |
| CRUD read events |
| AREAD_BEFORE |
| AREAD_AFTER |
| Query events |
| AQUERY_DECODE_CRITERIA_AFTER |
| AQUERY_PRIMARYKEYS_AFTER |
| AQUERY_OPEN_AFTER |
| AQUERY_CRITERIA_AFTER |
| AQUERY_JOIN_AFTER |
| AQUERY_TRANS_AFTER |
| AQUERY_CLOSE_AFTER |
4. Variables, properties, and methods available in events
At the time of event execution, the development partner can obtain access to the same context as for the class operation.
- Some supervisor variables describe the context call of the event (for example,
ACTION). - Properties of the class where the call is done (when a working copy exists). These properties are accessed using the current class instance available through the
thiskeyword. Additional technical properties (for example, context description and access to parents) are also available as properties. - Methods that can be called through
Fmeton a class instance (usuallythis).
Refer to the Developer Guide Classes Events documentation to find the description of this context.
The ASETATTRIBUTE(PROPERTY_NAME, ATTRIBUTE_NAME, VALUE) method
This method operates exactly as classes, but additional attributes are available:
| Attribute | Type | Description |
|---|---|---|
| $isMandatory | boolean | True if a value MUST be supplied at creation time. |
| $isHidden | boolean | Should the property be hidden in the interface? |
| $isDisabled | boolean | Should the property be disabled in the interface? |
Some other attributes exists but they are managed at dictionary level and cannot be updated with this method.