Value list

Getting started

Setup

The setup depends on the list management mode.

Validate the record after saving it so that it is taken into account by the XTEND server.

The reloading of the dictionary should be forced if the 'Update verification' setups of the site are not activated.

 See record Web Site.

Manual management

The list is created/modified in the graphical block (DHTML) at the bottom of the screen.

Creation from scratch

The first value is created:

• right click on the grey icon in the graphical block,
• then addition of values by inserting 'children' to the created value.

The value is deleted or modified via right click.

Creation from an already existing list

It is possible to elaborate a value list from an already existing list created from an X3 message, a miscellaneous table, or a batch list whose content needs to be modified.

In this case:

• create or copy the original value list (based on an X3 message, a miscellaneous table, etc.),
• then modify the Management setup to switch to Manual mode.

It is then possible to modify the content as shown above.

The manual list is not synchronized with the original list.

 The reference to the original list (menu, miscellaneous table, etc....) is lost once the Management setup has been switched to Manual.

Addition of values

When the user adds a value, the following window is displayed.
It aims at entering the value and the entry value.

Description selection

• The description cannot be entered: it systematically comes from an X3 :message or a miscellaneous table to make translating possible.
• The setups below make it possible to enter the origin of the description:
• Origin (reading method of the description),
• Chapter - Number: enter the chapter and the number,
• Miscellaneous table - number: enter the code of the table and the code of the entry.

The generation process of the MEN.xml file generates as many descriptions as there are languages defined for the site.

Entry of the value

Value: this field contains by default the index of the local menu or the entry code of the miscellaneous table used for the description. It is usually modified to associate specific codes when a new value list is created.

Case of the hierarchical categories

The 'linked field' is empty by default. It contains the field of the entity corresponding to the category level to which the value is connected, only if it is different from the field defined by default in the table 'Default field (entity)'.

 See the paragraph on the hierarchical categories.

Automatic management

• Create a value list from an X3 message or a miscellaneous table.
• The content of the list cannot be modified.
• If the message or the miscellaneous table is modified, then the value list should be validated again in order for the modifications to be taken into account. In effect the data are recopied to the MEN.xml dictionary file.

Type
Origin of the Message or Miscellaneous Table list

Message type

Chapter
Chapter no.

Miscellaneous Table Type

Miscellaneous table
Miscellaneous table code

Short title
Yes/No

Hierarchical list

Dependence
No to generate a simple list.
Yes to generate a hierarchical list from the dependencies between the diverse tables.

The link type of the dependencies between miscellaneous tables is 'child to parent', in other words, the 'Dependence table' setup of the 'Miscellaneous tables' record contains the code of the parent table.

The parent table must be used to generate a hierarchical value list from a miscellaneous table.

Level
It defines the tree structure scope, in other words, the number of category levels authorized for the value list.

Batch management

The list is created from a batch process.
The format o the file created via the batch process must be identical to the format of MEN.xml dictionary file.

Root directory
XTEND root directory containing the batch files

There are four root directories to store XTEND files.
Resources (files, images) in these directories can be accessed from the browser via images or attachments tokens.

• HTML design : Directory of the HTML project taking the user language into account
• X_FILES : Directory specific to the X3 folder located under X3_PUB/X3FOLDER/X_TEND/X_FILES
• X_FILEAPP : Directory specific to the X3 folder located under X3_PUB/X3FOLDER/X_TEND/X_FILAPP
  It is used to store the files from batch processes as reports generated by the print server.
• X_TEND : Director used to store files associated to all folders
  For example product images, commercial documents....
  It is located to: X3_PUB/X_TEND/

Design HTML and X_FILES can be placed under the X3 server (by default) or the Web Services server.

X_FILEAPP and X_TEND are always placed under the X3 server.

File
Access path to the batch file with respect to the root directory.

Check the update
'Yes', to trigger regular verification (every minute) of the last modification date of the batch file.

The batch files are reloaded when the XTEND dictionary is itself reloaded.

Management of the hierarchical categories

As previously seen, we know how to create hierarchical value lists displayed as a tree structure.
We are now going to learn how to use this data structure into the form of tokens in HTML pages in order to manage the hierarchical category menus.

