SOClass Modular version

5 - Iterative segment

Subject BasicTutorial
Version ADK 244
Issue date 16/07/2005
Beneficiaries Developers
File Tutorial - 5 - Iterative segment.doc
Status Final
Checked by Asycuda World - Lyon Competence center
Copyrights United Nations Conference on Trade and Development
 Developer Guide
Version ADK 244
5 - Iterative segment

Table of contents
1. MODIFICATION OF THE DATA OBJECT MODEL: SHARED SIDE...... 5
1.1. DEFINITION OF DOM CONSTANTS ................................................................... 5
1.2. CREATION OF THE ITERATIVE PAGE’S DATA MODEL ....................................... 6
1.3. MODIFICATION OF THE DOCUMENT DATA MODEL .......................................... 7
2. SERVER MODIFICATION ............................................................................... 9
2.1. DATABASE CONNECTION ................................................................................. 9
2.2. OPERATION MODIFICATIONS............................................................................ 9
2.3. CREATION OF A TABLE CONNECTOR .............................................................. 10
2.4. ADDING THE SUB TABLE CONNECTOR ............................................................ 11
3. CLIENT MODIFICATION .............................................................................. 12
3.1. CREATE THE ITERATIVE VISUAL PAGE ........................................................... 12
3.2. ADD THE VISUAL PAGE TO THE DOCUMENT ................................................... 13
3.3. ITERATIVE SEGMENT MANAGEMENT .............................................................. 14
3.3.1. Associating events to rules in the client document.................................. 14
3.3.2. Creating the appropriate rules................................................................ 14
4. PROPERTIES FILES........................................................................................ 18
4.1. TUTORIAL5 PROPERTIES FILES ....................................................................... 18
4.2. XML DATABASE TABLE MANAGEMENT ......................................................... 19
4.3. BINDER AND SHORTCUT DEFINITION.............................................................. 20

United Nations Conference on Trade and Development Page 1 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Figures
FIGURE1 - THIS IS AN EXAMPLE OF FIGURE........................................................................... 3
FIGURE2 - THE CHILD PAGE THAT CAN BE REPEATED ........................................................... 4
FIGURE3 - DOM OF THE ITERATIVE PAGE ............................................................................ 5
FIGURE4 - BUTTONS ASSOCIATED TO THE EVENTS ............................................................. 10

Source code
SOURCE 1 - THIS IS AN EXAMPLE OF SOURCE CODE ................................................................ 3
SOURCE 2 - ADDING THE CONSTANTS OF THE DOM IN C_TUTORIAL5 CLASS......................... 5
SOURCE 3 - IMPLEMENTATION OF THE DS_TUTORIAL5CHILD CLASS .................................... 6
SOURCE 4 - RULE DECLARATION IN THE D_TUTORIAL5 CLASS .............................................. 7
SOURCE 5 - DECLARATION OF EVENTS IN THE C_TUTORIAL5 CLASS ..................................... 8
SOURCE 6 - DATABASE TABLE ALIAS DECLARATION IN THE S_TUTORIAL5 CLASS ................. 9
SOURCE 7 - ADDING VISIBLE EVENTS TO OPERATIONS IN S_TUTORIAL5 CLASS ..................... 9
SOURCE 8 - ADDING EVENTS CONSTANTS IN C_TUTORIAL5 ................................................. 10
SOURCE 9 - CREATION OF THE SUB TABLE CONNECTOR IN THE TC_TUTORIAL5CHILD CLASS
10
SOURCE 10 - SUB TABLE CONNECTOR DECLARATION IN THE TC_TUTORIAL5 CLASS ............ 11
SOURCE 11 - VP_TUTORIAL5CHILD CLASS............................................................................ 12
SOURCE 12 - IMPLEMENTATION OF THE VF_TUTORIAL5CHILD CLASS .................................. 13
SOURCE 13 - ADDING NEW FORM IN THE VD_TUTORIAL5 CLASS .......................................... 13
SOURCE 14 - ADDING RULES IN THE DC_TUTORIAL5 CLASS.................................................. 14
SOURCE 15 - R_PAGE_NEW RULE CLASS ............................................................................... 15
SOURCE 16 - R_PAGE_DELETE RULE CLASS .......................................................................... 15
SOURCE 17 - R_MANAGECHILDVISUALEVENTS RULE CLASS................................................. 16
SOURCE 18 - ADDING RULE IN THE DC_TUTORIAL5 CLASS ................................................... 17
SOURCE 19 - UN.ASYTUTORIAL.TUTORIAL5.PROPERTIES FILE................................................ 18
SOURCE 20 - UN.ASYTUTORIAL.PROPERTIES .......................................................................... 18
SOURCE 21 - ASYUTORIAL_CREATE.XML MODIFICATIONS ..................................................... 19
SOURCE 22 - ASYTUTORIAL_INSERT.XML MODIFICATIONS .................................................... 19
SOURCE 23 - ADDING BINDER AND SHORTCUT IN THE INSTALL_SRC.XML FILE ...................... 20

