Namespacing with MidCOM
MidCOM follows a very strict concept of Namespaces. While PHP has no idea what a namespace could be, you as a PHP programmer must be aware of MidCOMs conventions about namespacing. If you do not obey the rules outlined below, there will be no such thing as portability in your MidCOM code.
The basic idea behind MidCOM Namespacing is a system similar to Java's Package Hierarchy. To achieve globally unique package identifiers it suggests using internet domain names as a hierarchy. A component developer must only create elements within a part of the global namespace defined by your own domain.
Component identifiers
Example: If company called Example Corporation, owning the domain example.net, is to create a search component, it would be located somewhere in the namespace net.example.*, for example in net.example.search.
As in Java, packages use a dot as a hierarchy delimiter, decending from the top-level domain downwards to the actual name of the component, defining the actual name of the component.
Each part of the namespace must match this regular expression:
All non-valid characters (i.e. dashes in Domain Names) have to be dropped, this should still be unique enough for real-world usage.
Derived from the component's name (net.example.search in the example above) are two variants, that do the actual namespacing within PHP and Midgard:
Replacing the dots by underscores, you will get the prefix that your component must apply to all global naming elements (classes, variables etc.). So the navigation class of our search component would be actually named net_example_search_navigation. This often results in awkwardly long identifiers for elements with a global scope, but it is the only possible solution I have found so far. So please stick to it when naming your identifiers.
Another representation of the components can be acquired by replacing the dots with slashes, giving you net/example/search from the example above. This is used as a directory path to the storage location of the component itself.
Private elements
Another major problem of PHP is its lack of private elements. While a pure specification cannot enforce private variables like Java or C++ can do, a guideline is still helpful for programmers.
All identifiers that are prefixed with an underscore are to be considered private. These elements are a no-use with the sole exception of the component who definies it.
Note, that for global identifiers the underscore is added to the local name, a helper class for the search component above which should be component-privat is therefore named net_example_search__helper (note the second underscore), not _net_example_search_helper. The file containing the class should be named _helper.php accordingly.
Reserved Elements
There are some reserved names in MidCOM:
The Package hierarchy
midcom.*accociated with its namespace is fully reserved for the MidCOM Framework.The following names are reserved for component's internal directories and not allowed in component names:
locale,midcom,config,documentationandstyle.
Parameter naming
As MidCOM must be able to store arbitary data at any content objects (e.g. topics, articles or attachments) the namespacing rules are in effect here too.
Any component may store arbitary data using its own component path (e.g. net.example.search) as a parameter domain. Nothing else is permitted. MidCOM automatically retrieves topic parameters of the component currently handling a given topic and passes them to the component during its configure cycle.
The domain midcom is special. It is used to control MidCOM itself. Important is the Parameter midcom.component, which contains the Path to the component MidCOM should load at this point and midcom.style which holds the path to the style to be used by the MidCOM style engine.
This leads to the conclusion that a single topic or article could hold the configuration data for more than one component. This is actually used at several points in the system. The most prominent example is the MidCOM Datamanager which stores its information within the domain midcom.helper.datamanager. This, for example, could be datamanger fields to be stored as parameters of a given article or datamanager metainformation holding information how to handle a datamanager-controlled attachment.
HTML ID attributes
The element id attribute can appear only once per HTML document. Because of this, MidCOM components must follow the same namespacing guidelines for HTML ids. For example, the query string field for the net.example.search component could have an id="net_example_search_query" attribute.