Contact form

Functionning

Here is the method to apply to create an 'XTEND form' by carrying out an action 'Save' on the X3 AYZ object from a click on a button of the HTML page. The form data are entered by the user in the fields of the HTML form and are used as action setup.

If the XTEND site was created from a copy of the ASAMPLE site, the setup records are already present.

Otherwise it is possible to either create them or to copy them one by one from the ASAMPLE site via the X3 action button 'Copy'.

An XTEND form is formed of:

a header (list section):

The subject (TTL)
The user email (MAICOD))
The message(CMT))
The Type (TYP)

of setups (grid section) used to manage options:

The description (PARCOD)
The value (PARVAL)

The data calculated upon creation are the code (FRMCOD), the status (STATUT) and the creation date (CREDAT).

In this example, the aim is to create a contact request form (TYP=CON) with following options concerning the person:

Company
Activity
Postcode

Creation

Creation of an HTML page (AXTDFRMCREATE) with an entry form.
For the purpose of this example, the form data are transferred in encrypted mode (HTTPS)
Creation of an interface (AXTDFRM) for the Web service call
Creation of a Web action of type X3 object creation (AXTDFRMCREATE) having as input setups the Title, the email, the comment and the list of selected options.
These setups will be 'mapped' on the setups upon Web service entry.
Creation of a dynamic link token (ADLKCONTACTNEW) which will be inserted in the HTML page (button 'Create') in order to value the setups with the value of HTML form fields and trigger the action.

Display

After creation, the form is displayed in blocked mode in the current page so that the user can verify the content.

This means reading the data sent by the Web service (header and setups) and displaying them on screen.

The read is carried out by mapping the setups when getting out from the Web service to two XTEND entities (XTDFRMHEAD and XTDFRMPARAM) in order to create data in memory and by inserting 2 section tokens (ABLKFRMHEAD and ABLKFRMPARAM) in the HTML page to display the data.

A 'conditioned section' token (ACNDXTDFRMHIDE) manages the display in the same page (enterable form or form created as not enterable).

Inquiry

The created forms may be inquired via X3 function Form(GESAYZ)

X3 setups

This section is a complement to the procedure to create a user action.

Step no. 1 - Creation of the interface

1. Create interface 'Object user action' AXTDFORM based on the publication name of the object AYZ (AXTDAYZ)

2. generate access.

3. Generate all the fields of the interface
Refer to menu 'Tools/Field token creation'

Step no. 2 - Creation of the entities

Create entities:

AXTDFRMHEAD with the header fields
XTDFRMPARAM with the fields of options PARCOD and PARVAL

Refer to menu Tools\Entry help.

This entities are then used in the return mapping of the form creation action.

In this example, 2 keys have been defined for AYZ:

FRMCOD, which corresponds to the form identifier
FCYCOD, which is the XTEND site code and is equal to the current site code.

FCYCOD filters the forms depending on the ASAMPLE current site.

It is necessary to delete this key in order to read all the forms of the database

Step no. 3 - Creation of the Web action

Setup reporting

Create a AXTDFRMCREATE action of type 'standard' having as setups the type, the title, the email, the comment and the options.

Only the Web service setups depending on the action call context are declared as setups of the action being entered.

The dynamic link token indicates how they are valued depending on the call context (Web field, XTEND field...).

Deletion on start'
checked to delete entities AXTDFRMHEAD and AXTDFRMPARAM at the action start (before the result of the sub-program call) in order to manage correctly the result display in the same HTML page via a 'conditioned section' token based on the presence of field FRMCOD.

Activity tracking
Yes: for all action calls to be recorded in a log file

Active on reload
No: to prevent a form from being created when pressing the F5 key after creating the form;

Activation button
Create: to trigger the action button Save object AYZ

Mapping of setups on entry

This aims at matching the XTEND field with the setups for web service call.

In this example it is only necessary to map setups of action TYP, TTL, CMT,MAIDCOD, PARCOD and PARVAL.

The mapping of PARCOD and PARVAL is of type Multi, which makes it possible for the XTEND server to 'map' several HTML fields having the same name on a multi-dimension setup.

