$Web Selp: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Web_Selp}}
{{DISPLAYTITLE:$Web_Selp}}
<span class="pageSubtitle"><section begin="desc" />Build select options from global select element, selected from parameters<section end="desc" /></span>
<span class="pageSubtitle">Build select options from global select element, selected from parameters</span>






$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]].  
<var>$Web_Selp</var> inserts into the Web output stream the options list of an HTML <code>select</code> element. The options list is taken from a global select element created by <var>[[$Web_Save_Sel]]</var>, 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* functions is provided in [[Janus Web Server $functions#$Web_Sel* functions|"$Web_Sel* functions"]].
 
<var>$Web_Selp</var> takes three arguments and returns a string; for some types of errors, the current <var class="product">User Language</var> request is cancelled. <var>$Web_Selp</var> is a [[Calling Sirius Mods $functions|callable]] $function.


$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|Calling Sirius Mods $functions]]).
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RC = $Web_Selp(global_name, param_name, option_keywords)
<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Web_Selp</span>(<span class="term">global_name</span>, [<span class="term">param_name</span>], [<span class="term">option_keywords</span>])
<section end="syntax" /></p>
</p>


<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%rc</th>
<td>A numeric variable to contain the [[#retcode|return code]].
<tr><th>global_name</th>
<tr><th>global_name</th>


 
<td>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 <var>[[$Web_Save_Sel]]</var>. This is a required argument.</td></tr>
<td>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.</td></tr>
<tr><th>param_name</th>
<tr><th>param_name</th>


<td>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 <code><select multiple></code> elements.
<p>
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 <code>option</code> elements in the list contain the <code>selected</code> attribute. As explained in [[Janus Web Server $functions#Drop-down lists: HTML <select>|"Drop-down lists: HTML &lt;select>"]], the default selected option depends on the type of <code>select</code> element: <code><select multiple></code> has no default; for non-multiple, the first item in the options list is the default <code>selected</code> element.</p></td></tr>


<td>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.</td></tr>
<tr><th>option_keywords</th>
<tr><th>option_keywords</th>


<td>This optional argument is a string of blank-separated keywords specifying special processing for this $function; it can contain any of the following:
<table class="syntaxTable">
<table class="syntaxTable">
<td>A string of blank-separated keywords specifying special processing for this $function; it can contain any of the following:</td></tr>
<tr><th><var>NOCAN</var></th>
<tr><th>NOCAN</th>
<td>Don't cancel request if global select element <var class="term">global_name</var> not found</td></tr>
<td>Don't cancel request if global select element ''global_name'' not found</td></tr>
<tr><th><var>NOFORM</var></th>
<tr><th>NOFORM</th>
<td>Don't look in form parameters</td></tr>
<td>Don't look in form parameters</td></tr>
<tr><th>NOISINDEX</th>
<tr><th><var>NOISINDEX</var></th>
<td>Don't look in isindex parameters</td></tr>
<td>Don't look in isindex parameters</td></tr>
<tr><th>NOISI</th>
<tr><th><var>NOISI</var></th>
<td>Synonym for NOISINDEX</td></tr>
<td>Synonym for <var>NOISINDEX</var></td></tr>
<tr><th>NOENDSEL</th>
<tr><th><var>NOENDSEL</var></th>
<td>Don't end list of options with </select></td></tr>
<td>Don't end list of options with <code></select></code></td></tr>
<tr><th>NOENDS</th>
<tr><th><var>NOENDS</var></th>
<td>Synonym for NOENDSEL</td></tr>
<td>Synonym for NOENDSEL</td></tr>
<tr><th>ENDOPT</th>
<tr><th><var>ENDOPT</var></th>
<td>End each option with </option>
<td>End each option with <code></option></code>
</td></tr></table>
</td></tr></table>


</td></tr></table>


This an optional argument.
<div id="retcode"></div>
</td></tr></table>
These are the <var>$Web_Selp</var> return values:


<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>Code</th>
<tr><th>Code</th>
<td>Meaning</td></tr>
<th>Meaning</th></tr>
<tr><th>null</th>
<tr><th>null</th>
<td>The operation completed successfully.</td></tr>
<td>The operation completed successfully.</td></tr>
<tr><th>"1"</th>
<tr><th>"1"</th>
<td>''Global_name'' not a saved global select element, and NOCAN option</td>
<td><var class="term">global_name</var> not a saved global select element, and <var>NOCAN</var> option specified.</td>
specified.<tr><th></th>
<tr><th></th>
<td>Any other error results in cancellation of the User Language request.</td></tr>
<td>Any other error results in cancellation of the <var class="product">User Language</var> request.</td></tr>


</table>
</table>
<p class="caption">$WEB_SELP return values</p>
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:
<p class="code"> 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
...
</p>
$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:
<p class="code"> 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
</p>
You can use this procedure at the start of the online:
<p class="code"> //CCAIN ...
...
BEGIN
IN META FR WHERE TYPE=LANG
CALL GEN_DAYS(LANG, %RC)
END FOR
INCLUDE GEN_DAYS
END
</p>
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, <tt>DN</tt>) 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:
<p class="code"> 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><br>'
%RC = $Web_Selp('DAYS.' WITH %LANG, 'DN')
PRINT '<input type=submit><br>'
PRINT '</form>'
END
</p>
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:
<p class="code"> 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><br>'
%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><br>'
PRINT '</form>'
INCLUDE GEN_DAYS
END
</p>
If you want to remove a language from further processing, you can call $Web_Del_Sel:
<p class="code"> B
%RC = $Web_Del_Sel('DAYS.ESPERANTO')
END
</p>
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:
<ul>
<li>Set a default language (with $Web_Set_Cookie)
<li>Use $Web_Selp_Check to ensure that the user's form parameter <tt>DN</tt> (which, remember, will contain the language-independent values DN0, DN1, etc.) is within the range of the default language. If <tt>DN</tt> is outside that range, $Web_Sel is used so that the pre-selected day is the "hand-coded" DN3.
</ul>
<p class="code"> 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><br>'
%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><br>'
PRINT '</form>'
INCLUDE GEN_DAYS
END
</p>


See [[$Web_Sel* example|"$Web_Sel* example"]] for an extended example which includes use of <var>$Web_Selp</var>.


[[Category:Janus Web Server $functions|$Web_Selp]]
[[Category:Janus Web Server $functions|$Web_Selp]]

Latest revision as of 21:45, 5 June 2013

Build select options from global select element, selected from parameters


$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* functions is provided in "$Web_Sel* functions".

$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.

Syntax

%rc = $Web_Selp(global_name, [param_name], [option_keywords])

%rc A numeric variable to contain the return code.
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 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 "Drop-down lists: HTML <select>", the default selected option depends on the type of select element: <select multiple> has no default; for non-multiple, the first item in the options list is the default selected element.

option_keywords This optional argument is 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>

These are the $Web_Selp return values:

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

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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$Web_Selp&oldid=60226"