Dynamic links

Getting started

Web action

There are two types of actions:

• Actions processed by X3 back-office via the call to the web service:
• Login, order creation, modification of contact details, among others.
• Actions processed by the XTEND server:
• Paging, line selection, change of site/language..

Each action is declared in the dictionary for a setup record.

The destination web page

This is the page displayed after the request has been posted on the server.

Each page is declared in the dictionary for a setup record.

 The destination page can be modified by the action.

To modify the destination page per program (4LG), the user must use dynamic links sequence (programmed sequence):

Value a parameter of the sub-program using the code of the dynamic link (with or without action/selection) which points to the destination page.

Selection

The dynamic link can post a selection to the target page's man section in order to modify the selection criteria.

The selection enables the user to manage the link detail list, the sort of the tables or the refining of the requests.

 For further information, see the documentation on the Section Tokens.

HTML setups

The following setups are taken into account by dynamic links.

<a adx="MyDynLink:xacceptreload&xparams=?PARCOD1=VAL1~PARCOD2=VAL2#xtdbottom">

This example:

• forces the execution of the action "on F5"
• valuates 2 user variables : PARCOD1 and PARCOD2,
• positions on the 'xtdbottom' bookmark of the destination page.

Positionning in the destination page

The following example showis how to position an object in a destination page (via HTML setup xparams) when the user clicks on a dynamic link:

<!--Dynamic link in the original page-->
<input type="button" value="Click here" adx="MYDYNLINK:xparams=#bookmark">
<a adx="MYDYNLINK:xparams=#bookmark">Click here</a>
<!--Destination page-->
</body>
    <!--Code HTML -->
    <a name="bookmark">
    <!--Positioning of the page when the user clicks the button above-->
    <!--Code HTML -->
</body>

Valuate user variables via the URL setups

The following example shows the valuation of PACOD1 and PARCODE (user variables) with VAL1 and VAL3 (via HTML setup xparams) when the user clicks on a dynamic link:

<!--Dynamic link in the original page-->
<input type="button" value="Click here" adx="MYDYNLINK:xparams=?PARCOD1=VAL1~PARCOD2=VAL2">
<a adx="MYDYNLINK:xparams=?PARCOD1=VAL1~PARCOD2=VAL2">Click here</a>

Case of utilization: detail list link

The detail list link consists in defining a link to access the detail of an entity displayed in a list.
For example: access the detail of the item via the catalog.

The page details generally contains futher information from other tables than the one used to display the list.
For instance, the rich description record of a product or associated products (cross-selling).

Conversely, the user will have to return to the list from the detail page without losing the context of the list (selection criteria, paging...).

1. Creation of the entity displayed in the list

• Interface creation,
• Creation of fields,
• Creation of entities.

2. Creation of a "multi-entries" section to read and display the list

• Selection of the entity defined previously.

3. Creation of a dynamic link to select the entity details

• Selection of the same entity as the list section.

The dynamic link selects an entity so that the code is the same as the current line code.
The current line is identified by the ACURRENT section (top of the the data context stack).
The link "Replace the selection of the main section".

4. Creation of the web page which displays the list

• Declaration of the list section as a main section of the web page,
• Creation of the HTLM to display the list.

<table>
    <tr>
        <th><b>Code</b></th>
        <th><b>Label</b></th>
    </tr>
<!--List section-->
<!adx="BLKITMLST">
    <tr>
        <!--Link to detail-->
        <td><a adx="DLKDETAIL"><span adx="CODE"></span></td>
        <td adx="DESCR"></td>
    </tr>
<!adx="BLKITMLST">
</table>

5. Creation of a "mono-entries" section to read and display the detail

• Selection of the same entity as the list section.

The mono-entry section has a selection of the type "Lat clicked link" in order to use the selection criteria of the dynamic link clickedby the user (which has been created previously via the selection on ACURRENT.CODE).

6. Creation of a "dynamic linnk" for the retrun to the list

• The destination page is the lsit page,
• The web action has the following code ABLKRESTOREMAINCTX
  Restores the context of the main section.

7. Creation of the web page which displays the details

• Creation of the HTLM to display the details.

<!--Detail section-->
<!adx="BLKDETAIL">
    <b>Code    </b><span adx="CODE"></span><br>
    <b>Label </b><span adx="DESCR"></span><br>
    <b>Price    </b><span adx="PRIX"></span><br>
    <b>Stock    </b><span adx="STOCK"></span><br>
