[scope name=...]<WebDNA>[/scope]
Enables a WebDNA programmer to explicitly define a block of WebDNA code that has a separate variable space. Meaning that variables defined within the 'scope', only exist for the duration of WebDNA between the 'scope' tags.
Optional Tag Parameters:
· name - User defined name for the local variable space.
This name can be used with the scope resolution operator to 'access' variables
stored in the 'named' variables space (but only for the duration of the scope
context).
Named Scope
Lets create a named variable space called 'mytempvars', and create a few text
variables in the new scope.
We use the following code...
-Scope begin...[scope name=mytempvars]
[text]a=11[/text]
[text]b=22[/text]
[text]c=33[/text]
List of local scope variables...[listvariables scope=mytempvars][name]=[value]
[/listvariables]
-Scope end...[/scope]
List of global variables...
[listvariables][name]=[value]
[/listvariables]
Result...
-Scope begin...
List of local scope variables...
a=11
b=22
c=33
-Scope end...
List of global variables...
page_number=2
page_name=Scope
edit_link=Scope/Scope_-_---2---.tpl
back_link=Scope_-_---1---.tpl
next_link=Scope_-_---3---.tpl
new_file=Scope/Scope_-_---3---.tpl
main_title=Scope
So you can see that the 'local' scope variables; 'a','b', & 'c', only exist
between the [scope] tags.
This is useful when you need to create several temporary variables for a specific
block of WebDNA code, but do not want the variables 'cluttering' the global
template variable space.
Scope and Functions
WebDNA functions have their own implied scope. Meaning that when you create
variables inside of a function definition, the variables are local to that function.
The 'name' of the variable space in the function, is the function name itself.
For example...
[function name=test_function]
[loop start=1&end=10]
[text]local_[index]=[index][/text]
[/loop]
[listvariables scope=test_function][name]=[value]
[/listvariables]
[/function][test_function]
Results...
local_1=1
local_2=2
local_3=3
local_4=4
local_5=5
local_6=6
local_7=7
local_8=8
local_9=9
local_10=10
Scope Resolution - Step-Wise Method
Because of the addition of 'local' variable name spaces to WebDNA, there will
often be occasions when you need to explicitly access variables in a given scope.
You can do this using the new 'Scope Resolution' operator: '::'. There are two
modes of Scope resolution; 'step-wise' and 'named'.
When parsing WebDNA code, the WebDNA engine will search 'inside-out' for variable
matches on a given token, and return the first 'match'. The step-wise scope
resolution method can force the engine to 'step over' matching variable names
and continue searching for 'outer' variables that match the given token.
This 'step-wise' scope resolution is used as follows...
Any number of 'colon' pairs preceding a variable name.
[::]
A usage case...
Often from within an [orderfile] context, you may want to access the global
[date] tag. Until now, if you used [date] from within an orderfile context (or
on a page called with the 'showcart' command), you would get the orderfile's
date, and not the 'global' date value. Now, you can retrieve the 'global' date
value using, [::date] from within the orderfile context. Basically the '::'
reads as, 'skip the first occurrence of a 'date' value, and retrieve the next
(if it exists).'
[orderfile file=testcart]
[date][::date]
[/orderfile]
Results...
1/01/2001
03/04/2003
You can 'stack' any number of resolution operator '::' pairs to 'skip' to a particular 'outer' instance of a variable...
[scope name=scope1]
[text]a=1[text]
[scope name=scope2]
[text]a=11[text]
[scope name=scope3]
[text]a=111[text]
value of 'a' in [scope3] = [a]value of 'a' in [scope2] = [::a]
value of 'a' in [scope1] = [::::a]
[/scope]
[/scope]
[/scope]
Results...
value of 'a' in [scope3] = 111
value of 'a' in [scope2] = 11
value of 'a' in [scope1] = 1
Scope Resolution - Named Method
You can directly refer to a particular scope using the scope name between the
':' colons. The 'name' must be qualified by 'named-', i.e.
[:named-:]
'Reserved' scope names can also be used. In this case you do not need to include
the 'named-' prefix, i.e.
[:global:]
Reserved scope names are discussed on the following page.
Using the orderfile example from the previous page...
[orderfile file=testcart]
[date][:global:date]
[/orderfile]
Results...
1/01/2001
03/04/2003
The 'global' name is the reserved scope name for secure template variables.
Using the nested scopes example from the previous page...
[scope name=scope1]
[text]a=1[text]
[scope name=scope2]
[text]a=11[text]
[scope name=scope3]
[text]a=111[text]
value of 'a' in [scope3] = [:named-scope3:a]value of 'a' in [scope2] = [:named-scope2:a]
value of 'a' in [scope1] = [:named-scope1:a]
[/scope]
[/scope]
[/scope]
Results...
value of 'a' in [scope3] = 111
value of 'a' in [scope2] = 11
value of 'a' in [scope1] = 1
Reserved Scope Names
There are a few 'reserved' scope names:
'global' - refers to the 'normal/secure' template variable space.
'local' - When used inside of a function or scope context, refers to the variable
space associated with the current function or scope.
'insecure' - Refers to the 'insecure' template variable space (this space also
includes HTML form variables).
A demonstration of named and step-wise scope resolution...
[text]abc=123_global[/text]
[text insecure=F]abc=123_insecure[/text][scope name=scope1]
[text]abc=123_local[/text]global 'abc' = [:global:abc] - using reserved 'global' name
global 'abc' = [::abc] - using 'step-wise' scope
insecure 'abc' = [:insecure:abc] - using reserved 'insecure' name
insecure 'abc'= [::::abc] - using 'step-wise' scope
local 'abc' = [:local:abc] - using reserved 'local' name
local 'abc' = [abc] - using implied scope
local 'abc' = [:named-scope1:abc] - using 'named' scope
[/scope]
Results...
global 'abc' = 123_global - using reserved 'global' name
global 'abc' = 123_global - using 'step-wise' scopeinsecure 'abc' = 123_insecure - using reserved 'insecure' name
insecure 'abc'= 123_insecure - using 'step-wise' scopelocal 'abc' = 123_local - using reserved 'local' name
local 'abc' = 123_local - using implied scope
local 'abc' = 123_local - using 'named' scope
New 'scope=' parameter
Besides being able to 'resolve' variables in different scopes, you can create
variables for a specified scope using the 'scope=' parameter in [text] and [math]
assignments. This option will soon be available for other persisted WebDNA object,
i.e. Arrays, Tables, XML/XSL objects, etc.
This is useful when you have a block of WebDNA code within a function, or named
scope, and need to create/modify a variable in an outer scope.
For example...
Here we simulate a 'pass by reference' by passing the variable name, to receive
the results, into a function call.
[function name=Backwards]
[text]length=[countchars][in_string][/countchars][/text]
[text scope=global][output_to]=[loop start=[length]&end=1&advance=-1][getchars start=[index]&end=[index]][in_string][/getchars][/loop][/text]
[/function][Backwards in_string=abcdef_12345&output_to=result]
result = [result]
Results...
result = 54321_fedcba
In the example above, the function definition assumes that the destination variable existed in the 'global' scope. Lets do the same thing as before, but pass in the scope name as well...
[function name=Backwards]
[text]length=[countchars][in_string][/countchars][/text]
[text scope=[output_scope]][output_to]=[loop start=[length]&end=1&advance=-1][getchars start=[index]&end=[index]][in_string][/getchars][/loop][/text]
[/function][!] clear out global 'result' from previous example [/!]
[text]result=[/text]
[scope name=scope1]
[Backwards in_string=abcdef_12345&output_to=result&output_scope=scope1]
value of 'result' inside of 'scope1' = '[result]'
[/scope]
value of 'result' outside 'scope1' = '[result]' (should be empty).
Results...
value of 'result' inside of 'scope1' = '54321_fedcba'
value of 'result' outside 'scope1' = '' (should be empty).