A menu of hierarchical categories contains several ListBoxes displayed via the tag <select> whose contents are inter-dependent.

Let us use the following categories to perform selections in a car catalog:

Level 1: Constructor
Level 2: Template
Level 3: Estate or Saloon type
Level 4: Diesel or Petrol fuel

The fields of the car entity containing the codes of the categories of levels 1, 2, 3 and 4 are CAT1,CAT2,CAT3 and CAT4 respectively.

Value list

The first stage consists in creating the value list containing the tree structure of the categories:

Default field (Entity): list of the 'filed tokens' containing the information about the category.
The XTEND entities that will support this category system will need to include the fields defined in the 'Default field' table.

In this example, we enter CAT1,CAT2,CAT3 and CAT4 in this order (See the next paragraph).

Entry of categories: a description and a category code are associated with each category.

N1 - Value=REU - Label=Renault
N2 - Value=CLI - Label=Clio
  N3 - Value=BRK - Label=Estate Car
 N4 - Value=DI - Label=Diesel
 N4 - Value=ES - Label=Petrol Fuel
N2 - Value=MEG - Label=Megane
...

The level '1, 2, 3, 4) of the category corresponds to the rank (1-N) in the 'Default field' table and provides access to the field name bearing the value.

XTEND entity

The XTEND entities (coming from the X3 data) accommodating the hierarchical categories must contain fields that specify the information on the category.

The entity must contain as many category fields as there are category levels (one field by category level).

In our example, the AUTO entity must contain four fields, CAT1, CAT2, CAT3, CAT4 to store the categories.

The category fields are associated with the AUTOS list of values that contains the category tree structure.

These fields must be defined in the table setup 'Default field (Entity) of the value list.

In our example, the table contains CAT1, CAT2, CAT3 and CAT4.

We have thus defined a link between the tree structure and the XTEND entity via the category fields.

Selection

In order to express a hierarchical category, a path type syntax is used with the character / as separator.

For instance /REU/CLI/BER, /PEU, /PEU/107.

To store the hierarchical categories with the path format, a (working) field is used.

This text type field is defined in the dictionary and a value list is associated to it.

The value of this field is elaborated using a JavaScript function based on those criteria selected by the user and sent to the XTEND server via a field in the HTML form.

In our example, this field is CATPATH.

Definition of the selection criteria

To carry out a selection on the entity, a dynamic link token must be created and selection criteria added.

A criterion is created for each category field and its value is compared with that of the field containing the 'path' of the category.

Formula of the dynamic link token:
CAT1 =web:CATPATH Et CAT2 =web:CATPATH Et CAT3 =web:CATPATH Et CAT4 =web:CATPATH

To calculate the value of the criterion, the XTEND engine creates a link between the level of the category field (CAT1, CAT2, etc.) and the position of the value in the 'path' of the category.

Example for the /REU/CLI/BER category:

The XTEND engine performs the following processing when valuating the selection criteria:

1. Reading of the value of the CATPATH Web field,
This field contains the path /REU/CLI/BER

2. For each criterion:

• Calculation of the category field level in the tree structure (CAT1,CAT2...)
  The level is indicated by the rank in the table Default field (Entity) of the value list
• extraction of the path value according to the level
  CAT1=REU - CAT2=CLI - CAT3=BER

The CATPATH field acts as if it contained a table classifying the categories.

HTML page

This paragraph describes how to implement the following elements in the HTML page:

• the automatic filling of the HTML <select> tags containing the values of the selection criteria,
• the calculation and update of the path that will contain the path of the selected category (CATPATH).

The XTEND tokens are used to process these two operations while keeping the JavaScript code to be developed to a minimum.

Display of the selection criteria

As shown here below, four selection boxes corresponding to the four categories used to select cars have been created.

HTML

<table>
<tr>
<td>
 <select name="CATPATH1" adx="CATPATH:xlevel=1&xonchange=DLKSELECTAUTOS">
 <option value="">Indiff&eacute;rent</option>
 </select>
</td>
<td>
 <select name="CATPATH2" adx="CATPATH:xlevel=2&xonchange=DLKSELECTAUTOS">
 <option value="">Indiff&eacute;rent</option>
 </select>