<!adx="BLKDETAIL">
<!--Back to the list-->
<a adx="DLKRETOURLISTE">back to list</a>

To display further data coming from another table or view (a rich description of an item or associated products, for instance):

• Create entities and sections that list these entities by passing BLKDETAIL.CODE (detail entity code) on to the selection criteria.

Return to previous page

ADLKRETURN dynamic link is used to return back to XTEND pages that have been viewed.

• operates better than 'Back' or 'Move Back to previous page' button of the browser
• does not take into account dynamic links that remain on the same page

For example:

If a product catalogue is paged, ADLKRETURN (link) will display the page that was before the display of the catalogue and will not take into account paging actions as the browser "Back" button.

The XTEND engine manages a stack of pages viewed by user session which size can be determined via the configuration setup:
xtend.server.gensetup.misc.rtnstacksize (20 by default).

Predefined links

Prerequisites

Refer to documentation Implementation

Screen management

Header

Tab General

Tab Advanced

Tab Selection

Tab Sort

Reports

By default, the following reports are associated with this function :

 PRTSCR : Screen print

This can be changed using a different setup.

Specific Buttons

Advanced use

JavaScript xtdDoDlk function

A dynamic link token is always inserted as attribute of an HTML tag <a> or <input type='button'>.

When the XTEND server dynamically builds the HTML page : it calls a JavaScript function from XTEND (stdDoDIk) library on the event onClick, at the level o the dynamic link tokens.

Setup from the function xtdDoDlk are contextual and will be used by the XTEND library to constitute data (xml) to send to the XTEND server in order to process the action and the selection.

<a  href="javascript:xtdDoSubmit('MYDLK',null);"
onclick="xtdDoDlk(this,'MYDLK',null,null,'XAA',0,null,event,false,'_1',false,null,false);">

<input type="button"
onclick="xtdDoDlk(this,'MYDLK',null,'MYBLOCK','XA',0,null,event,true,'',false,null,true);"
value="Add to cart"/>

Data context

When the user clicks on a dynamic link, the data context of the page does not exist anymore on the server.
It existed at the time of page construction and was then deleted.

The XTEND server stores in the HTML page (see <span id="xtdctx"> tag) the data context necessary to the process after selections and actions of dynamic links.

One of the roles of the JavaScript xtdDoDlk function is to find the data context associated to the dynamic link in order to send it again to the server.

For example:

The user wants to display the object (item/product) which has been clicked on in the detail page for a list/detail link. For the XTEND server, this operation consists in:

• memorizing selection criteria values for each line of the catalogue (here, the product code but there can be several) in order to pass them on to the section that display the details.

Storing the context in the HTML page ensures that XTEND functions correctly whilst using the "Back" button of the browser.

Call to a link by program

To call a dynamic link by JavaScript program (not managed by XTEND), use the following function:

//aElmt is the DOM element which has been clicked
//aDlk is the code of the dynamic link to call
//aParams is optional and contains the setups of the url (query string)
function xtdCallDlk(aElmt,aDlk,aParams){}

 This function can be used only if the dynamic link has no reference to XTEND fields in the selection criteria or action setups.

Only "Web field' criteria or setups are taken into account.

How to intercept the mouse click

In some case, the developer might have to intercept the click in order to process controls.

Declare a JavaScript function with the name xtdDoMyDlk so that the library (XtendLib.js) calls it by passing the contextual object on to aDomOut (CXtdDomOut class) which is used to access all information on the dynamic link.

This function returns "false" in order to interrupt the process.

function xtdDoMyDlk(aDomOut)
{      
     if (aDomOut.isDlk("MyDynLink"))
     {
         // The user has clicked on MyDynLink
         return confirm("Confirm action"); 
     }
     return true;
}

The user can also intercept the process just before the form is sent to the server (submit) by creating a JavaScript function xDoMySubmit in the page:

function xDoMySubmit(aDlk,aDomOut){
    // Returns false to stop the process
    return true;
}

CXtdDomOut class

aDomOut class setup which gives access to the context of the dynamic link.

// Returns the value of user variable aKey
aDomOut.getUserVar(aKey);
// Returns the dynamic link code which the user has clicked on
aDomOut.getDynLinkId();
// Returns the index of the line (0 to N) if the user has clicked
// on a link in the table section'
aDomOut.getCurLineIdx();
// Returns True if the user has clicked on aArg link
// aArg is either a link table or a string
aDomOut.isDlk(aArg);
    if (aDomOut.isDlk("DLK1","DLK2")){
        // Code if the user has clicked on "DLK1" or "DLK2"
    }