United Nations Conference on Trade and Development Page 2 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

How to read this document

This symbol indicates advice and recommendations. Information on best
practices and recommended procedures related to the current topic is
contained here.

Keyword Definition

This symbol indicates a warning. Information on common pitfalls or dangers

associated with the current topic is contained here.

This symbol indicates an example to further illustrate the current topic.

Source 1 -
This is an example
of source code Source code.

Phase 1 Phase 2 Phase 3

Figure1 - This is an example of figure

United Nations Conference on Trade and Development Page 3 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Objective
In this document you will learn

How to implement an iterative page in an e-Document

Required element

Tutorial4 e-Document

Iterative page An iterative page is a page that can be duplicated

dynamically by the end-user for an unlimited number of
times, based on the model of the first page of the form to
which it belongs.

The iterative page that will be created in this tutorial, represent the children of a person. An
undefined number of children can be attached to a person.

Buttons to add and

delete a child

Figure2 - The child page that can be repeated

United Nations Conference on Trade and Development Page 4 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Infinite iteration groups of data that can repeat an infinite number of times: they are
dynamically created by the e-document’s user.
An infinite iteration is identified by a rank and requires the creation of a class extending
KNumberedSubDocument to implement the iteration segment. This class is then linked to
the main data model using the numberedItm() method.
A new iteration segment and a new visual page are created dynamically by the user by
generating a visual event (i.e. clicking on a button). This event will then trigger two rules.
One of these rules is responsible for generating a dynamic page and is actually managed by a
new visual form class extending the KVisualFormWithNumberedPages class. The
constructor of this new class refers (through its parameters) to the events fired by the client
when creating the new dynamic page. These events objects contain as a source, the form from
where they where generated.

1. Modification of the Data Object Model: Shared side

The first step to create an iterative page is to define the data model of the page.

CHD Visual field Data element

Child name CFN
CFN
Child Birth Date CBD
CBD

Figure3 - DOM of the iterative page

1.1. Definition of DOM constants

The constants used in the DOM must be declared in the C_Tutorial5 interface as it has
been done in previous tutorials.

Source 2 -
adding the …
constants of the // Segment Child
DOM in public static final String CHD = "CHD";
// child first name
C_Tutorial5 class public static final String CFN = "CFN";
// child Birth date
public static final String CBD = "CBD";
…

United Nations Conference on Trade and Development Page 5 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

1.2. Creation of the iterative page’s Data Model

For an iterative segment, the data model must be declared in a separated file which name
should start with “DS_” (in this tutorial, it will be DS_Tutorial5Child). “DS_” classes
extend the KNumberedSubDocument class, and can’t be standalone. It must be used in a
“D_” class. Thus, the “DS_” class has an attribute pointing on the “D_” class it belongs to
(represented in the source code by a KDocument because every “D_” should extend this
class).
In “DS_” classes, a method isEmpty() is requested. This method is used to know if the
document needs to be added or not.