The entity code is not to be entered in order to "map" action setups.

The Web service setups whose value comes always from the same context can be valued directly in the action mapping by specifying the entity.

For instance, if the login user code should be passed on, it could be mapped directly with the AUSERCODE field of the ASESSION entity rather than declared as setup of the action.

Mapping of setups on exit

Two XTEND entities should be created from the data returned by X3:

AXTDFRMHEAD to store fields of the list screens
AXTDFRMPARAM (Multi) to store fields of the grid section which contains the setups

The entities of Action type are stored for later use during the user session.

They are automatically re-created upon each action call.

Entities deletion action

To manage the display via a "conditional section", the entities should be deleted the first time the page appears (when ADLKCONTACT -dynamic link token- is clicked on in the left menu).

An action is created AXTDFRMRESET for this purpose in order to delete the entities AXTDFRMHEAD and AXTDFRMPARAM.

This action is associated to the ADLKCONTACT token.

Type
Standard

Interface
None

Step no. 4 - Creation of the dynamic link

The dynamic link ADLKXTDFRMCREATE is the token that is inserted in the form creation button

It is used to define the destination page (current page), to associate the action AXTDFRMCREATE and to value the setups.

General setups

Activity tracking
Yes: so that any click on the link be recorded in the log file

Force the http post mode
No: Since an action with setups is associated with the dynamic link, the request is sent automatically in POST mode

Current page
Yes: The result (created message or form) is displayed in the current page

Action
Code of the action to trigger

Control web fields
Yes : To control web setups (see "Action" section)

Action setups

This aims at declaring all action setups and at indicating the method to value them.

TYP field
Constant: The form type is always the contract type (CON)

TTL, MAICOD field
'Mand. Web fld': Mandatory entry by web field.

CMT, PARCOD, PARVAL fields
"Web field": Non mandatory entry by web field

Cste/Attrib. web
Contains the input tag name (attribute name)

The entry control is active only if the option "General/Control Web fields" is ticked.

The query is sent to the XTEND server only if:

the user valued all the mandatory fields
the entered data is correct for the fields of type date and numeric.

The control is carried out by the XTEND JavaScript library.

Page display token

The ADLKCONTACT token can be used to display the form creation page from the left menu.

To manage the display via ACNDXTDFRMHIDE (conditional section), it is necessary to erase the form entities at first display.

This operation is done by associating the AXTDFRMRESET action to the ADLKCONTACT token.

This token is used to display the page in secured mode (https) to indicate to the user that the data are encrypted.

Activity tracking
Yes

Force the post mode
Yes: To maintain the XTEND context saved in the current page.
The HTTP GET method is used only for links such as "anchor" links that must be compatibles with web crawlers.

Current page
No/AXTDFRMCREATE: Destination page

Action
AXTDFRMRESET : To delete form entities

Step no. 5 - Creation of the section tokens

ABLKFRMHEAD and ABLKFRMPARAM section tokens are used to display AXTDFRMHEAD and AXTDFRMPARAM entities which represent the data of an XTEND form.

Header section

Type
Single-record: Reads the AXTDFRMHEAD entity, places the data on top of the data context pile and execute the child tokens

No data
Nothing displayed: If entity AXTDFRMHEAD does not exist, the section and the child tokens are not taken into account

Entity
AXTDFRMHEAD : Code of the entity to display

Parameters section

Type
Multi record: Performs an iteration on all AXTDFRMPARAM entities and positions each entity at the top of the data context stack and then carries out the child tokens

No data
Nothing displayed: If entity AXTDFRMHEAD does not exist, the section and the child tokens are not taken into account

Entity
AXTDFRMPARAM : Code of the entity to display

Line by section
10: Displays maximum 10 AXTDFRMPARAM entities in the page

Cell by line
1: Displays one AXTDFRMPARAM entity per line

Style per line
None: Styles to define in "my.css" file to alternate the background line color

