$Web_Selp

From m204wiki
Revision as of 01:39, 16 September 2011 by JAL2 (talk | contribs)
Jump to navigation Jump to search

<section begin="desc" />Build select options from global select element, selected from parameters<section end="desc" />


$Web_Selp inserts into the Web output stream the options list of an HTML<select> element. The options list is taken from a global select element created by $WEB_SAVE_SEL, and the selected options (that is, the ones that are highlighted on the HTML page) are identified by values of a form and/or isindex parameter in the current web request. An overview of the $WEB_SEL_x functions is provided in $Web_Selp.

$Web_Selp takes three arguments and returns a string; for some types of errors, the current User Language request is cancelled. $Web_Selp is a callable $function (see Calling Sirius Mods $functions).

Syntax

<section begin="syntax" /> %RC = $Web_Selp(global_name, param_name, option_keywords) <section end="syntax" />



global_name The name of the global select element containing the values and descriptions for the options list. The global select element with this name must have been created by $Web_Save_Sel. This is a required argument.
param_name The name of a form and/or an index parameter in the current web request. For each occurrence of this parameter, if it has a value that is equal to the value of an item in the options list, that option element is selected in the displayed options list. This allows multiple items to be selected, which is useful for <select&thinsp.multiple> elements. This an optional argument. If this argument is omitted, or if no occurrences of the parameter are equal to the value of any of the options in the global select element, then none of the <option> elements in the list contain the selected attribute. As explained in $Web_Selp, the default selected option depends on the type of <select> element: <select&thinsp.multiple> has no default; for non-multiple, the first item in the options list is the default selected element.
option_keywords
A string of blank-separated keywords specifying special processing for this $function; it can contain any of the following:
NOCAN Don't cancel request if global select element global_name not found
NOFORM Don't look in form parameters
NOISINDEX Don't look in isindex parameters
NOISI Synonym for NOISINDEX
NOENDSEL Don't end list of options with </select>
NOENDS Synonym for NOENDSEL
ENDOPT End each option with </option>


This an optional argument.

specified.
Code Meaning
null The operation completed successfully.
"1" Global_name not a saved global select element, and NOCAN option
Any other error results in cancellation of the User Language request.

$WEB_SELP return values


See $Web_Selp for an extended example which includes use of $Web_Selp.

$Web_Sel* example

This section demonstrates some of the concepts of the $WEB_SELx functions. The application is a simple form which lets the user select a day of the week. To show how this can exploit metadata, assume that you have a Model 204 file with the days of the week in several languages, and that you have saved the user's language in a cookie named LANG. Note that by giving values of 'DN0', 'DN1', etc., the code does not need to deal with the actual day names (the option descriptions).


Assume you have records like the following:

IN META STORE RECORD TYPE = LANG LANG = ENGLISH END STORE IN META STORE RECORD TYPE = DAY LANG = ENGLISH DAY = Sunday END STORE IN META STORE RECORD TYPE = DAY LANG = ENGLISH DAY = Monday END STORE ...


$Web_Save_Sel is used to save one global select element for each language. You can do this when you start the online, but a later example shows how a language can be dynamically added. Assume the following procedure:

SUBROUTINE GEN_DAYS(%LANG IS STRING LEN 20, - %NDAY IS FLOAT OUTPUT) %NDAY = 0 %L1 FLOAT %L2 FLOAT %X FLOAT %L1 = $ListNew %L2 = $ListNew IN META FR WHERE TYPE=DAY AND LANG=%LANG %X = $ListAdd(%L1, 'DAY' WITH %NDAY) %X = $ListAdd(%L2, DAY) %NDAY = %NDAY + 1 END FOR IF %NDAY THEN %X = $Web_Save_Sel('DAYS.' WITH %LANG, - %L1, %L2) END IF END SUBROUTINE

You can use this procedure at the start of the online:

//CCAIN ... ... BEGIN IN META FR WHERE TYPE=LANG CALL GEN_DAYS(LANG, %RC) END FOR INCLUDE GEN_DAYS END


You can use the global select elements to create a drop-down list in an HTML form. $Web_Selp is used with the same second argument (the parameter name, DN) as the name= attribute of the <select> element; this is how you can easily "pre-select" the same day chosen before when the form is redisplayed to the user:

B %LANG STRING LEN 20 %RC FLOAT %LANG = $Web_Cookie_Parm('LANG') PRINT '<form method=post action="' WITH - $Web_Hdr_Parm('URL') WITH '">' PRINT 'Select day: <select name=DN>
' %RC = $Web_Selp('DAYS.' WITH %LANG, 'DN') PRINT '<input type=submit>
' PRINT '</form>' END


This approach works fine, except that if a language is added while the online is running, a user who acquires this language in his or her cookie will have the User Language request cancelled, because $Web_Selp will not find the desired global select element. The following approach can be used to handle this situation when the web form is built. The NOCAN option of $Web_Selp is used to see if a new language is in use:

B %LANG STRING LEN 20 %RC FLOAT %LANG = $Web_Cookie_Parm('LANG') PRINT '<form method=post action="' WITH - $Web_Hdr_Parm('URL') WITH '">' PRINT 'Select day: <select name=DN>
' %RC = $Web_Selp('DAYS.' WITH %LANG, 'DN', - 'NOCAN') IF %RC NE 0 THEN CALL GEN_DAYS(%LANG, %RC) %RC = $Web_Selp('DAYS.' WITH %LANG, 'DN') END IF PRINT '<input type=submit>
' PRINT '</form>' INCLUDE GEN_DAYS END


If you want to remove a language from further processing, you can call $Web_Del_Sel:

B %RC = $Web_Del_Sel('DAYS.ESPERANTO') END

However, it is then possible that a "stale cookie" may be left around in a user's browser. In that case, you will want to set a default language, but if the deleted language was Romulac, and a day beyond the 7th had been selected, you might also want to force the pre-selected day to be the middle of the week. The following code contains changes that do the following:

  • Set a default language (with $Web_Set_Cookie)
  • Use $Web_Selp_Check to ensure that the user's form parameter DN (which, remember, will contain the language-independent values DN0, DN1, etc.) is within the range of the default language. If DN is outside that range, $Web_Sel is used so that the pre-selected day is the "hand-coded" DN3.

B %LANG STRING LEN 20 %RC FLOAT %LANG = $Web_Cookie_Parm('LANG') PRINT '<form method=post action="' WITH - $Web_Hdr_Parm('URL') WITH '">' PRINT 'Select day: <select name=DN>
' %RC = $Web_Selp('DAYS.' WITH %LANG, 'DN', - 'NOCAN') IF %RC NE 0 THEN CALL GEN_DAYS(%LANG, %RC) IF %RC NE 0 THEN %LANG = 'ENGLISH' %RC = $Web_Set_Cookie('LANG', 'ENGLISH') END IF %RC = $Web_Selp_Check('DAYS.' WITH %LANG, - 'DN') IF %RC NE 0 THEN %RC = $Web_Sel('DAYS.' WITH %LANG, 'DN3') ELSE %RC = $Web_Selp('DAYS.' WITH %LANG, 'DN') END IF END IF PRINT '<input type=submit>
' PRINT '</form>' INCLUDE GEN_DAYS END