Mason Framework API

The mason framework does a complex handling of several data, as example, it (by default) propagate global template data Outside-In, but don't propagate the data back unless specificly said. So, to make sure that everything works as expected, the data can't be directly accessed. So, everything you need to do, the Framework provides a method to that.

This are the methods the MFWork object provides. An object of this type is already provided to each module or handler that will be called at any time, so you will not need the new constructor.

The MFWork object is given to any module or handler as $mf arg. You will not need the run method, as it is already called for you way before any module or handler is called.

Methods for the MFWork object

$mf->arg($argname);

Returns the $argname argument sent to the page. For exemple, calling $mf->arg('value'); while processing http://www.yoursite.com/index.html?value=123 will return 123.

This will work for every module or handler in a page. There is an intented and expected case where $mf->arg() don't return the initial arguments. That case is explained next.

$mf->set_args();

$mf->set_args have two different behaviours. In the first is expects a hashref, and in the second it expects a list.

$mf->set_args(\%args);

If set_args is called with an hashref it will use the referenced hash as its args list from that point on. The previous args will be discarded for good. Use with care. With extreme care.

Why use at all? you ask. Well, $mf->form() uses args to get the values of their field values. If you want to show a form and after a valid submit show it again or show another form, you need to reset args. I use this on the admin/pages module, to process the Preview.

$mf->set_args(%argslist);

if set_args is called, but not with an hashref, it will use its args as an hash, and add the keys to args (or rewrite the current values).

$mf->dbh();

This will return a DBI handler to the database. If this is the first time the dbh() method is called it will create a connection, otherwise it will reuse the same connection.

$mf->get_db_dataset($query, @params);

This method will execute the $query with @params, and return the resulting dataset as a array of hashes.

$mf->option($optname)

Will return the value for the option $optname value. This will be the value for the current request. At this point, this only considers the global value (set at Base Options) and the site value (set at Options), but in a future release (still with 0.1.x) this will consider also the value for the user options.

$mf->get_vault()

This will return a hashref that will be return everytime the same component (not module, every single component in a module will have it's own vault) calls it. The vault it valatile, that means, exists for the present page processing only. At this time, if a module need to keep that across multiple page procesings, it should use the Mason cache.

$mf->get_shared_vault($vaultname)

This can be used to share a vault across multiple modules or components, even if they are not linearly. The vault exists across the page procesing, and not after this ends.

This vaults and the ones you can get from $mf->get_vault() are completly distinct, and you can't use this to get a vault from another component.

$mf->cachekey(@keys)

the Mason Framework is intented to run multiple sites with a single virtualhost (from apache config prespective), and multiple viltualhosts with a single instalation. With that consideration, a component must not assume he knows how to create a key to use with $m->cache (the Mason cache), unless it have 100% sure that key will always be unique.

$mf->cachekey() gets those values the module think make the key unique for the site, and returns a string that can be used as key to the $m->cache.

$mf->escape($str)

Anyntime need to use a string you matched somewhere in a new regexp, and the universe exploded? Not yet? You're a luck one. Now you can:



while (my ($str)=$text=~/[[\[\]\(\)]+/) {
  $str=$mf->escape($str);
  $text=~s/$str//;
}

$mf->data($name)

This returns the value of the template variable named $name.

$mf->set_data(%data)

This will merge the values in %data with the actual data. The values set this way can be used in every template processed after this call. This include the templates that are being processed (those that include the placeholders where the current module will be included).

$mf->is_fatalplace($placename)

Returns true if the $placename is fatal. A Fatal place is one that needed to have content. Usually the main content placeholder (<?=main?> in the default configs).

$mf->add_fatalplace($placename)

Add the place $placename to the list of fatal places.

Note: If a module verifies a condition and replaces his place with a new placeholder (or calls a template that is expected to create a new placeholder), his place is fatal and the new place is all the content it expects to include, then the module must add the new expected place as fatal.

Note 2: If a module calls a template that is expected to create a new (mo dule) placeholder, but the placeholder is not created, no error is issued. A tem plate without placeholder is always complete for the Mason Framework.

$mf->template('templatename', [...])

$mf->stemplate('templatename', [...])

$mf->template and $mf->stemplate are for MFWork templates the equivalents to $m->comp and $m->scomp for Mason Components. The first outputs the template result to the MFWork template engine to be included in the current placeholder, and the second to the caller (the module being executed).

You should use the first if processing a complete template, and the second if processing partial templates, that will be included later in a bigger template.

Both get the same parameters:

the first is the template to be processed. This is the only mandatory parameter, and is not a named one.
Every other parameter are named parameters, and are all optional. They are:

data: This is expected to be an hashref. If this parameter is set, all template data that was set before will be discarded while processing this template or any module included or subtemplate.
add_data: as data, this is expected to be an hashref, but this template values will be added to the previously set data, and a merge of the two will be used. If this includes previously set data variables, those present here will be used to this template and every subtemplate.
cachetemplate: If this is true, the template will be cached in memory for the duration of the current page processing. This should only be used to templates that are expected to be called several times in a same page. For exemple, the row template in a list.

$mf->handle(zone=>$zone, zonetype=>$zonetype, args=>$argsref, [...])

This executes the handlers for $zone and $zonetype. All their parameters are named:

zone mandatory: The zone that will be handled.
zonetype mandatory: The zonetype that will be handled. Note: the handlers that will be selected to run are those registered for this zonetype as well as those registered to run with with $zonetype='default'.
args mandatory: This is expected to be an hashref, that will be passed to the handler as args.
type: This must be one of single (the default), untilok, whileok, whileokdiscard, all. Any other value sent to type will result in $mf->handle behaving as if all was given. This parameter defined the handling type that will be performed:

single (the default): Only the first registered handler will be used. Even if the handler returns with error or a discard status, no other handler will be called.
untilok: In this case, $mf->handle will call each handler to the ($zone, $zonetype) until one of them ends with $result->{status} eq 'ok'.
whileok: In this case, $mf->handle will call each handler to ($zone,$zonetype) until one of them returns something that is not 'ok'.
whileokdecline: In this case, the handlers will be called until one of them returns a status that is not ok or decline. This allow handlers to say that they don't want to handle that data, but you still continue processing other handlers.
all: In this case all handlers will be called, unless one of them return error.

default_status: This allow you to set a default status structure, that will be returned if no handler is set to that $zone and $zonetype (including $zonetype='default').

Note: See Handlers for more details on handler implementation and execution.

Note 2: An handler that ends with an status that not 'ok' is expected to leave the data it gets unchanged.

$mf->get_handlers(zone=>$zone, zonetype=>$zonetype)

$mf->get_handlers returns a list with info on all handlers for a specific $zone and $zonetype.

$mf->bodyformat(body=>$body, from=>$from[, to=>$to])

$mf->bodyformat can be used to transform the body content from a formating syntax to a diferent one ('html' is the default).

$mf->form([...])

Create a form and returns the submited valid data. See Forms for details.

$mf->table([...])

$mf->stable([...])

Creates a table. They work as $mf->template and $mf->stemplate.

$mf->urify($uri)

$mf->urify($uri) returns a urified version of the string if gets as parameter. This works with international latin characters.

$mf->get_user()

Returns the information of the current user.

$mf->user_is($permition)

Return true if the user have the specified permition, false otherwise.

$mf->user_logout()

Removes the current user session.

Mason Framework