Development > Safe X3 WAS > Tokens > Blocks 

SEEWARNING Before creating your site, it is advised to read the documentation:Before beginning.

The block token reads and displays the entity allocated to the section by setup:

1. It reads the entity/ies from the X3 database by calling up an interface (Web service) of type 'Access to data',

2. It carries out an iteration on the returned entities to create dynamically the lines of a grid.

Getting started


The block token is inserted in the HTML page by using following syntax:

        <td adx="aBLKELMTRANK"></td>
        <td adx="ITEMREF"></td>

The XTEND engine processes the blocks as follows:

Parsing phase of the HTML page.

This stage is performed only once when the HTML page is loaded:

  • Creation of the block object and addition to the structure,
  • Calculation of dependencies between the blocks if the selection of a block depends on another block.
    The result of this calculation provides the initialization order of the blocks
Generation phase of the HTML page.

This stage is carried out each time the HTML page is displayed:

1. Block initialization

  • Calculation of selection criteria according to the selection type,
  • Calling up of the Web service 'Access to data' with the selection criteria as a setup,
  • Creation and storage in the memory of the returned entities.

2. Iteration on all returned entities

  • Inserting of the entity in the data context,
  • Calling up of the HTML generation method for sub-tokens,
  • Deletion of the entity in the data context,

In previous example, if the selection displays 3 products of code PUZ001, PUZ002 and PUZ003, a 3-line grid will be obtained:







The generated HTML is as follows:

The HTML 'child' of the block token was repeated 3 times and was recalculated each time with respect to the new data context (current line).


Selection and sort

The block token not only displays data grids, it also manages the dynamic modification of selection and sort criteria.

The block setups set the default criteria and it is possible to authorize or deny the modification of these criteria by a dynamic link.

The dynamic link token can modify the block criteria and it is also possible to define selection and sort setups for this token.

Only the selection and sort criteria or the page main block (alias AMAIN) can be modified by the dynamic link criteria.

It is possible to define several blocks by page, but only one of them (the main block) has selection and sort criteria that can be modified by the user.

There are three types of modification via dynamic link for the block criteria:

  • The criteria of dynamic link 'Replaces main block selection':
    • Block selection = link selection criteria

  • The criteria of dynamic link 'Added to main block selection':
      • Refines the block request with the link criteria,
      • Block selection = block selection criteria + link selection criteria

  • The criteria of dynamic link 'Added up to current main block selection':
      • Refines the block request by adding the dynamic link selection (AND logic) to the current block request,
      • This option is used if the block selection results from the aggregation of several dynamic links,
      • Block selection = block selection criteria + sum of the criteria of all clicked links.

These three options make it possible to handle most situations occurring in Web pages.

The block token record is used to set up the block selection and sort criteria.

These are the default criteria applied at first display of the page containing the block.

The block token proposes two setups 'Modifiable selection' and 'Modif. sorting' indicating if the selection criteria and/or sort criteria can be modified by a dynamic link.

These setups are only applied if the block was defined as main block in the record of the Web page displaying it.

Block containing several cells by line

In order to display a block with several cells by line, the specific token ASTAMP is used to delineate the cell.

The XTEND server repeats the HTML code present between the two ASTAMP tags as many times as cells in the line.

<!-Iteration on the lines of the block-->
        <!-Code repeated as much as there are cells by line'-->
                <!--to alternate the color of the cells-->                           
                <td adx="ALINESTYLE:xattr=Class">
                   <!--HTML code of a cell-->
                   <b>Name</b><p adx="NAME"></p>
                   <b>First name</b><p adx="FIRSTNAME"></p>

How to fill the empty cells

The example below shows how to fill empty cells when the number of recordings is not a multiple of the number of cells by line.

The conditioned blockADISPSTAMPEMPTY is used to define the HTML dedicated to the empty cells.

<!-Iteration on the block lines-->
                <td adx="ALINESTYLE:xattr=Class">
                        <!--Empty cell filled with a blank-->      
                        <!--HTML code of a non empty cell-->
                        <b>Nom</b><p adx="NAME"></p>
                        <b>Prénom</b><p adx="FIRSTNAME"></p>   

Actions impacting the blocks

Page numbering

The actions ABLKFIRSTPAGE, ABLKNEXTPAGE, ABLKPREVPAGE, ABLKLASTPAGE are used to manage the page numbering in the blocks.