// Returns the list of WWeb parameters (Class CXtdDlkWebParamsOut)
aDomOut.getWebParameters();
// to know the value of the Web parameter aName
// aldx is the index of the value if the value is multiple
aDomOut.getWebParameters().getParamValue(aName,aIdx)
// Returns an Array containing the values of the Web parameter aName
aDomOut.getWebParameters().getParamValues(aName)
// Returns the value of a selection criteria or an action setup
// aFieldName is the name of the XTEND field used for mapping
aDomOut.getDlkParamValues(aFieldName);
// Ditto getDlkParamValues - aParamId is the ID of the parameter in the mapping
// - For selection criteria, the ID is SEL + criteria rank (1-N)
// - This is more accurate than getDlkParamValues as the ID contrary to the name of the XTEND field
aDomOut.getDlkParamValuesById(aParamId);

How to add entry controls

When an action setup is declared as "Mandatory web field", the library automatically controls:

• the entry of a value,
• the type for numerical and date fields.

To add additional control on web setups, add the following xtdWebParamCheckValue function in the HTML page.

This function is called for each web setup of the action associated with the dynamic link and returns "true" in order to validate the entry.

See the example in form entry of ASMAPLE site.

tdWebParamCheckValue function

Setups:

• aWebParamOut is the object which represents the setup
  See CXtdDlkWebParamOut class
• aInputFieldName is the name of the web field
  Name attribute
• aInputFieldIndex is the index of the field in the form
  0 if only one field has the name aInputFieldName
• aInputFieldValue is the setup value for the aInputFieldIndex index

function xtdWebParamCheckValue(aWebParamOut,aInputFieldName,
                               aInputFieldIndex,aInputFieldValue){
    // Example: Control of email format on MAICOD field
    if (aInputFieldName=="MAICOD"){
        var wEmail=xtdCheckEmail(aInputFieldValue);
        if (wEmail && wEmail!=aInputFieldValue){
            //Format OK
            //The value is updated with the format calculated by xtdCheckEmail
            aWebParamOut.setValue(aInputFieldIndex,wEmail);
        }
        //True to validate the entry - False to make it invalid
        return wEmail!=null;
    }
}

Class CXtdDlkWebParamOut

// Returns True if the parameter is mandatory
aWebParamOut.isMandatory();
// Returns the Index of the field in the HTML form
// -> There can be several fields with the same name in the form (table)
aWebParamOut.getIndex();
// Returns DOM element
aWebParamOut.getElement(aIdx)
//aValue is an Array
aWebParamOut.setValues(aValue);
//aIdx is the index (0 - N) of the value
aWebParamOut.setValue(aIdx,aValue);
// Returns te value of another Web parameter
// -> useful i the control of a parameter value depends from other parameters
aWebParamOut.getParamValue(aName,aIdx);
// Returns the value in an Array
aWebParamOut.getValues();
// Returns aldx as index value
aWebParamOut.getValue(aIdx);
// Returns 0 as index value
aWebParamOut.getFirstValue();
// Returns name attribute
aWebParamOut.getName();
// Returns the type of parameter defined in XTEND dictionary
aWebParamOut.isInteger();
aWebParamOut.isX3Menu();
aWebParamOut.isDecimal();
aWebParamOut.isCurrency();
aWebParamOut.isDate();
aWebParamOut.isString();
aWebParamOut.isNumeric();
// Returns the type of element of the parameter DOM
aWebParamOut.isHidden(aIdx);
aWebParamOut.isInputText(aIdx);
aWebParamOut.isCheckBox(aIdx);
aWebParamOut.isRadio(aIdx);
aWebParamOut.isTextArea(aIdx);
aWebParamOut.isSelect(aIdx);

Filter setups to control

If the xtdWebParamCheck function is displayed in the page, the XTEND library calls this function before carrying out the setup control.

This function returns "true" to control the value and false to block the control.

It is particularly useful in the picking lists with line selection by a check box. It is used to filter lines in order to process to the control only on lines that are checked.

See the example in form entry of ASMAPLE site.

xtdWebParamCheck function

Setups:

• aWebParamOut is the object which represents the setup
  See CXtdDlkWebParamOut class
• aInputFieldName is the name of the web field
  Name attribute
• aInputFieldIndex is the index of the field in the form
  0 if only one field has the name aInputFieldName

