Variable.Variable

The classes in the Variable module are the abstractions of module variables, with methods to define, set, read, render modification widgets for, change visibility of the variable and so on. The Variable.Variable class is the basic variable type in Roxen. All other variable types inherit (and should inherit) this class.

Of most interest to the roxen module programmer, we have the basic, high-level API of the Variable classes - how to define a variable, change its visibility check callback or get callbacks when the variable is changed:

The constructor, for defining and initializing variables. Default is the default value for the variable, flags is a bitwise or of one or more of the VAR_ defines defined in module.h:

VAR_INITIAL: Should be configured initially.
VAR_MORE: Only visible when more-mode is on (default on)
VAR_DEVELOPER: Only visible when devel-mode is on (default on)
VAR_EXPERT: Only for experts

The std_name and std_doc are the name and documentation string for the default locale (always english).

void set_invisibility_check_callback(function(RequestID,Variable:int) cb)

If the function passed as argument returns 1, the variable will not be visible in the configuration interface.

Pass 0 to remove the invisibility callback.

function(RequestID,Variable:int) get_invisibility_check_callback()

Return the current invisibility check callback.

int check_visibility(RequestID id, int more_mode, int expert_mode, int devel_mode, int initial, int|void variable_in_cfif)

Return 1 if this variable should be visible in the administration interface. The default implementation checks the flags field, and the invisibility callback, if any. See get_flags(), set_flags() and set_invisibibility_check_callback().

If variable_in_cfif is true, the variable is in a module that is added to the configuration interface itself. This allows you to hide variables that would break something in the admin interface, if set to an value that is illegal in that context, for instance. It might seem as though you can not add modules of your own to the admin interface (and for a good reason too - tampering with the admin interface can easily lead to a malfunctioning admin environment - but if you really know what you are doing, you can start the server with the define YES_I_KNOW_WHAT_I_AM_DOING, and may then tamper to your heart's delight :-).

void set_flags(int flags)

Set the flags for this variable. See create() for more info.

int get_flags()

Returns the flags field for this variable. See create() for more info.

void set_warning(string to)

Set the warning shown in the configuration interface.

void add_warning(string to)

Like set_warning(), but adds to the current warning, if any.

int set(mixed to)

Sets the variable to a new value.

The return value depends on the result of the set:

true (non-zero)

The set was successful and changed the value of the variable. More precisely, the return value hints about how it was changed:

-1: The variable was changed back to its default value.
1: The variable was changed otherwise.

false (zero)

The set didn't change the value of the variable, for some reason or other:

0: A plain 0 is returned if the variable was not changed by the set.
UNDEFINED: The set failed (verify_set() threw a string). (UNDEFINED is a 0 with zero_type set to one, such as ([])[0]). If verify_set() threw an exception, the exception is thrown, instead of returning a value.

int low_set(mixed to)

Forced set. No checking is done whatsoever. Returns:

-1: The variable was changed back to its default value.
1: The variable was changed otherwise.
0: The value was unchanged, or the set failed.

mixed query()

Returns the current value for this variable.

int is_defaulted()

Return true if this variable is set to its default value.

string get_warnings()

Returns the warnings currently signalled by the variable, if any (zero otherwise).

function(Variable:void) get_changed_callback()

Return the callback set with set_changed_callback().

void set_changed_callback(function(Variable:void) cb)

The function passed as an argument will be called when the variable value is changed.

Pass 0 to remove the callback.

void add_changed_callback(function(Variable:void) cb)

Add a new callback to be called when the variable is changed. If set_changed_callback() is called, callbacks added with this function are overridden.

mixed default_value()

Returns the default (initial) value for this variable.

When implementing your own variable types, there is a type constant and a host of other methods that are of interest too. This is also the recommended way if you are extending a variable type to provide more error checking, for instance, apart from when you use some kind of data that is not already available among the default set of variables. Just inherit a suitable base class (Variable.Variable if you are still doing everything from scratch), and redefine whatever you need.

string type

Mostly used for debug (sprintf("%O", variable_obj) uses it).

string doc()

Return the documentation for this variable (locale dependant).

The default implementation queries the locale object in roxen to get the documentation.

string name()

Return the name of this variable (locale dependant).

The default implementation queries the locale object in roxen to get the documentation.

string type_hint()

Return the type hint for this variable. Type hints are generic documentation for this variable type, and is the same for all instances of the type.

array(string|mixed) verify_set_from_form(mixed new_value)

Like verify_set(), but only called when the variables are set from a form.

array(string|mixed) verify_set(mixed new_value)

Return ({ error, new_value }) for the variable, or throw a string.

If error != 0, it should contain a warning or error message. If new_value is modified, it will be used instead of the supplied value.

If a string is thrown, it will be used as a error message from set, and the variable will not be changed.

mapping(string:string) get_form_vars(RequestID id)

Return all form variables preficed with path().

mixed transform_from_form(string what)

Given a form value, return what should be set. Used by the default set_from_form() implementation.

void set_from_form(RequestID id)

Set this variable from the form variable in id->Variables, if any are available. The default implementation simply sets the variable to the string in the form variables.

Other side effects: Might create warnings to be shown to the user (see get_warnings()).

Calls verify_set_from_form() and verify_set().

string path()

A unique identifier for this variable. Should be used to prefix form variable names.

Unless this variable was created by defvar(), the path is set by the configuration interface the first time the variable is to be shown in a form. This function can thus return 0. If it does, and you still have to show the form, call set_path() with a unique string.

void set_path(string to)

Set the path. Not normally called from user-level code.

This function must be called at least once before render_form() can be called (at least if more than one variable is to be shown on the same page). This is normally done by the configuration interface.

string render_form(RequestID id, void|mapping additional_args)

Return a (HTML) form to change this variable. The name of all <input> or similar variables should be prefixed with the value returned from the path() function.

string render_view(RequestID id)

Return a "view only" version of this variable.