Upgrading Components

This article outlines the tasks you as a component author have to do when converting a component to FS-MidCOM.

For a start, it is not that difficult. The first step is to get the component's code out into the filesystem, which can be easily done using the new WebDAV interface. It is not yet perfect, you will have to do a few things afterwards.

File Renaming, Component restructuring

First and tomost, you have to rename all snippets in the _l10n snippetdir to .php.dat. This is mainly useful to avoid PHP IDEs to stumble over hundrets of meaningless .php files. Also, the .dat extension is being used as for all non-PHP files within the MidCOM Library. Use something like find -iname "*php" -exec mv {} {}.dat \; to do this compfortably.

You should do the same with all configuration and schema files in your component, so that only the true sources and the style elements remain as .php.

Then, move all the code snippets from _code to the main component directory, remove it, and then rename _doc to documentation and remove the underscores from the directories _config, _style and _midcom. This will make the component a bit clearer to read.

Note, that according to the new directory hierarchy in mRFC 6 you are now allowed to create custom subdirectories as you need them.

Of course, all these changes have to be reflected in the source of the component. For a good example, look into de.linkm.newsticker, it is by no means perfect, but good enough as a template.

Using require instead of load_snippet

While this is not absoultely required, it is encouraged for ease of code. The MidCOM load_snippet directive will map an old-style call to the filesystem for the time being, but it is considered deprecated. The now preferred way of initializing the component looks roughly like this:

$prefix = MIDCOM_ROOT . "/de/linkm/taviewer";
require("${prefix}/viewer.php");
require("${prefix}/navigation.php");
require("${prefix}/admin.php");

The constant MIDCOM_ROOT is there representing the location of the MidCOM Code Library. Remember, that the location of your code snippets have changed.

Using the Datamanger with file-based schemas

The datamanager now has support for reading a schema from a file. To use this, you have to use the syntax "file:/path/to/file" in any place where you would normally load the data from a component-delivered snippet. This means, that your default configuration could look like this, taken from the reworked datamanager:

"schemadb" => "file:/de/linkm/taviewer/config/schemadb_default.dat",

All file paths are always taken relative to MIDCOM_ROOT.

Transparently accessing snippets and files

Often enough you find yourself in the situation having a schema db url in the config, that might or might not be preceded with a file:. To avoid having to check against this again and again, the global helper function midcom_get_snippet_content($path) is available to you. It supports file: operation and will return either the content of the file referenced (relative to MIDCOM_ROOT) or the code field of the corresponding snippet.

Static files

MidCOM now has an "offical" place where you can put static files that should be used directly by the client without going through MidCOM. This is for example useful for icons, CSS files and the like. It is especially useful while incorporating stuff like HTMLArea into the Framework, as the corresponding JScript Files will be readily available through the site's document root.

This directory is usually alised to /midcom-static/ into your document root, but since it is possible to change this, you should never hardcode this path. Instead use the global define MIDCOM_STATIC_URL, which will contain the prefix you need to use without a trailing slash. So you can use it like this, for example:

<img src="<?php echo MIDCOM_STATIC_URL; ?>/stock-icons/16x16/attach.png"
width="16" height="16" ALT="">

Working without the preparser

Ensure, that your code works without the Midgard Preparser, as outlined here. Note, that this is not neccessary for the Style snippets you use from either the Midgard Style Database or the Component's defaults.

Make sure, that you do not use the (long time deprecated) mgd_include_snippet or $midcom->load_snippet way of building the AIS, always everywhere use midcom_show_style (unconditionally).

AIS / NAP Toolbar Adaption

MidCOM 2.0.0 features a new, centrailized toolbar system to faciliate UI-consistency. Please check the article AIS toolbar update in this section along with the documentation of midcom_helper_toolbar and the example code in the component de.linkm.taviewer.

Also look into NAP Toolbar Interface, as you can now be more specific about AIS links in your NAP information.