[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' scope

insecure 'abc' = 123_insecure - using reserved 'insecure' name
insecure 'abc'= 123_insecure - using 'step-wise' scope

local '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).