It is not possible to define selection criteria on the sections selecting the entities stored in the XTEND server memory, that are of Session or Action type. The section selects automatically all entities.

The selection criteria are only applied to entities of type "Data access".

Step no. 6 - Creation of the conditional section token

This aims at illustrating the use of conditional sections.

The ACNDXTDFRMHIDE token is used to modify the page content depending of the presence of a form or not.

If the AXTDFRMHEAD entity exist (ABLKFRMHEAD section not empty), it means that a form has been created and that it should be displayed
If the AXTDFRMHEAD entity does not exist (ABLKFRMHEAD section empty), it means that the entry fields should be displayed.

Display
Not ticked: Indicates that the token content (html and child tokens) is hidden if the condition is checked.

Criteria type
Empty section: Indicates that the display/hide conditions is based on the fact that one section contains data or not

Section
ABLKFRMHEAD : Section code to test

The AXTDFRMRESET action -which deletes form entities- has been created so that entry fields are displayed when the page is first displayed even if a form has been created previously.

This action is called by AXTDFRMRESET dynamic link token which displays the form creation page from a click in the left menu.

Step no. 7 - Page creation

Create the AXTDFRMCREATE web page.

Default page
Associate the contact.html file.
The file must be present on the X3 server and can be selected by the F12 key.

Protocol
Https: Used to indicate that it is necessary to encode the Http query (see HTTPS configuration)

Main section and background section
None

Protected access
No: used to indicate that this page is in open access (anonymous)

Activity tracking
Yes: used to record each page display in a log file

Step no. 8 - Site validation

After modification of the X3 setups, it is advised to validate the site as a whole in order to build the XTEND server dictionary via function 'Web site validation (AYTFCYGEN)'.

Verify that the XTEND site is published, that is that the field "Publish the site" of the "Web site" record is checked.

HTML page

Link to the page

Insertion of the ADLKCONTACT dynamic link in the left menu in order to display the page and delete the last form created.

<TD class="button"><A adx="ADLKCONTACT">Contact us</A></TD>

Display management

The "conditional section" token ACNDXTDFRMHIDE is used to display the form entry if no XTEND form has been found. Otherwise, it displays the content of the form.

<!adx="ACNDXTDFRMHIDE">

<!adx="ACNDXTDFRMHIDE">
<!adx="ACNDXTDFRMHIDE:xNot">


<!adx="ACNDXTDFRMHIDE">

Header entry

Creation of <input> fields with the adx="FieldName" token.

When no attribute name is specified in an <input> tag it is generated automatically with the adx token name.
In case of an entry error discovered by the XTEND server of the X3 application, the setup xrc(<input adx="TokenName:xrc">) is used to display again the last value entered.
It makes it possible to avoid loosing entered data.

<H1>Contact us</H1>
<table>
   <tr>
      <td><b><b>Email:</b></td>
      <td>
          <input type="text" adx="MAICOD:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b><b>Subject:</b></td>
      <td>
          <input type="text" adx="TTL:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b>Message:</b></td>
      <td>
          <textarea adx="CMT:xrc" rows="5" cols="75"></textarea>
      </td>
   </tr>
</table>

Options entry

Creation of fields couples: <input> such as Key/Value that will be "mapped" on two columns of a grid section or two N dimension setups of a sub-program.

PARVAL contains the value entered by the user
PARCOD contains the code which has the fiwe value and which cannot be seen ("hidden").

The mapping of PARCOD/PARVAL couples with web service setups is done according to the order of creation of fields in the HTML page.

<tr>
    <td><b>Société:</b></td>
    <td>
        <input type="Text"   adx="PARVAL:xrc" size="50">
        <input type="hidden" name="PARCOD" value="Société">
    </td>
</tr>
<tr>
    <td><b>Activité:</b></td>
    <td>
        <select adx="PARVAL">
            <option value="">Préciser :</option>
            <option value="Artisans" >Artisans</option>
        </select>
        <input type="hidden" name="PARCOD" value="Activité">
    </td>