The tokens ADLKFIRSTPAGE, ADLKNEXTPAGE, ADLKPREVPAGE, ADLKLASTPAGE can be used on the page main block.

The fields aBLKNBELMTS and APAGEPOS display the total number of recordings and the position of the page compared to the total page number.

The conditioned blocks AHIDEMAINFIRSTPAGE and AHIDEMAINLASTPAGE manage the display/hide status of page numbering buttons for the first and last pages.



For example:

Page numbering with display management at start and end of page numbering.

<table width="100%">
        <td align="left" width="20%">
        <!--Hide FirstPage and Previous actions if current page is the first page-->           
                <a href="" adx="AMAIN.aDlkFirstPage">First</a>
                <a href="" adx="AMAIN.aDlkPrevPage">Previous</a>
        <!--Displays page information-->
        <td align="center" width="60%">
            Page: <span adx="AMAIN.aPagePos"></span> -
            Number of elements: <span adx="AMAIN.aBlkNbElmts"></span>
        <td align="right" width="20%">                         
        <!--Hide LastPage and Next actions if current page is the last page--> 
                <a href="" adx="AMAIN.aDlkNextPage">Next</a>
                <a href="" adx="AMAIN.aDlkLastPage">Dernière</a>

Selection of a line

The dynamic links ADLKSELECT and ADLKUNSELECT (action ABLKSELECT and ABLKUNSELECT) are used to select/deselect a block line.


Insert the tokens ADLKSELECT and ADLKUNSELECT in one of the line cells either in a tag <a> or in a tag <input type='button'>.

The field ABLKSELECTEDLINE contains the rank (1 to N) of the selected line.

For example:

The block ABLKCOUNTRIES displays the countries in the site ASAMPLE with selection of the line to display the detail Currency/Country language.

A click on the first cell (CRY) selects the line.

        <td><a adx="ADLKSELECT"><span adx="CRY"></span></a></td>
        <td adx="CRYDES"></td>    
        <td adx="CUR"></td>
        <td adx="LAN"></td>                
<!--Display the no. of lines selected-->

The HTML setup 'xSelect=true' is used to select the first line by default.

If this setup is not used, or if its value is 'false', the block has no selected line by default.

When a block has a selected line, it is possible to access the fields of this line via the syntax MyBlock.MyField.

The values of the fields of the selected line can be displayed or used as criteria in a block, dynamic link, or conditioned block.

The conditioned block AHIDEMAINSELECT displays/hides an HTML zone taking into account whether the main block has a selected line or not (see country page of site ASAMPLE).

Return of detail to list

The action ABLKRESTOREMAINCTX is used to get back to a list page from a detail page without loosing the page numbering or the selected line of the main block.

The dynamic link below is used to get back to the page FORMQUERYRES and restore the main block context.

<input type="button" value="Return list" adx="DlkFrmQueryBack" class="xtendButton" >

Direct access to the line data

The following syntax is used to access directly the data of a block line:

<!--First line-->
<span adx="MYBLOCK(first).MYFIELD"></span>]<br>
<!--Last line-->
<span adx="MYBLOCK(last).MYFIELD"></span>]<br>
<!--N line-->
<span adx="MYBLOCK(N).MYFIELD"></span>]<br>

Access to the data of a block in JavaScript (JSON)

The following syntax is used to value a JavaScript variable with the JSON representation of a block or block line:

    // JSON data of a block
    var wMyBlock_JSON=<!adx="MYBLOCK(*)"><!adx="MYBLOCK(*)">;
    var wMyBlock_JSON=<!adx="MYBLOCK(*)"><!adx="MYBLOCK(*):xinclude=FIELD1,FIELD2">;
    var wMyBlock_JSON=<!adx="MYBLOCK(*)"><!adx="MYBLOCK(*):xexclude=FIELD1,FIELD2">;
    // JSON data of a line
    var wMyLine_JSON=<!adx="MYBLOCK(2)"><!adx="MYBLOCK(2)">;
    var wMyLine_JSON=<!adx="MYBLOCK(2):xinclude=FIELD1,FIELD2"><!adx="MYBLOCK(2)">;
    var wMyLine_JSON=<!adx="MYBLOCK(2):xexclude=FIELD1,FIELD2"><!adx="MYBLOCK(2)">;

The JSON variable of a block is composed of an array of lines:

    var wMyBlock = [{line 1},{line 2},...];
var wMyBlock = [{"STATUT":1,"STATUT_DESCR":"To process","PRIX":81.35,"COD2":"30-112"},
    {"STATUT":1,"STATUT_DESCR":"To process","PRIX":606.15,"COD2":"32-034"}];