var gNbChecked=0;
// Returns true if the web setup aInputFieldName/aInputFieldIndex must be controlled
function xtdWebParamCheck(aWebParamsOut,aInputFieldName,aInputFieldIndex){
/*
    Example for a picking list with checkboxes (ASELECTED) to select lines.
    here is no control on the AQUANTITY field if the line is not selected
*/
    if (aInputFieldName=="AQUANTITY"){
        // gNbChecked is a counter of the selected lines
        // it enables the user to block the action if no line is selected
        if (aInputFieldIndex==0) gNbChecked=0;
        // Line selected if ASELECTED value is equal to 1
        if (aWebParamsOut.getParamValue("ASELECTED",aInputFieldIndex)=="1"){
            gNbChecked++;
            return true;
        }
        return false;
    }
    return true;
}

Particularities of checkboxes

Checkboxes are not returned in the HTML form if they are not checked.

This behaviour is not compatible with the XTEND engine which bases itself on the field index in the HTML form in order to associate data entered in the same grid line.

XTEND replaces unchecked CheckBoxes by an "input hidden" field bearing the same name just before sending the form to the server (xtdProcessCheckBoxes) so that CheckBoxes can still be returned even if they are not checked in the library.

The value used to valuate unchecked CheckBoxes is given by the global variable gXtdCBUnSelelectedValue which is empty by default (var gXtdCBUnSelelectedValue="").

To modify its value:

• Call xtdSetUnSelelectedValue function with the chosen value, for instance on the onLoad event of the page.

<script>
    // Page onLoad event
    function xBodyOnLoad()
    {
        // Set '0' value for unselected checkboxes
        xtdSetUnSelelectedValue('0');
        // Page initialization code
    }
</script>
<body onLoad="xBodyOnLoad();">
    <form>
        //Html code
    </form>
</body>

 Upon parsing, XTEND detect all CheckBoxes that have an adx token and constitute a list which is sent to the customer in the data context of the page. CheckBoxes of this list are taken into account by the xtdProcessCheckBoxes function.

Access "Regional settings"

The XTEND server sends the information on "Regional Settings" that correspond to the current language to the browser in the data context of the page.

To access these information:

• Use the following function which sends an object which class is CXtdRegionalSettings.

var wRegSettings=gXtdDOMFactory.getXtdDomIn().getRegionalSettings();

Class CXtdRegionalSettings methods

// Decimal separator
wRegSettings.getDecimalSep();
// Thousand separator
wRegSettings.getThousandSep();   
// Date order - MDY=0 - DMY=1 - YMD=2
wRegSettings.getDateOrder();
// Pivot date to calculate X3 dates
wRegSettings.getDatePivot();

Add/Delete variables and user criteria

The following functions are used to add/delete variables and user criteria.

xtdAjax* functions update variables on the server via an Ajax request, without submitting the HTML form.

Other functions (except xtdGetUserVar) submit the HTML form.

// ---------------------------------------------------------------
function xtdRemoveUserVar(aId);
function xtdSetUserVar(aId,aValue);
function xtdGetUserVar(aId);
function xtdRemoveUserCrit(aId);
// ---------------------------------------------------------------
function xtdAjaxRemoveUserVar(aId);
function xtdAjaxRemoveAllUserVar();
function xtdAjaxSetUserVar(aId,aValue);
function xtdAjaxRemoveUserCrit(aId);
function xtdAjaxRemoveAllUserCrit();
function xtdAjaxSetUserCrit(aId,aValue);
function xtdRemoveAllUserCrit();

Display a message coming from the XTEND server

The following function displays a message calculated by the XTEND server.
The message is returned in the current language of the site.

Setups:

• aId is the code for the XTEND message,
• aP1,aP2.. are (optional) setups.

function xtdAlert(aId,aP1,aP2,aP3,aP4);
// The following example displays
// 'You are connected to the application with DIS001 use code'
xtdAlert("ASESSLOGIN2","DIS001");

Access the call context of the page

The following class give access to the call context of the page in order to know the result of an action:

var wCallCtx==gXtdDOMFactory.getXtdDomIn().getCallingCtx();
// ---------------------------------------------------------------
// CLASS CXtdCallingCtx
// ---------------------------------------------------------------
// Dynamic link used to display the current page
wCallCtx.getDynLink();
// True si la page est le résultat d'une action
wCallCtx.hasAction();
// Action code
wCallCtx.getAction();
// True if the action occurred accurately - False it there is an error
wCallCtx.getActionResult();

Error messages

The only error messages are the generic ones.

Tables used

Refer to documentation Implementation