</td>
<td>
 <select name="CATPATH3" adx="CATPATH:xlevel=3&xonchange=DLKSELECTAUTOS">
 <option value="">Indiff&eacute;rent</option>
 </select>
</td>
<td>
 <select name="CATPATH4" adx="CATPATH:xlevel=4&xonchange=DLKSELECTAUTOS">
 <option value="">Indiff&eacute;rent</option>
 </select>
</td>
</table>               

CATPATH field: contains the 'path' of the current category (e.g. REU/CLI forRenault/Clio)

'adx="CATPATH:xlevel=N' : this syntax specifies to the XTEND engine that the list of options must be loaded with the values of the category corresponding to level N of CATPATH:

• If CATPATH=REU/CLI and xlevel=1
  Displays the list of manufacturers (level 1 of the category hierarchy).
• If CATPATH=REU/CLI and xlevel=2
  Displays the list of models (level 2 of the category hierarchy) for the manufacturer REU (Renault).

When the CATPATH page is first displayed, it is empty and the 'Indifferent' option is displayed (value="").

'xonchange=DLKSELECTAUTOS': this runs the DLKSELECTAUTOS dynamic link whenever the field value is modified.

This setup prevents having to add a button <input type='button' adx="DLKSELECTAUTOS" value="Select"> on which the user must click after modifying the criterion.

Calculation of the CATPATH path

The JavaScript functions below are used to calculate the 'path' of the selected category:

//-------------------------------------
//aObj is the DOM (select) object which have been modified
//--> new selection
//Calculates the level (MaxLevel) of the category according to the name of aObj
//--> CATPATH1 indicates level 1 - CATPATH2 indicates level 2 ...
//Calculates the path of the category from level 1 to wMaxLevel
//Reset of the field having a level superior to wMaxLevel
Returns the path
function getCatCar(aObj)
{
 var wCatPrefix="CATPATH";
 var wCat="";
 if (!aObj || !aObj.name) return wCat;
 var wMaxLevel=parseInt(aObj.name.slice(wCatPrefix.length),10);
 for( var i=0;i<wMaxLevel;i++)
 {
   var wVal=xtdGetFieldVal(wCatPrefix+(i+1));
   if (wVal!="")
   {      
     if (i>0) wCat+='/';
     wCat+=wVal;
   }
 }
 // Reset o the fields
 for( var i=wMaxLevel;i<4;i++)
   xtdSetField (wCatPrefix+(i+1),"");
 return wCat;
}
//-------------------------------------
//xtdDoMyDlk is called when the user clicks ona dynamic link
function xtdDoMyDlk(aDomOut)
{
   var wContinue=true;
   //DLKSELECTAUTOS --> Modification o a selection criterion
   if (aDomOut.isClickedDynLink("DLKSELECTAUTOS"))
   {                      
     // Calculation of the category path 
     var wCat=getCatCar(aDomOut.getDynLinkCtx().getHtmlElement());
     //Update of CATPATH field which is transmitted to XTEND engine
     //--> See the selection criteria of DLKSELECTAUTOS link
     xtdSetField("CATPATH",wCat);   
   }
   return wContinue;
}

The DLKSELECTAUTOS dynamic link is run whenever the user modifies a category.

The 'xtdDoMyDlk' function is used to run specific processings before submitting the form to the XTEND server.

This function:

• calculates the new 'path' of category (getCatCar()),
• values field CATPATH transmitted to the server.

As a consequence, the server will perform the new selection and calculate the new values of the selection criteria.

Selection reset

The function below reinitializes the selection criteria and recalculates the page.

<script>
function selAllCars(aObj)
{
 xtdSelectSetVal("CATPATH1","");
 xtdSelectSetVal("CATPATH2","");
 xtdSelectSetVal("CATPATH3","");
 xtdSelectSetVal("CATPATH4","");
 xtdDoDlk(aObj,"DLKSELECTAUTOS");
}
</script>

<input type="button" value="Reset" onClick='javascript:selAllCars(this);'>

Prerequisites

Refer to documentation Implementation

Screen management

Entry screen

Specific Buttons

Error messages

The only error messages are the generic ones.

Tables used

Refer to documentation Implementation