The JSON variable of a line is an object containing fields:

    var wMyLine ={"FIELD1":"Value1","FIELD2":"Value2"...};
var wMyLine = {"STATUS":1,"STATUS_DESCR":"To process","PRICE":606.15,"COD2":"32-034"}

For a field, the xjson setup generates a JSON object {"FieldName:"Value"}. Without xjson setup, the JavaScript variable is valued with the field value.

    // JSON data of a field
    var wMyField_JSON=<!adx="MYFIELD:xjson"><!adx="MYFIELD">;
    //XTEND generates
    var wMyField_JSON={"MYFIELD":"Value"};
// Field value
    var wMyField_JSON=<!adx="MYFIELD"><!adx="MYFIELD">;
    //XTEND generates
    var wMyField_JSON="Value";

HTML setups






Selects the first line by default

Fields of a block






Index of an element in a block (O->ABLKNBELMTS-1)



Rank of an element in a block (1->ABLKNBELMTS)



Index of line in a block (O->ABLKNBELMTS-1)



Rank of line in a block (O->ABLKNBLINES)



Total number of elements (recordings) of a block request



Rank of the selected line of a block via action ABLKSELECT



Number of lines in a block



Number of pages in a block



Rank of a block current page




Predefined blocks

Predefined blocks




Contains all fields of type constant


Current data context (top) in XDEND stack of data


HTML form


HTTP cookies


Main block of a page defined in the page setups


Background block of a page defined in the page setups


User messages


In the expression MyReferenceBlock.MyLinkToken, the block MyReferenceBlock corresponds to 'reference block' ;
The data context of this block is set as a setup for the action


Contains the user session data


Contains the user criteria (HTML setup xcrit)


Contains the user data provided by the login


Contains the user variables created by the functions JavaSCript xtdSetUserVar/xtdRemoveUserVar


SEEREFERTTO Refer to documentation Implementation

Screen management



The following fields are present on this tab :

  • Site (field FCYLIB)
  • Title (field INTIT)




Tab General


General setups of the block.




The following fields are present on this tab :


  • Type (field TYP)
  • Lines per block (field BLCNBRLIN)
  • Cells per line (field LINNBROBC)
  • field INTTYP



Tab Selection


Parameters of the selection associated with the block.




The following fields are present on this tab :


  • Selection type (field SELTYP)
  • Modifiable selection (field SELDYNALT)
  • Optimization (field INTOPTIMI)

Selection synthesis

  • field RES30

Table Selection criteria

  • And/or (field ANDOR30)
  • ( (field BRKLFTM30)
  • Field (field FIEKEY30)
  • field OPE30
  • Source (field VALTYP30)
  • Web const./alloc. (field VALEUR30)

The parameter value is entered here. Depending on the case, this value is entered as if it were a number, a date or an alphanumeric code. When the parameter is of local menu type, it is possible to enter either the beginning of the name or the numeric value corresponding to the position of the name in the list. When the code is controlled by an annex table, a selection key may be used to select it.

  • Field (field VFIEKEY30)
  • ) (field BRKRGTM30)
  • Mandatory criteria (field CRIOBY30)
  • Char. * for all (field ALLSTAR30)



  • field INTTYPSEL



Tab Sort


The following fields are present on this tab :


  • Sort type (field SRTTYP)
  • Modifiable sort (field SRTDYNALT)

Table Sort

  • Field (field FIEKEY31)
  • Sort order (field SRTORD31)



Tab Advanced


The following fields are present on this tab :

Date returned by block

  • No data (field OPTDSY)

Table Style per line

  • Style (field LINSTY)

Table Param sub-routine access

  • Source (field VALTYP41)
  • Web const./alloc. (field VALEUR41)
  • Field (field VFIEKEY41)




By default, the following reports are associated to the function :

 PRTSCR : Screen print

This can be changed by a different setup.

Specific Buttons

This button is used to update the XTEND dictionary in XML format.

The X3WEB server takes into account only the dictionary with this format.

There is one xml file per dictionary.

For instance, the ACT.xml file corresponds to all the web actions for the current web site.

This button is used to copy a block token.

Menu Bar

Tools / Validation with checking

Validation and check of the coherence of XTEND dictionary data.

Error messages

The only error messages are the generic ones.

Tables used

SEEREFERTTO Refer to documentation Implementation