Source 3 -
Implementation of package un.asytutorial.tutorial5;
the import so.kernel.core.KNumberedSubDocument;
DS_Tutorial5Child
public class DS_Tutorial5Child extends KNumberedSubDocument implements
class C_Tutorial5 {

/**
* Constructor without parameter is required for desktop persistence
*/
public DS_Tutorial5Child() {
super();
}

/**
* Definition of the Data Model
*/
public void define_DataModel() {
add(CFN); // Child name
add(CBD); // Child age
define_DataInformation();
}

/**
* Definition of the Data Information
*/
public void define_DataInformation() {
setHumanName(lng("Child"));
de(CFN).setHumanName(lng("child first name"));
de(CBD).setHumanName(lng("child birth date"));
}

/*
* Method to indicate if the document is empty. Here a child document is empty
* if there is no child name specified.
*/
public boolean isEmpty() {
return (de(CFN).getString("").trim().equals(""));
}

/**
* Definition of the Client Business Rules
*/
public void define_ClientBusinessRule() { }

/**
* Retrieves a property string in the current working language.
*/
public static String lng(String property) {
return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

United Nations Conference on Trade and Development Page 6 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

1.3. Modification of the document Data Model

Rule An object that allows the performing of a process and is

attached to a part of the DM. A rule is, therefore, triggered
upon the occurrence of an event.
The event that triggers a rule can be composite, i.e. the
grouping of basic events and / or events defined by the
programmer
Business Rule An independent piece of code that executes a specific process
on the document. This process could be anything related to
the implementation of the business logic of the document, for
instance writing a single value in a data element of the Data
Model, computing a Customs declaration’s taxation lines, or
validating a document’s data before sending it to the server.
Business rules are triggered by specific events, and they can,
in their turn, generate events.
Client Rule A rule that executes on the client. A client rule is attached to
any element (leaf or node) of any level of the DOM. The rule
is triggered when an event it listens to reaches this element.

Define a new rule triggered by the events (ACT_CHILD_NEW, ACT_CHILD_DEL) declared

to create the data model representation of the iteration.
The numberedItm() method links DS_Tutorial5Child class with the main data
model.
KR_NumberedSudDocumentManager class manages the addition and the removal of
iterative pages.

Source 4 -
Rule declaration in …
the D_Tutorial5 import so.kernel.core.rules.KR_NumberedSubDocumentManager;
class …
Public void define_DataModel() {
.. ..
// Child numbered sub-document
numberedItm(CHD, new DS_Tutorial5Child());
.. ..
}
…
public void define_ClientBusinessRule() {
KR_NumberedSubDocumentManager rule =
new KR_NumberedSubDocumentManager(ds(CHD),
ACT_CHILD_NEW,
ACT_CHILD_DEL);
addRule(rule, ACT_CHILD_NEW);
addRule(rule, ACT_CHILD_DEL);
}
….

United Nations Conference on Trade and Development Page 7 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Don’t forget to declare these constant events in file C_Tutorial5.

Source 5 -
Declaration of …
events in the // Visual middle events
C_Tutorial5 class public static final int ACT_CHILD_NEW = KernelEvent.INTERNAL_EVENTS_MAX +12;
public static final int ACT_CHILD_DEL = KernelEvent.INTERNAL_EVENTS_MAX + 13;
…

United Nations Conference on Trade and Development Page 8 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

2. Server modification

2.1. Database connection

First it is necessary to define the alias for the table representing children (creation of the
child table in the database is explained later). The alias is declared in the S_Tutorial5
class. An access method to this alias is also needed in this class as we done for
PERSON_TAB.

Source 6 -
Database table …
alias declaration in // Name of the resource table identifier for the Customs database tables
the S_Tutorial5 public static final String PERSON_TAB = "TUTORIAL_PERSON_TAB";
public static final String CHILD_TAB = "TUTORIAL_CHILD_TAB";
class …

static protected String getCHILD_TAB() {

return Server.getString(S_Tutorial5.class, CHILD_TAB);
}

2.2. Operation modifications

Then, in the S_Tutorial5 class again, the create and update operations must be
modified to include two buttons for the management of the iterative page. We use the
addVisibleEvenId method to associate event with button:
• One for the addition of a page.
• One for the removal of a page.
We will access to these buttons only when we use create or update operations.

Source 7 -
Adding visible …
events to operations protected Operations createValidOperations() {
in S_Tutorial5 ….
Operation op_Create =
class OperationFactory.makeCreateOperation(OI_CREATE, OP_CREATE);
op_Create.addVisibleEventID( MEN_CHILD_NEW,
"Add child",
lng("Add child"),
"img/Btn_New_Normal.gif");
op_Create.addVisibleEventID( MEN_CHILD_DEL,
"Delete child",
lng("Delete child"),
"img/Btn_No_Normal.gif");
ops.add(op_Create);

United Nations Conference on Trade and Development Page 9 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Operation op_Update =
OperationFactory.makeUpdateOperation(OI_UPDATE, OP_UPDATE);
op_Update.addVisibleEventID( MEN_CHILD_NEW,
"Add child",
lng("Add child"),
"img/Btn_New_Normal.gif");
op_Update.addVisibleEventID( MEN_CHILD_DEL,
"Delete child",
lng("Delete child"),
"img/Btn_No_Normal.gif");
ops.add(op_Update);
….
}

This buttons are associated with visible events (names are starting with MEN_). These events
must be declared in the C_Tutorial5 interface.

Source 8 -
adding events // Visual middle events
constants in public static final int MEN_CHILD_NEW = KernelEvent.INTERNAL_EVENTS_MAX +10;
C_Tutorial5 public static final int MEN_CHILD_DEL = KernelEvent.INTERNAL_EVENTS_MAX + 11;

The 2 events are

associated to these
buttons
Figure4 - Buttons associated to the events

2.3. Creation of a table connector

The iterative segment is represented by a table in the database. Consequently, a new table
connector must be created. The key of the table is composed of two fields:
• The key of its table connector owner (here, it is the Instance_ID field of
TC_Tutorial5).
• A rank field differencing the multiple sub segments corresponding to the same
Instance_ID.

Source 9 -
Creation of the sub package un.asytutorial.tutorial5.server;
table connector in
the import java.sql.Types;
import so.kernel.core.KNumberedSubDocument;
TC_Tutorial5Child import so.kernel.server.ConnectionManager;
class import so.kernel.server.KNumberedSubTableConnector;
import so.kernel.server.TableConnector;
import un.asytutorial.tutorial5.C_Tutorial5;

United Nations Conference on Trade and Development Page 10 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

public class TC_Tutorial5Child extends KNumberedSubTableConnector implements

C_Tutorial5 {
/**
* Table connector -
*/
public TC_Tutorial5Child(TableConnector tc, ConnectionManager
connectionManager) {
super( tc.getServerBinder(),
connectionManager,
S_Tutorial5.getCHILD_TAB(),
CHD,
new DS_Tutorial5Child());

// add the table columns

add(de(KNumberedSubDocument.RNK), "RNK" , Types.INTEGER); // Rank

// add the table columns

add(de(CFN), "CHD_NAM", Types.CHAR); // Child name
add(de(CBD), "CHD_BDA", Types.DATE); // Child birth date

// define the key column

key(de(KNumberedSubDocument.RNK));// Rank
key(de(INSTANCE_ID), tc); // define the parent TableConnector's
key

setParticipateInSearch(true);
}
}

2.4. Adding the sub table connector

The table connector representing a child must be declared as a sub table connector in the
table connector representing a person.

Source 10 -
Sub table connector ....
declaration in the public TC_Tutorial5( GCFServerBinder serverBinder, ConnectionManager
TC_Tutorial5 class connectionManager) {
super(serverBinder, connectionManager, S_Tutorial5.getPERSON_TAB());
serverBinder.setInstanceIdField(this, INSTANCE_ID, INSTANCE_ID);
…

// add the sub-table connector

addSubTableConnector(new TC_Tutorial5Child(this, connectionManager));
…
}

United Nations Conference on Trade and Development Page 11 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

3. Client modification

3.1. Create the iterative visual page

Visual pages representing an iterative segment of the Data Model have an additional
attribute, a data set corresponding to it. This data set is used to make the binding of visual
fields and DOM elements in the initFacets() method.

Source 11 -
VP_Tutorial5Child package un.asytutorial.tutorial5.client;
class
import java.awt.Color;
import java.awt.Font;

import so.kernel.client.KVisualPage;
import so.kernel.client.elf.ElfField;
import so.kernel.client.elf.ElfVisualPage;
import so.swing.KPanel;
import un.asytutorial.tutorial5.C_Tutorial5;

public class VP_Tutorial5Child extends ElfVisualPage implements C_Tutorial5 {

// Declare Visual controls

transient private ElfField fld_ChildName = elfFieldPool.getElfField();
transient private ElfField fld_ChildBirthDate = elfFieldPool. getElfField();

public VP_Tutorial5Child() {
super();
initVisualPage();
initVisualControls();
}

public void initVisualPage() {

…
}

// Initialization: Visual controls

public void initVisualControls() {
// Title stripe
addTitleStripe( 0, 4, 444, 24, lng("Child"));

// Label
add( 20, 50, 100, 24, lng("First name"));
add( 20, 100, 100, 24, lng("Birth date "));

// Editable Visual controls

add( 100, 50, 200, 20, fld_ChildName, lng("first name"));
add( 100, 100, 200, 20, fld_ChildBirthDate, lng("birth date"));
}

public void initFacets() {

addFacetText(fld_ChildName, getAttachedDataSet().de(CFN), "X35");
addFacetDate(fld_ChildBirthDate, getAttachedDataSet().de(CBD), "Date");
}

/**
* Retrieves a property string in the current working language.
*/
public static String lng(String property) {
return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

United Nations Conference on Trade and Development Page 12 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

3.2. Add the visual page to the document

Then, the new visual page must be added to the document. The form containing the
iterative pages doesn’t extend the VisualForm class but the
KVisualFormWithNumberedPages one. This class allows the dynamic changing of the
instance’s number of one page.

Create the VF_Tutorial5Child form, take care of the constructor

Source 12 -
Implementation of package un.asytutorial.tutorial5.client;
the
VF_Tutorial5Child import so.kernel.client.KVisualFormWithNumberedPages;
import so.kernel.client.KVisualPage;
class import un.asytutorial.tutorial5.C_Tutorial5;

public class VF_Tutorial5Child extends KVisualFormWithNumberedPages implements

C_Tutorial5 {

/**
* Constructor
*/
public VF_Tutorial5Child() {
super(lng("Child"), CHD, ACT_CHILD_NEW, ACT_CHILD_DEL);
}

public KVisualPage getVisualPage(int arg0) {

return new VP_Tutorial5Child();
}

/**
* Retrieves a property string in the current working language.
*/
public static String lng(String property) {
return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

Add the form created to the Visual document class (VD_Tutorial5).

Source 13 -
Adding new form in …
the VD_Tutorial5 public void initializeForms() {
class …
VF_Tutorial5Child formChild = new VF_Tutorial5Child();
…
addForm(formChild);
…
}

United Nations Conference on Trade and Development Page 13 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

3.3. Iterative segment management

The last step for the management of the iterative page is to associate the events generated
by the buttons (MEN_xxx) to a rule.

3.3.1. Associating events to rules in the client document

This association is done by using rules. For each event corresponding to a visual
button, a rule is added to the DC_Tutorial5 class. These rules, declared in separated
files, fire the events of the DOM.

Source 14 -
Adding rules in the package un.asytutorial.tutorial5.client;
DC_Tutorial5 class
import so.kernel.client.ClientDocument;
import so.kernel.core.KernelEvent;
import so.kernel.core.KernelEventConstants;
import so.kernel.core.events.EventConstants;
import un.asytutorial.tutorial5.C_Tutorial5;
import un.asytutorial.tutorial5.D_Tutorial5;
import un.asytutorial.tutorial5.client.rules.R_Page_Delete;
import un.asytutorial.tutorial5.client.rules.R_Page_New;

public class DC_Tutorial5 extends ClientDocument implements

C_Tutorial5,KernelEventConstants {
void initRules(D_Tutorial5 doc) { }

void initRules(D_Tutorial5 doc, VD_Tutorial5 vd)

{
// Manage add, delete logic and user dialog
doc.addRule(new R_Page_New(), new KernelEvent(MEN_CHILD_NEW));
doc.addRule(new R_Page_Delete(vd), new KernelEvent(MEN_CHILD_DEL));
}
}

3.3.2. Creating the appropriate rules

In this tutorial, rules are briefly presented. More explanations about rules are
given in tutorial 8.

The following rules must be defined in the \...\client\rules\ directory.

The first rule, R_Page_New, is a simple rule firing the appropriate event for the
creation of a new child.

United Nations Conference on Trade and Development Page 14 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Source 15 -
R_Page_New rule package un.asytutorial.tutorial5.client.rules;
class
import so.kernel.core.*;
import un.asytutorial.tutorial5.*;

/**
* Handle a "new child" visible event, and fire the CHILD_NEW event.
*/
public class R_Page_New extends Rule implements C_Tutorial5 {

public void apply(KernelEvent e) {

if (e.getData() instanceof D_Tutorial5) {
D_Tutorial5 cmp = (D_Tutorial5)e.getData();

cmp.fire(new KernelEvent(ACT_CHILD_NEW));
}
}
}

The second rule, R_Page_Delete, is a bit more complex because verifications are done
to be sure to delete the good form. But the main thing to remember here is the firing of
event for the triggering of actions declared on the sub segment of the DOM.

Source 16 -
R_Page_Delete rule package un.asytutorial.tutorial5.client.rules;
class
import java.text.MessageFormat;

import so.util.DebugOutput;
import so.kernel.core.Rule;
import so.kernel.core.*;
import so.kernel.client.*;
import so.swing.KOptionPane;
import un.asytutorial.tutorial5.*;
import un.asytutorial.tutorial5.client.VD_Tutorial5;

/**
* Handle a "delete child" visible event, requests user confirmation, and eventually
* fire the CHILD_DEL event to delete the current child.
*/
public class R_Page_Delete extends Rule implements C_Tutorial5 {
private VD_Tutorial5 vd;

public R_Page_Delete(VD_Tutorial5 vd) {

this.vd = vd;
}

public void apply(KernelEvent e) {

if (e.getData() instanceof D_Tutorial5) {

D_Tutorial5 cmp = (D_Tutorial5)e.getData();

if (cmp != vd.getDocument()) {
DebugOutput.error("The rule has been added to a doc that is not attached to given
skin");
return;
}
KVisualDynamicForm vf = (KVisualDynamicForm)vd.getSelectedForm();
KVisualPage vp = (KVisualPage)vf.getSelectedPage();

DS_Tutorial5Child child = (DS_Tutorial5Child)vp.getAttachedDataSet();

// there is no current child to delete

United Nations Conference on Trade and Development Page 15 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

if (child == null) return;

String name = child.de(CFN).getContentString(); // New empty child

if (name == null) {
doDelete(cmp, child);
return;
}
// ask user confirmation to delete child
MessageFormat formater = new MessageFormat(lng("Do you want to delete child,
{0}?"));
int answer =KOptionPane.showConfirmDialog(DesktopMain.sharedInstance(),
formater.format(new Object[] { name }),
lng("Confirmation"),
KOptionPane.YES_NO_OPTION,
KOptionPane.QUESTION_MESSAGE, null);
if (answer == KOptionPane.YES_OPTION) doDelete(cmp, child);
}
}

private void doDelete(D_Tutorial5 cmp, DS_Tutorial5Child child) {

cmp.fire(new KernelEvent(child, ACT_CHILD_DEL)); // delete current child
}

public static String lng(String property) {

return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

We implement one last rule which allows to access the button add and delete child only on
the child form.

Source 17 -
R_manageChildVis package un.asytutorial.tutorial5.client.rules;
ualEvents rule
class import so.kernel.core.Rule;
import so.kernel.core.events.client.*;
import so.kernel.core.*;
import so.kernel.client.*;
import un.asytutorial.tutorial5.C_Tutorial5;
import un.asytutorial.tutorial5.client.*;

public class R_ManageChildVisualEvents extends Rule implements C_Tutorial5 {

public void apply(KernelEvent e) {

GUIFormGainFocusEvent ev = (GUIFormGainFocusEvent)e;
Document doc = (Document)ev.getSource();
VisualForm vf = ev.getForm();

if (vf instanceof VF_Tutorial5Child) {

doc.setEnabledOperationEvent(MEN_CHILD_NEW, true);
doc.setEnabledOperationEvent(MEN_CHILD_DEL, true);
} else {
doc.setEnabledOperationEvent(MEN_CHILD_NEW, false);
doc.setEnabledOperationEvent(MEN_CHILD_DEL, false);
}
}
}

United Nations Conference on Trade and Development Page 16 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

This rule is added to the DC_Tutorial5 class and associated to the

GUI_FORM_GAIN_FOCUS event.

Source 18 -
Adding rule in the …
DC_Tutorial5 class import un.asytutorial.tutorial5.client.rules.R_manageChildVisualEvents;
…
void initRules(D_Tutorial5 doc, VD_Tutorial5 vd) {
// Manage add, delete logic and user dialog
doc.addRule(new R_page_new(), new KernelEvent(MEN_CHILD_NEW));
doc.addRule(new R_page_delete(vd), new KernelEvent(MEN_CHILD_DEL));

//Enable and disable the new (MEN_CHILD_NEW) and delete (MEN_CHILD_DEL) contact
events according to the form that has the focus.
doc.addRule(new R_ManageChildVisualEvents(),
EventConstants.GUI_FORM_GAIN_FOCUS);
}
…

United Nations Conference on Trade and Development Page 17 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

4. Properties files
In this chapter you will learn

Prepare properties files for deployment.

Properties files that will be modified

un.asytutorial.tutorial5.properties \server\som\config
un.asytutorial.properties \server\som\config
asytutorial_create.xml \server\som\db
asytutorial_insert.xml \server\som\db
install_src.xml \server\som

4.1. Tutorial5 properties files

Define the aliases for the database connection of the module in a new file:
un.asytutorial.tutorial5.properties.
These aliases will be used in the database.properties file.
As a table has been created in this tutorial, the alias corresponding to it must be declared in
the property file of the module (un.asytutorial.tutorial5.properties).

Source 19 -
Un.asytutorial.tutor un.asytutorial.tutorial5.server.S_Tutorial5#TUTORIAL_PERSON_DataBaseURL=
ial5.properties file $[un.asytutorial_URL]
un.asytutorial.tutorial5.server.S_Tutorial5#TUTORIAL_PERSON_DataBaseUser=
$[un.asytutorial_User]
un.asytutorial.tutorial5.server.S_Tutorial5#TUTORIAL_PERSON_DataBasePassword=
$[un.asytutorial_Password]
un.asytutorial.tutorial5.server.S_Tutorial5#TUTORIAL_PERSON_TAB=
TUTORIAL5_PERSON_TAB
un.asytutorial.tutorial5.server.S_Tutorial5#TUTORIAL_CHILD_TAB=
TUTORIAL5_CHILD_TAB

Also add the following line in the un.asytutorial.properties to take into account
the property file created:

Source 20 -
Un.asytutorial.prop @include un.asytutorial.tutorial2.properties
erties @include un.asytutorial.tutorial3.properties
@include un.asytutorial.tutorial4.properties
@include un.asytutorial.tutorial5.properties
….

United Nations Conference on Trade and Development Page 18 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

4.2. XML database table management

The next step is to modify the xml file that manages the automatic creation of the database
during the module installation.
Two files need to be modified:
• asytutorial_create.xml for the automatic creation of the tables in the
database
• asytutorial_insert.xml for the automatic insertion of records in the tables.
We create also a new table.
These files are located in: un\asytutorial\server\som\db

Source 21 -
Asyutorial_create.x <create>
ml modifications ……
<table name="TUTORIAL5_PERSON_TAB">
<column name= "INSTANCE_ID" type="INTEGER" null="false"/>
<column name= "IDE_FNA" type="VARCHAR" size="35"/>
<column name= "IDE_LNA" type="VARCHAR" size="35"/>
<column name= "IDE_BDA" type="TIMESTAMP"/>
<column name= "IDE_PIC" type="LONGVARBINARY"/>
<column name= "IDE_SEX" type="INTEGER"/>
<column name= "COO_ADR" type="VARCHAR" size="50"/>
<column name= "COO_CPO" type="VARCHAR" size="6"/>
<column name= "COO_TEL" type="VARCHAR" size="20"/>
<column name= "COO_CIT" type="VARCHAR" size="25"/>
<column name= "USR_LOG" type="VARCHAR" size="25"/>
<column name= "USR_PWD" type="VARCHAR" size="20"/>
<primary_key>
<column name= "INSTANCE_ID"/>
</primary_key>
</table>
<table name="TUTORIAL5_CHILD_TAB">
<column name="INSTANCE_ID" type="INTEGER" null="false"/>
<column name="RNK" type="INTEGER" null="false"/>
<column name="CHD_NAM" type="VARCHAR" size="35" />
<column name="CHD_BDA" type="TIMESTAMP"/>
</table>
</create>

Source 22 -
Asytutorial_insert.x <insert>
ml modifications <table name="TUTORIAL2_PERSON_TAB">
</table>
<table name="TUTORIAL3_PERSON_TAB">
</table>
<table name="TUTORIAL4_PERSON_TAB">
</table>
<table name="TUTORIAL5_PERSON_TAB">
</table>
<table name="TUTORIAL5_CHILD_TAB">
</table>
</insert>

United Nations Conference on Trade and Development Page 19 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

4.3. Binder and shortcut definition

A binder and a shortcut have to be declared too.

Source 23 -
Adding binder and …….
shortcut in the <BU name="BUasytutorial">asytutorial BU</BU>
install_src.xml file ……
<binder name="B_TUTORIAL_5" status="">
<field name="server" value="un.asytutorial.tutorial5.server.S_Tutorial5"/>
<field name="dom" value="un.asytutorial.tutorial5.D_Tutorial5"/>
<field name="client" value="un.asytutorial.tutorial5.client.DC_Tutorial5"/>
<access bu="BUasytutorial">
<full/>
</access>
</binder>
…
<DL>
<folder name="Tutorial" icon="">
……..
<item name="Tutorial 5: Iterative Segment" icon="">
<field name="binder" value="B_TUTORIAL_5"/>
<field name="skin" value="un.asytutorial.tutorial5.client.VD_Tutorial5"/>
<access bu="BUasytutorial">
<full/>
</access>
</item>
</folder>
</DL>

Now you can compile and deploy your module with Ant tools.

United Nations Conference on Trade and Development Page 20 of 22

 Developer Guide
Version ADK 244
5 - Iterative segment

Summary

Main steps for the creation of an iterative segment in the database:

• Define the constants of the DOM representing the iterative segment in the C_xxx
class.
• Define the Data Model of the iterative segment in a separate file named DS_xxx.
• Add the Data model created in the DS_xxx file as a sub segment in the D_xxx
class.
• In the D_xxx class, add 2 client rules on the sub segment associated to events
(ACT_xxx events; these events must be defined in the C_xxx class).
• In the S_xxx class:
 Define the alias for the table representing the iterative segment.
 Define an access method for this table (getxxx_TAB() method).
 Add visible events (MEN_xxx events; these events must be defined in the
C_xxx class) on operations on which it has to be possible to manage the
iterative segment.
• Create a sub table connector corresponding to the table associated to the iterative
segment.
The key of this table is composed of the key of the table it belongs to and a rank.
• Modify the table connector owning the sub segment: add the sub table
connector.
• Create the visual page representing the iterative segment.
• Create the visual form containing this visual page. This visual form extends the
KVisualFormWithNumberedPages class.
• Add this visual form to the visual document.
• Define the rules in the DC_xxx class: add rules on the visible events (MEN_xxx).
• Create the rules classes that will fire the action events (ACT_xxx).

United Nations Conference on Trade and Development Page 21 of 22