</tr>
<tr>
    <td><b>Code postal:</b></td>
    <td>
        <input type="text"   value="" adx="PARVAL:xrc" size="10">
        <input type="hidden" name="PARCOD" value="Code Postal">
    </td>
</tr>

Creation button

Creation of a "Button" input with the adx attribute which contains the dynamic link code.

All <input type="button"> buttons containing adx tokens must be of type 'button'.
The submit type should not be used.

A user action is considered as validated if no error message was sent by the Web service call.

Error messages are sent in 4GL via sub-program ADDMESSERR (Call ADDMESSERR("Message") From AWEB)

X3 messages are displayed via the token AXUSERMSG.

Ex: <span id="userMsg" class="userMsg" adx="aMsgUser"></span>

Automatic control of entry

MAICOD and TTL fields have been defined as mandatory web fields, the control is done automatically and does not require any addition of a JavaScript code.

Displayed error messages are AJSWEBFLDMANDAT (mandatory field and AJSWEBFLDBADVAL (format error).

Additional control in JavaScript

It is possible to add controls in JavaScript on Web setups by adding a JavaScript function called xtdWebParamCheckValue in the HTML page.

If the XTEND library detect the presence of this function, it will be called with the following setup:

aWebParamOutl'objet which represents the setup

aWebParamOut .setValue(String) valuates the setup
aWebParamOut .getValue() returns the setup value

aInputFieldName the setup code
aInputFieldIndex the index if the link is placed in a section
aInputFieldValue the setup value

This function returns true\false to confirm\deny the entry.

The AJSWEBFLDBADVAL message is displayed if there is an entry error.

A function that control the email format has been added in the sample page.

The xtdWebParamCheck function is used to filter the fields to control.

It works the same way as xtdWebParamCheckValue.

Header display

The ABLKFRMHEAD section is used to position the data context.

The fields are displayed via an adx token placed in an HTML tag.

<table width="90%" border="0" cellspacing="2" cellpadding="4">
<!adx="ABLKFRMHEAD">
    <tr>
        <td><b>Email:</b></td>
        <td adx="MAICOD"></td>
    </tr>
    <tr>
        <td><b>Sujet:</b></td>
        <td adx="TTL"></td>
    </tr>
    <tr>
        <td><b>Message:</b></td>
        <td><pre adx="CMT"></pre></td>
    </tr>
<!adx="ABLKFRMHEAD">
</table>

Display options

The ABLKFRMPARAM section is used to repeat the form options and to create as many <tr> lines as options.

For each option, XTEND sets a data context in order to resolve the value of PARCOD and PARVAL adx tokens placed in the HTML tags.

<!adx="ABLKFRMPARAM">
    <tr>
        <td><b adx="PARCOD"></b></td>
        <td adx="PARVAL"></td>
    </tr>
<!adx="ABLKFRMPARAM">

JavaScript

The pageDoMyDlk entry point is used to add a process on a user click and to cancel the current process if false value and returned.

In this case, a confirmation is asked before posting the form to the XTEND server.

//Asks user to confirm creation of a new form if user clicks on ADLKCONTACTNEW dynamic link
function pageDoMyDlk(aDomOut)
{
    if (aDomOut.isDlk("ADLKCONTACTNEW"))
        return confirm('Confirm form creation\Confirm creation');
    return true;
}

The xtdWebParamCheckValue entry point is part of the control mechanism of values for XTEND "web fields" (XTEND actions web setups).

If the xtdWebParamCheckValue function is defined in the HTML page, it is called by the XTEND library for each control of "web fields".

In this case, the control of the MAICOD (email) field value via the xtdCheckEmail XTEND function.

//This function is used to customized control on web parameters values
function xtdWebParamCheckValue(aWebParamOut,aInputFieldName,aInputFieldIndex,aInputFieldValue){
    // Check input email value
    if (aInputFieldName=="MAICOD"){
        var wEmail=xtdCheckEmail(aInputFieldValue);
        if (wEmail && wEmail!=aInputFieldValue)
            aWebParamOut.setValue(aInputFieldIndex,wEmail);
        return wEmail!=null;
    }
    return true;
}