\net_nemein_wiki_viewer

Wiki Site interface class.

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.

Example:

$this->_request_switch[] = [ 'fixed_args' => ['registrations', 'view'], 'variable_args' => 1, 'handler' => ['net_nemein_registrations_regadmin', 'view'] ];

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.

Callback method signatures

/**

• Show handler example, with Docblock:
• @param mixed $handler_id The ID of the handler.
• @param array &$data The local request data. {@*} public function _show_xxx ($handler_id, array &$data) {}

The two callbacks match the regular processing sequence of MidCOM.

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 subclasses you create should look about this:

class my_handler extends midcom_baseclasses_components_handler { public function _on_initialize() { // Add class initialization code here, all members have been prepared } }

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.

Example: Plugin registration

$this->register_plugin_namespace( '__ais', [ 'folder' => [ 'class' => 'midcom_admin_folder_management', 'config' => null, ], ] );

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.
• string plugin_name: The name of the plugin as defined in its config

Properties

Methods