Source: site.programming [edit]

Programming Collaborama

This page describes how to program new functions in Collaborama. Read the introductory help page first.

To develop with Collaborama, you simply create new or edit existing Collaborama functions. Before editing pages, you must signup for an account and log in.

Collaborama Modules

When creating a new command, Collaborama will ask which Module you want to save it in. Every user has their own "space", where they can save their own personal commands and customizations -- this module is the default when creating a new command. Other modules include "global", which is in the default path of all Collaborama members, and "sandbox", where works-in-progress are usually kept.

When you type a function into the command line, your module path will be searched in order, first looking in your personal space, then at system modules, then at the global module, finally in the sandbox. However, you can indicate which module to use by qualifying the function with the module name followed by a ".". For example, you can edit the default Collaborama homepage and save your customization into your personal module. When you access home, you will now see your customizations. If you'd like to access the default homepage, you can reference "site.home".

To see which modules you have readable and writable access to, and in what order modules will be searched when resolving commands, use the command "permissions".

Function Types

Functions come in several types:

Alias: This is used when you want to call an existing command by a different name, or make a private "link" to an existing function. Create your newly named command, make it of type alias, and in the 'page content' field, call the existing function, passing in variable surrounded by the % symbol. (Example: dist.) Note: if the target command has a render function, you should also specify this render function in the aliased version.
URL: Embed variables into a URL, and return the specified page. This is a quick way to do a Web search, for instance. (URL example: gim.)
WebL: A WebL script that calculates some result, perhaps based on certain input parameters. This can be used to scrape content from other sites. (WebL example: describe.)
HTML snippet: Not a fully executable command, snippets define pieces of HTML that may be displayed in the browser. They also support dynamic content generated using WebL. Place any WebL scripts in the page surrounded by "<webl>" and "</webl>". (Snippet example: the "help" page, help.)
HTML page: Similar to a snippet, but indicates that the result is a full page, to be displayed all by itself. Unlike a snippet, the result is displayed completely on its own, not within the Collaborama display enviroment.
Text/data: A way to store fully static content that is not in HTML or WebL form.

Optional Arguments

Collaborama functions declare their (mandatory) arguments in the Arguments field of the edit form; if you call a function with less arguments than it declares, you will get an error message. However, extra arguments passed to a function are bundled into an array called "OPTIONALARGS". When writing a function, you can check the size(OPTIONALARGS) and access arguments. Arguments are currently order-based, so you must presently document their existance in the "Description" field of the edit form.

If additional arguments are sent (in addition to the cmdline argument), you can access them in the EXTRAARGS variable name.

WebL Scripting Language

When writing WebL commands, you have access to the WebL language, minus a few functions for security reasons ("exec", "exit", "import", etc.) Instead of using WebL's Eval() function, use the provided WubEval() function instead. Modules Str and Url have been imported and are available for use. In addition, a number of Collaborama utility functions are available in module called Wub; see the "internalapi" page for details on this internal API.

Calling Other Functions

From inside a WebL block of code, you can call another Collaborama function using the WubCall(CmdName, ArgList) function:

   var dist = WubCall("distance", ["Oakland, CA", "San Francisco, CA"]);

From inside of HTML, a link can dispatch to another Collaborama function by using <a href="/webl/WubHub_DoIt?cmdline=yourFun(arg1,arg2)">Link Text</a>. Finally, you can create a form that passes arguments to a Collaborama function by specifying a hidden 'cmdline' field within the form. The arguments specified in this field should refer to field names within the form:

<form action="/webl/WubHub_DoIt" method="post">
   <input name="cmdline" value="distance(arg1, arg2)" type="hidden"/>
   From: <input name="arg1" value="" size="45" title="From address"/>
   To:   <input name="arg2" value="" size="45" title="To address"/>
         <input type="submit" value="Calculate Distance">
</form>

Tags and Flags

When defining a function, you may associate "tags" and "flags" with the function. Tags are user-defined labels that categorize a function as belonging to a particular group or having a particular feature. Flags are "special" tags that are referenced explicitly by other Collaborama functions, therefore having a functional "use". For instance, the "test" flag is used to indicate that a function should be included in Unit Test runs, and the "render" flag marks render functions.

User-defined tags (entered in the "Tags:" input box for a function) will be stored internally in the form "tag.YourTag"), and user-specified flags (entered in the "Flags:" input box) are stored in the form "flag.YourFlag". In addition, Collaborama automatically tags functions with system-level flags to enable easy searching for functions. Examples include "type.FunctionType", where FunctionType is one of (alias, url, webl, snippet, text), "system.cached", and "createdby.UserName".

Return Values

It is helpful to realize that any page has a WebL return value. Text/data pages are strings, HTML pages are "page" types, and HTML snippets are "pieces". The return value of a WebL page depends on the code within that page. A WebL page can call other Collaborama pages, of any type, using the WubCall(CmdName, ArgList) function, and combine its results to give a new answer. The type of a return value also affects how Collaborama displays the final answer to the user: strings and HTML snippets are displayed within the Collaborama environment, but HTML pages take up the whole browser window.

Caching page results

Most Collaborama scripts return results quickly, but some commands that query many web sources (e.g. cultureBonk(sf))or combine many commands (e.g., runAllUnitTests) may take a while to run. To improve performance, we have implemented caching of command results. Here's how it works:

Commands with checkbox "Cache results" will persist their results for each unique input they receive. If executed again with arguments it has seen before, the saved result is returned immediately rather than running the command. This caching is GLOBAL across all users, so use with care.
If you fill out an "Expiration Date", cached results will expire. You may request that the system automatically refresh values at a certain rate (e.g. 1D = every day, 1H = every hour, or combinations such as "3W 2H"). The refresh threads run as as the "anonymous" user, so this will only work for functions accessible when you are logged out (e.g. in module "global").
To clear the cache for a function, you can execute "clearCache(funcName)"

Session Workspace

For logged in users, there is also available a "session workspace", called wubvars, that functions can use to store return values that may be used by other commands. It is simply a globally accessible WebL variable that may be written to. For instance, a function could assign wubvars.answer := 42, and a Collaborama function called later could check the value of wubvars.answer. Each user has their own wubvars session (wubvars is not shared across users). The wubvars command can be used to inspect this variable. Users begin with an empty object [. .] for wubvars. Note this feature is not currently available to anonymous users; for them, wubvars is nil. It may be advisable for functions to check a user is logged in before using it.

WubInfo Variable

Occasionally, WebL functions may wish to obtain information about the request they are handling. The wubinfo global varaible is an object holding many useful fields:

wubinfo.cmdline: Full command line executed by user (string).
wubinfo.cmd: Name of function executed by user (string).
wubinfo.args: Arguments passed to function executed by user (list).
wubinfo.user: Username of current user; nil if user not logged in (string).
wubinfo.fullname: Name of current user; nil if user not logged in (string).
wubinfo.wubversion: Version of Collaborama system (string).
wubinfo.weblversion: Version of WebL used by Collaborama.

The wubinfo command can be used to inspect this variable.

Advanced Programming

See the advancedProgramming page to see topics such as working with Tries, with Lucene (search and local search), and MongoDB (databases).