\org_openpsa_expenses_viewer

This is the class that defines which URLs should be handled by this module.

It provides an automatic mechanism for URL processing and validation, minimizing
the required work to get a new component running.

Request switch configuration

The class uses an array which aids in URL-to-function mapping. Handlers are distinguished
by the "URL-space" they handle. For each handler three functions are needed, one for the
request handle decision ("Can Handle Phase"), one for the
request handling ("Handle Phase") and one for output ("Output Phase"). These handlers refer to
another class which gets instantiated if necessary.

All request handlers are contained in a single array, whose keys identify the various switch
configurations. These identifiers are only for informational purposes (they appear in the
debug log), so you could just resort to automatic array index numbering using the []
operator.

Each request handler definition in the switch must contain these key/value pairs:

mixed fixed_args: This is either a string or an array and defines the fixed
arguments that have to be present at the beginning of the URL to be handled. A
string denotes a single argument, an array is used if more than one fixed argument
is needed. If you do not have any fixed arguments, set this parameter to null, which
is the default.

int variable_args: Usually, there are a number of variables in the URL, like
article IDs, or article names. This can be 0, indicating that no variable arguments are
required, which is the default. For an unlimited number of variable_args set it to -1.

mixed handler: This is a definition of what method should be invoked to
handle the request using the callable array syntax. The first array member must contain
the name of an existing class.
This value has no default and must be set. The actual methods called will have either an
handler or show prefix.

This definition is usually located in either in the routes.inc file (preferred)
or the _on_initialize event handler.

The handlers are processed in the order which they have been added to the array. This has
several implications:

First, if you have two handlers with similar signatures, the latter might be hidden by the
former, for example the handler 'view' with two variable arguments includes the urls that
could match 'view', 'registration' with a single variable argument if processed in this order.
In these cases you have to add the most specific handlers first.

Second, for performance reasons, you should try to add the handler which will be accessed
most of the time first (unless it conflicts with the first rule above), as this will speed
up average request processing.

It is recommended that you add string-based identifiers to your handlers. This makes
debugging of URL parsing much easier, as MidCOM logs which request handlers are checked
in debug mode. The above example could use something like
$this->_request_switch['registrations-view'] to do so. Just never prefix one of your
handlers with one underscores, this namespace is reserved for MidCOM usage.

The main callback _handle_xxx is mandatory, _show_xxx is optional since the handle method can
return a response directly.

As you can see, the system provides you with an easy way to keep track of the data
of your request, without having dozens of members for trivial flags. This data array
is automatically registered in the custom component context under the name
'request_data', making it easily available within style elements as $data

The data array can also be accessed by using the $_request_data member of this class,
which is the original data storage location for the request data.

Note that the request data, for ease of use, already contains the L10n
Databases of the Component and MidCOM itself located in this class. They are stored
as 'l10n' and 'l10n_midcom'. Also available as 'config' is the current component
configuration and 'topic' will hold the current content topic.

Automatic handler class instantiation

If you specify a class name instead of a class instance as an exec handler, MidCOM will
automatically create an instance of that class type and initialize it. These
so-called handler classes must be a subclass of midcom_baseclasses_components_handler.

The two methods for each handler have the same signature as if they were in the
same class.

Plugin Interface

This class includes a plugin system which can be used to flexibly enhance the
functionality of the request classes by external sources. Your component does
not have to worry about this, you just have to provide a way to register plugins
to site authors.

Plugins always come in "packages", which are assigned to a namespace. The namespace
is used to separate various plugins from each other, it is prepended before any
URL. Within a plugin you can register one or more handler classes. Each of this
classes can of course define more than one request handler.

A plugin class must be a descendant of midcom_baseclasses_components_handler or at
least support its full interface.

As outlined above, plugins are managed in a two-level hierarchy. First, there is
the plugin identifier, second the class identifier. When registering a plugin,
these two are specified. The request handlers obtained by the above callback are
automatically expanded to match the plugin namespace.

The first argument of this call identifies the plugin namespace, the second
the list of classes associated with this plugin. Each class gets its own
identifier. The namespace and class identifier is used to construct the
final plugin URL: {$anchor_prefix}/{$namespace}/{$class_identifier}/...
This gives fully unique URL namespaces to all registered plugins.

Plugin handlers always last in queue, so they won't override component handlers.
Their name is prefixed with __{$namespace}-{$class_identifier} to ensure
uniqueness.

Each class must have these options:

class: The name of the class to use

src: The source URL of the plugin class. This can be either a file:/...
URL which is relative to MIDCOM_ROOT, snippet:/... which identifies an
arbitrary snippet, or finally, component:...
which will load the component specified. This is only used if the class
is not yet available.

name: This is the clear-text name of the plugin.

config: This is an optional configuration argument, allows for customization.
May be omitted, in which case it defaults to null.

Once a plugin has been successfully initialized, its configuration is put
into the request data:

mixed plugin_config: The configuration passed to the plugin as outlined
above.

Type

Tags

None found

$_handler

$_handler : Array

The handler which has been declared to be able to handle the
request. The array will contain the original index of the handler in the
'_route' member for backtracking purposes. The variable argument list will be
placed into 'args' for performance reasons.

Tags

$router

Type

Tags

None found

$_request_switch

$_request_switch : array

Request execution switch configuration.

The main request switch data. You need to set this during construction,
it will be post-processed afterwards during initialize to provide a unified
set of data. Therefore you must not modify this switch after construction.

Type

Tags

None found

$_plugin_namespace_config

$_plugin_namespace_config : array

This variable keeps track of the registered plugin namespaces. It maps namespace
identifiers against plugin config lists. This is used during can_handle startup
to determine whether the request has to be relayed to a plugin.

You have to use the register_plugin_namespace() member function during the
_on_initialize event to register plugin namespaces.

Tags

show()

Tags

_on_initialize()

Initialization event handler, called at the end of the initialization process

Use this function instead of the constructor for all initialization work. You
can safely populate the request switch from here.

You should not do anything else then general startup work, as this callback
executes before the can_handle phase. You don't know at this point
whether you are even able to handle the request. Thus, anything that is specific
to your request (like HTML HEAD tag adds) must not be done here. Use _on_handle
instead.

Tags

None found

_on_handle()

_on_handle(mixed $handler, array $args)

Component specific initialization code for the handle phase. The name of the request
handler is passed as an argument to the event handler.

Note, that while you have the complete information around the request (handler id,
args and request data) available, it is strongly discouraged to handle everything
here. Instead, stay with the specific request handler methods as far as sensible.

Parameters

mixed

$handler

The ID (array key) of the handler that is responsible to handle
the request.

Tags

_on_handled()

Parameters

Tags

register_plugin_namespace()

register_plugin_namespace(string $namespace, array $config)

Create a new plugin namespace and map the configuration to it.

It allows flexible, user-configurable extension of components.

Only very basic testing is done to keep runtime up, currently the system only
checks to prevent duplicate namespace registrations. In such a case,
midcom_error will be thrown. Any further validation won't be done before
can_handle determines that a plugin is actually in use.

Parameters

string

$namespace

The plugin namespace, checked against $args[0] during
URL parsing.

array

$config

The configuration of the plugin namespace as outlined in
the class introduction