mRFC 0010: MidCOM Metadata Interface

1. Introduction
2. Storage Interface
3. API
4. Proposed Metadata Keys in a first implementation
5. AIS integration
6. Site integration
7. Converting existing Metadata and backwards-compatibility
8. Where to go from here?

This mRFC is about the integration of a flexible, component-independant metadata system, that can be queried through NAP.

Introduction

Currently, NAP does only provide information about the creation and revision of a given object, and it relies on the component to do so. While this works for the currently provided information, it would be very tedious if you start to integrate things like approval or visibility there. The current MIDCOM_NAV_VISIBLE stuff is a good example for this, as are the various approval variants used throughout the system.

The approach I propose to solve this problem is to create an interface within NAP that allows it to store arbitary data at a leaf or node. This has the advantage, that a single editing interface can handle all available components.

The storage interfaces is delivered by NAP and requires support of MIDCOM_NAV_GUID from the component, which will get mandatory if this mRFC gets implemented. This way the storage handler does not need to be implemented in the different components.

Important note: This will now introduce the requirement of having a GUID for each MidCOM leaf, which was not part of the original spec. As of my knowledge, no component does make use of this feature at the moment, therfore I have decided that this specific part of the spec can be changed accordingly.

Storage Interface

The NAP storage interface will use the datamanager to manage the data at the various object. In order to not interfere with the schemas of the component, a number of restrictions is placed onto the internal schema used by the NAP subsystem:

• Storing data in the fields of the storage object is strongly prohibited (you don't know which fields are available).
• Storing data in parameters is only possible as config parameters within the domain midcom.helper.metadata.
• Storing data in attachment is prohibited for now.
  
• Locking will be disabled to avoid having stale locks on content objects.
  

The increased overhead involved with the datamanager's metadata loading, this will only be done on demand, e.g. if someone requests the metadata for a given object.

For performance reasons, the Metadata objects will directly access these parameters, unless the Datamanager is used explicitly.

API

The API will be two-fold. The Metadata interface is encaspulated in its own class, the basicnav class will only hold a cache and the appropriate interface. For each MidCOM object (node or leaf) there will be a separate instance of that class.

• mixed get($key): Gets the corresponding Metadata key. Preferred method, as it retrieves only those values, that are needed.
• set($key, $value): Sets the corresponding key.
  
• Array get_all(): This will return the complete DM metadata array.
  
• midcom_helper_datamanager get_dm(): As above, but it will return a datamanager instance.
• approve(): Approves the object. The approval timestamp is set to the current system time.
• unapprove_object(): Unapproves the object. The approval timestamp is set to 0 to indicate unapproved state.
• schedule_object (timestamp $start, timestamp $end): Sets the visibility scheduling for a given object.
  
• bool is_visible(): Returns true if the object is visible right now, false otherwise. This takes both approval, scheduling and the explicit visibility settings into account.
  

The NAP API will be extended by the following elements:

• midcom_metadata get_metadata($guid = null): Retrieves the metadata object corresponding to the GUID, the default is the currently displayed object.
  
• bool $show_only_approved = false: This is a selector that allows you to automatically hide any unapproved items. Items, which have a publishing start/end time that has elapsed count as unapproved in this respect.
  
• bool $show_only_visible = true: This selector indicates if only visible items should be shown.
• MIDCOM_NAV_VISIBLE will be automatically populated using the new metadata now, with any component-given value overriding it for backwards compatibility.
  Note: I propose a conversion script that converts the visibility settings currently implemented in the various component into the new default location to keep the code clean.

The most important point here is NAPs new ability to reverse-lookup GUIDs. Note, that at the very moment there are no security restrictions in place for verifying that a given object is with the current content tree, you could access an arbitary object here right now.

Proposed Metadata Keys in a first implementation

• timestamp approved = 0 (Parameter): Indicates, if the article has been approved (non-null).
• guid approver = null (Parameter): The GUID of the person that has approved the object.
  
• timestamp schedule_start = 0 (Parameter): The start of the visibility time for scheduled articles, a null value indicates no start time.
• timestamp schedule_end = 0 (Parameter): The end of the visibility time for scheduled articles, a null value indicates no end time.
• string keywords (Parameter): A set of keywords for the HTML header of the corresponding page.
• string description (Parameter): The page's description for the HTML header of the corresponding page.

The special handling of Articles described here earlier (using calstart/-days on articles) will be postponed for now, as this would make things unneccessarily complex. Instead, upon writing the article, the metadata information is copied into the corresponding article fields, but the mandatory information is always the parameters stored at the object. These copies are there for quickly querying articles for approval mainly.

AIS integration

The primary interface will be a AIS driven DM editing interface for the current topic.

In addition, several "hot-keys" e.g. for approval should be placed within the User Interface. I would welcom any suggestion how to integrate this cleanly.

My idea was to have a second toolbar above or below the request-local one with access to the various metainformation, the view-this-page link could be added here too, so that the component's toolbar will be less cluttered.

Site integration

At the moment all kinds of access checks regarding visibility or approval will only be done within the navigation. There will (currently) be no additional checks whatsoever while a request's URL is parsed. So if you know the URL of a actually hidden topic, you will still be able to access it.

Converting existing Metadata and backwards-compatibility

Additionally, we will need a conversion script, that transforms the currently avaialble visibility settings into parameters matching the new structure. This will be a simple PHP file in some new update directory within the lib tree, which has to be called manually using some Midgard-enabled page.

See the parameter registry what parameters are currently in use.

In addition to this initial conversion script, there will be a hook within the metadata interface that copies the values into the old places where neccessary (this should be configurable actually). At this time I do not know of any metadata parameters that are relevant outside of MidCOM though.

Where to go from here?

• PermaLink support will now be viable, as the GUID information is uniformly present
• Caching might be of interest on the long run, to speed up NAP processing