[function] This context enables the WebDNA programmer to call a previously defined block of WebDNA code. Functions allow you to create your own tags to use just as you would any other predefined WebDNA tag. A function will override a native WebDNA tag, so you could, for instance, redefine the date and time tags to match a different time zone, if your server is not local to you. A function is a handy way to perform a complicated series of instructions so you need only maintain one piece of code, but use it a number of times in your page.

Example WebDNA code:

[function name=citytime]
[format seconds_to_time %I:%M %p][math]{[time]}+{[more]:00:00}-{[less]:00:00}[/math][/format]
[/function]

<b>Current time around the world</b>
[citytime more=0&less=0] - New York City<br>
[citytime more=0&less=3] - Seattle<br>
[citytime more=7&less=0] - Paris

In this example, we feed the function two variables, [more] and [less]. The code within the page is clean and clear, and we use only one function to return multiple values. If we decide to change the way the times are formatted, we only need to change the single chunk of code. (The server in the example is in New York City, so we define [more] and [less] relative to the server time.)

name

User defined name for the function. The name is then used like any other WebDNA tag, as in our example.

preparse

T/F Optional. By default, the WebDNA code that makes up the function is stored 'raw' and executed later when the function is called, as in our citytime example above, because the variables are, well, variable. But if you need to use WebDNA to create the function in the first place, then you can set 'preparse' to 'T'. This will force the WebDNA engine to first parse the WebDNA in the function definition before storing it for later use. Usage: [function name=somename&preparse=t]

This new example creates a function named 'backwards' that will take a variable named 'instring' and display the characters of the string in reverse order. We use the following code...

[function name=Backwards]
[text]length=[countchars][instring][/countchars][/text]
[loop start=[length]&end=1&advance=-1][getchars start=[index]&end=[index]][instring][/getchars][/loop]
[/function]

Now the function is defined and stored for later use in the template.
To execute the new function, we use...

[Backwards instring=abcdef_12345]

The power of [function]

Using the [function ][/function] context, one can extend WebDNA's power to near limitless potential.

A "Function" could be something as simple as outputing static info:

[!] ** create primary numbers function ** [/!]
[function name=PrimeNums]
[return]2,3,5,7,11,13,17,19,23,29[/return][/function]

then

[!] ** Display primary numbers function ** [/!]
[PrimeNums]

Or, a function could be a something more logical.
For example, have the option of returning a random prime number:

[!] ** create primary numbers function ** [/!]
[!] ** adding a param called fmode ** [/!]
[function name=PrimeNums]
[!] ** table of primes (could be a .db file, or MySQL database as well) ** [/!]
[table name=primes&fields=pnum]
2
3
5
7
11
13
17
19
23
29
[/table]
  [switch value=[fmode]]
    [case value=random]
      [search table=primes&[!]
        [/!]nePNUMdatarq=find_all&[!]
        [/!]raPNUMsort=1&[!]
        [/!]PNUMtype=num[!]
        [/!]&max=1]

        [return][founditems][PNUM][/founditems][/return]
      [/search]
    [/case]
    [default]
      [!] ** find all primes ** [/!]
      [search table=primes&nePNUMdatarq=find_all]
        [return][founditems][PNUM],[/founditems][/return]
      [/search]
    [/default]
  [/switch]
[/function]

Now, from the above, you can call this function with either:

[!] ** Find all Prime Numbers ** [/!]
[PrimeNums]

or:

[!] ** Find a random prime number ** [/!]
[PrimeNums fmode=random]

The above is untested, but you get the idea! Create a WebDNA Lab (in the admin prefs of WebDNA) to find a great tutorial on the [function][/function] context. There are many other great ways to use it.

What is a Function Library?:
Libraries are usually a collection of functions that may have a themed purpose. A library theme could be as focused as, for example, functions to deal with image manipulation, or as loosely focused, for example, as "Donovan's commonly used functions". However, the idea is that you end up with a library that can be easily "loaded" into your site for extensible use with your WebDNA site. This is the open source and limitless area of WebDNA. Anyone can create and share a function library.

What format is a function library?:
There are a couple/few "formats" that could be created for your library.. but the traditional method is the best. This method is a simple text file with a specific ending suffix such as: "mylibrary.dnalib" or "mylibrary.inc"

if you use a custom suffix such as "dnalib", you should add this mapping within your WebDNA prefs so that WebDNA knows to process this file type. First, find your "WebCatalogEngine" directory and edit the file "webdna.conf" so that "dnalib" is added along with all the other mappings (towards the end of the file). Then, in your admin prefs, add .dnalib as an allowable suffix. (you can avoid the extra mapping stuff by using ".inc"

So, a very small sample function library might look like:
mylibrary.inc

[!] ** donovan's sample library ** 
    ** File: mylibrary.inc ** 

    ** created Mar 23 2009 **
    ** function prefix convention "ml_"
[/!][!] 

    ** NAME: "ml_list"
    ** DESCRIPTION: Returns a list of available functions in this library ** 
    ** INPUT: none
    ** OUTPUT: List of function names

[/!][function name=ml_list]
[return]Ml_List,Ml_PrimNums[/return]
[/function][!]

    ** NAME: "ML_PrimeNums"
    ** DESCRIPTION: Library for dealing with Prime Numbers ** 
    ** INPUT: "fmode"
               params:
                 "random"
               (leave blank to find all prime numbers)
    ** OUTPUT: Prime Numbers

[/!][function name=Ml_PrimeNums]
[!] ** table of primes (could be a .db file, or MySQL database as well) ** [/!]
[table name=primes&fields=pnum]
2
3
5
7
11
13
17
19
23
29
[/table]
  [switch value=[fmode]]
    [case value=random]
      [search table=primes&[!]
        [/!]nePNUMdatarq=find_all&[!]
        [/!]raPNUMsort=1&[!]
        [/!]PNUMtype=num[!]
        [/!]&max=1]

        [return][founditems][PNUM][/founditems][/return]
      [/search]
    [/case]
    [default]
      [!] ** find all primes ** [/!]
      [search table=primes&nePNUMdatarq=find_all]
        [return][founditems][PNUM],[/founditems][/return]
      [/search]
    [/default]
  [/switch]
[/function]

(again, the above is untested and is just to give you an idea of the format of things)

How To Load a Function Library:
There are several ways to load a library, but the two best ways are to simply it include it on the page where you want to use it:

[include file=mylibrary.inc]

Or, you can drop the file in your "Globals/FunctionDefs/" directory, and then turn on your "pre-parse" function within the WebDNA Preferences, to have your library of functions available to you on all your sites and pages at all times!

With the module version of WebDNA, the Globals directory is in your "WebCatalogEngine" directory.. however, if you want access to your library from within a WebDNA Sandbox, you will have to find the "Globals" directory for that particular sandbox. By default, this would be "WebCatalogEngine/SandBoxes//Globals"

Then, call your functions!:

[!] List of available functions in mylibrary.inc [/!]
[Ml_list]

[!] List all prime numbers [/!]
[Ml_PrimeNums]

Happy function library creating!