Routing

Routing handles the mapping of URLs to different parts of the application. In MidCOM, there are two main mechanisms to do this:

Topic-based Routing

Component routing is based on Topics, which gives you a lot of flexibility in how you structure your site's URL space. If your topic tree looks like this:

root
  news
     blog
  aboutus
     company

Then a URL like /news/blog/latest/5/ would be resolved to the topic with the name blog. At this point, the topic's component takes over, and tries to map the remaining URL (in this case latest/5/) to a handler inside the component. Which routes can be handled by a component is determined in the routes.inc file in the component's config directory. A typical route definition might look like this:

'latest-articles' => array(
    'handler' => array('net_nehmer_blog_handler_index', 'index'),
    'fixed_args' => 'latest',
    'variable_args' => 1,
),

So with the given URL, the handler class net_nehmer_blog_handler_index would get instantiated, and the method _handler_index will be called. Everything that matches variable_args (in this example, 5) get passed to _handler_index in the $args parameter:

public function _handler_index($handler_id, array $args, array &$data)
{
    // $handler_id == 'latest-articles'
    // $args[0] == '5'
}

Dynamic Load

Component routes can also be called from PHP code by using midcom_application::dynamic_load. This allows you to integrate output from a different component into your page:

// output a list of the user's tasks
midcom::get()->dynamic_load($projects_relative_url . 'task/list/');

URL Methods

MidCOM URL Methods are executed before any component processing is done. They all belong to the domain midcom and are executed by adding them at the beginning of the request URL like this: /midcom-$name-$value.

midcom-substyle-<string>

This will instruct the Style Engine to set a substyle to the current component, which is appended to the style selected by the component at the moment the component style is loaded. The methods substyle_(append|prepend) work on the basis of this value then.

Note, that this first assignment is done between can_handle and handle, so it will serve as a basis for all component-side style switching operations.

The substyle URL switch is most useful in conjunction with #Dynamic Load.

midcom-serveattachmentguid-<guid>

This will serve the attachment denoted by the given GUID. It uses the default expiration time of serve_attachment (see there).

Note: While MidCOM only requires a GUID, a filename is often appended on this URL Method for Browser compatibility. This filename doesn't have to match the name of the Attachment, as MidCOM identifies it by GUID.

midcom-permalink-<guid>

This will resolve the given GUID into the MidCOM NAP tree, relocating to the URL corresponding to the node/leaf. The Permalink can be created by using the MidCOM Constant MIDCOM_NAV_PERMALINK of any Navigation data array. Upon resolving it, MidCOM will relocate to the automatically computed MIDCOM_NAV_FULLURL.

midcom-exec-<component>/filename.php

Allows you to execute certain PHP files directly, in full MidCOM context. The argument is the name of the component, which holds the script to be executed. Script files are searched in the subdirectory exec/ of the component. If you use midcom as component name, MidCOM core scripts, located in lib/midcom/exec will be accessible. The next argument is the name of the script file. Accessing subdirectories is not possible, only a single argument will be taken.

The scripts executed need to do their own permission checks, they will work with the credentials of the current MidCOM instance unconditionally.

Example: http://$host/midcom-exec-midcom/reindex.php

See available scripts at MidCOM exec Scripts

midcom-cache-<string>

May take one of the following values:

• invalidate will clear the cache of the current site,
• nocache will bypass the content cache for the current request;

midcom-login-

Tries to login the user based on credentials sent in POST data

midcom-logout-

Ends the current login session