[return]<webdna>[/return]

The textual output generated as a result of a WebDNA function call includes whatever text remains after the function code is executed. This may include unwanted spaces, carriage returns, and other 'white space' characters. The [return] context can be used to explicitly identify what text is returned from the function call, thereby avoiding unwanted characters.

The [return] context is optional and can only be used from within the [Function] context. The [return] context does NOT 'break out' of a function call, so it is possible to use one or more [return] contexts to 'tailor' the functions output.

Example without [return]

Below is a simple function that does not include a [return] context. This function simply adds the first ten positive numbers. We will execute the function, then wrap the execution in [url][/url] tags to 'reveal' the extra white space that can accumulate from a function call (much as it would when using the WebDNA [include] tag.)

Here is the code:

[function name=add_em_up]
[text]result=0[/text]
[loop start=1&end=10]
[text]result=[math][result]+[index][/math][/text]
[/loop]
[result]
[/function]

Executing the function, we get: " 55 "

Now, lets 'wrap' the function result with the [url] context to uncover the 'extra' stuff we accumulated a result of the function call.
Here is the result:

"%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A55%0D%0A"

Note all the extra white space, in this case, carriage returns and line feeds.

The 'old' Solution

One way that WebDNA programmers have dealt with unwanted return characters, is to wrap line-endings, or other unwanted white space, with WebDNA comments, i.e. [!]...[/!]. So the function definition on the previous page would look like...

[function name=add_em_up][!]
[/!][text]result=0[/text][!]
[/!][loop start=1&end=10][!]
[/!][text]result=[math][result]+[index][/math][/text][!]
[/!][/loop][!]
[/!][result][!]
[/!][/function]

Executing the above function, and wrapping the result with URL tags, we get: "55"

The extra 'garbage' is gone, but using all those [!][/!] pairs is cumbersome, and does add some extra parsing overhead.

A Better Solution

The [return] context can now be used to target exactly what we want the function to return. So our example function now looks like...

[function name=add_em_up]
[text]result=0[/text]
[loop start=1&end=10]
[text]result=[math][result]+[index][/math][/text]
[/loop]
[return][result][/return]
[/function]

"[url][add_em_up][/url]"

Executing the above code, we get: "55"

The extra 'garbage' is gone, and we did not have to use all those [!][/!] contexts.

Even if the explicit results of a function call are not significant, for example, when the function assigns the result to some global text variable. It is still a good idea to use the [return] context in order to cut down on the amount of white space that my be returned to the client browser.

For example:

[function name=add_em_up]
[text]result=0[/text]
[loop start=1&end=10]
[text]result=[math][result]+[index][/math][/text]
[/loop]
[text scope=global]result=[result][/text]
[return][/return] [!] return nothing [/!]
[/function]

[add_em_up]
result="[result]"

Executing the above code, we get:

result="55"

As mentioned in the first page of this tutorial, the [return] context does not actually 'return' or 'break out' of the function call. So, it is possible to have multiple [return] contexts in a given function definition. For example:

[function name=add_em_up]
[text]result=0[/text]
[loop start=1&end=10]
[text]result=[math][result]+[index][/math][/text]
[showif [index]
Results in...
"1+2+3+4+5+6+7+8+9+10=55"

The [return] context is also very useful when creating 'recursive' functions (functions that call them selves until a terminating 'base case' is reached).

Here is a sample recursive function that calculates the factorial for a given integer.

[function name=factorial]
[showif [num]>1]
[return][math][num]*[factorial num=[math][num]-1[/math]][/math][/return]
[/showif]
[hideif [num]>1]
[return]1[/return]
[/hideif]
[/function]

6! = [factorial num=6]

The results...

6! = 720