Baseclass to use for the component interface in MIDCOM.

The class uses an event based approach for subclasses to influence the default behavior.

The actual implementation should be enough for most smaller components, as the classes behavior is widely configurable. You should not override any of the base classes interface methods if you can avoid it. If you find that an event handler is missing, please contact the MidCOM development team for some advice.

Quick start

This class does a lot of things automatically for you, described below. If you are not interested in the gory details though, here is a quick list of what you have to know (but don't complain if I have missed anything), and do these things after calling the base class constructor:

  • Inherit the class as {$component}_interface (e.g. net_nehmer_static_interface).
  • Prepare a component manifest for your component, see the class midcom_core_manifest for details.
  • You can change the values of all public members, the defaults should be suitable for cases.
  • The component's data storage area will contain two keys when the initialized event handler is called: The NAP active id, defaulting to false and stored as active_leaf and the component's default configuration, stored as a midcom_helper_configuration object in the key config.
  • Put your component wide default configuration into $component_dir/config/config.inc.

Class parameters

The following options can be used to parametrize the components startup and operation. See the individual member documentation for now.

  • $_autoload_files
  • $_autoload_libraries
  • $_component
  • $_nap_class_suffix
  • $_site_class_suffix

Class operation

This class now does an awful lot of work for you, you just need to configure it to have the right names and places to look for. It is designed to fit in the current component wildlife with as little collateral damage as possible, but as always, a 100% transparent implementation is both not wanted and not sensible.

Actually, you should not need to overwrite any event handler for almost all components I currently know of. Ultimately, this is a proxy class to the actual component code. Its main goals are to automate these tasks:

  • Component startup (loading of the right script files and libraries)
  • Default configuration (loading of the various configuration files, see the _load_configuration() method for details)
  • Component data storage initialization
  • Context separation during runtime

Example usage

The average component will require something like this, part one is the component manifest:

'name' => 'net.nehmer.static',
'purecode' => false,
'version' => 1,
'privileges' =>  Array
(
    'read' => MIDCOM_PRIVILEGE_ALLOW,
    'write' => Array (MIDCOM_PRIVILEGE_DENY, MIDCOM_PRIVILEGE_ALLOW)
),
'class_mapping' => array('mgdschema_classname' => 'midcom_classname'),

See the class midcom_core_manifest for further details.

Built on this, we add the following interface class:

class net_nehmer_static_interface extends midcom_baseclasses_components_interface
{
    function _on_reindex($topic, $config, &$indexer)
    {
        $qb = midcom::get('dbfactory')->new_query_builder('midcom_db_article');
        $qb->add_constraint('topic', '=', $topic->id);
        $result = $qb->execute();

        if ($result === false)
        {
            debug_add("Could not query the articles for {$topic->id}, skipping indexing.");
        }

        $datamanager = new midcom_helper_datamanager2_datamanager($config->get('schemadb'));

        foreach ($articles as $article)
        {
            if (!$datamanager->autoset_storage($article))
            {
                debug_add("Warning, failed to initialize datamanager2 for Article {$article->guid}. See Debug Log for details.", MIDCOM_LOG_WARN);
                debug_print_r('Article dump:', $article);
                continue;
            }

            $document = $indexer->new_document($datamanager);
            $document->topic_guid = $topic->guid;
            $document->topic_url = $node[MIDCOM_NAV_FULLURL];
            $document->read_metadata_from_object($datamanager->storage->object);
            $document->component = $topic->component;
            $indexer->index($document);
        }
    }
}
package midcom.baseclasses
see \global\midcom_helper__componentloader
see \global\midcom_core_manifest

 Methods

_on_check_document_permissions (\midcom_services_indexer_document $document, \midcom_helper_configuration $config, \MidgardTopic $topic)

Verify an indexer document's permissions.

This is used for custom, advanced access control within a component's domain.

The topic and configuration objects are passed for ease of use and performance, as they have already been prepared by the framework.

Usually, you want to limit the visibility of a document in the search result. You can do this by returning false in this function, the indexer will then skip this object before returning the resultset to the callee. You may modify the document that has been passed, to limit the information available to the client, though this should be avoided if possible.

Parameters

$document

\midcom_services_indexer_document&$document The document to check. This object is passed by reference and may therefore be modified to match the current security policy.

$config

\midcom_helper_configurationThe configuration associated with the topic.

$topic

\MidgardTopicThe topic this document is assigned to.

Returns

booleanTrue if the object may be shown, false otherwise.

_on_initialize ()

This is an event handler, called after the basic component initialization has been done just before the initialize call will return to MidCOM.

It should prepare all necessary information to start processing requests.

Unless you need more functionality then snippet and library loading, configuration merging and basic component data storage initialization, no further modification needs to be done.

Returns

booleanIndicating whether the initialization has been successful.

_on_reindex (\midcom_db_topic $topic, \midcom_helper_configuration $config, \midcom_services_indexer $indexer)

Reindex the given topic.

The complete configuration set is already available in $config. The original index records are already deleted, so you do not need to bother about this.

The default event handler does nothing.

Parameters

$topic

\midcom_db_topicThe topic to reindex.

$config

\midcom_helper_configurationThe configuration associated with this topic.

$indexer

\midcom_services_indexerThe indexer object to use for indexing. (Passed by reference!)

Returns

booleanIndicating success.

_on_watched_dba_create (object $object)

This function is triggered at the end of the request for each watched create operation that has been done during the request.

It will be called once per operation and unique object, where object uniqueness is determined by the combination of object class and guid. The object has been refreshed before being passed to this event handler.

It is called after the generic _on_watched_operation event handler.

Parameters

$object

objectThe object on which the operation has occurred.

_on_watched_dba_delete (object $object)

This function is triggered at the end of the request for each watched delete operation that has been done during the request.

It is called after the generic _on_watched_operation event handler.

Parameters

$object

objectThe object on which the operation has occurred.

_on_watched_dba_import (object $object)

This function is triggered at the end of the request for each watched import operation that has been done during the request.

It is called after the generic _on_watched_operation event handler.

Parameters

$object

objectThe object on which the operation has occurred.

_on_watched_dba_update (object $object)

This function is triggered at the end of the request for each watched update operation that has been done during the request.

It will be called once per operation and unique object, where object uniqueness is determined by the combination of object class and guid. The object has been refreshed before being passed to this event handler.

It is called after the generic _on_watched_operation event handler.

Parameters

$object

objectThe object on which the operation has occurred.

_on_watched_operation (int $operation, object $object)

This function is triggered at the end of the request for each watched operation that has been done during the request.

It will be called once per operation and unique object, where object uniqueness is determined by the combination of object class and guid. The object has been refreshed before being passed to this event handler.

Parameters

$operation

intThe operation identifier (one of the MIDCOM_OPERATION constants) which applies.

$object

objectThe object on which the operation has occurred.

can_handle (\midcom_db_topic $current_object, int $argc, array $argv, int $contextid)

Relays the can_handle call to the component, instantiating a new site class.

It will execute can_handle of that class, returning its result to MidCOM.

Parameters

$current_object

\midcom_db_topicThe topic in question.

$argc

intThe count of the remaining URL arguments.

$argv

arrayThe argument listing

$contextid

intThe id of the context we are operating in.

Returns

booleanTrue, if the component can handle the request, false otherwise.

check_document_permissions (\midcom_services_indexer_document $document, \midcom_db_topic $topic)

Verify an indexer document's permissions.

It will call the corresponding event handler reading the topic configuration beforehand.

Parameters

$document

\midcom_services_indexer_document&$document The document to check. This object is passed by reference and may therefore be modified to match the current security policy.

$topic

\midcom_db_topicThe topic this document is assigned to.

Returns

booleanTrue if the object may be shown, false otherwise.

configure (mixed $configuration, int $contextid)

Configures the component for usage.

The configuration is merged, and, if necessary, an existing handler object is purged.

Parameters

$configuration

mixedA configuration data list, suitable for merging with a midcom_helper_configuration object.

$contextid

intThe ID of the context we are associated with.

Returns

booleanIndication success.

get_config_for_topic (\midcom_db_topic $topic)

This is a small helper function which gets the full configuration set active for a given topic.

If no topic is passed, the system wide default configuration is returned.

Be aware, that this call does not check if the passed topic is actually handled by this component, as it is theoretically possible for components to drop configuration information on other topics as well.

Parameters

$topic

\midcom_db_topicThe topic which should be queried, omit to get the systemwide defaults.

Returns

\midcom_helper_configurationMidCOM configuration object

get_current_leaf ()

Returns the currently selected leaf of the request.

Returns

intThe active leaf ID out of the component data storage.

get_leaves ()

Relays the get_leaves call to the NAP instance.

Returns

ArrayAn Array of NAP compliant leaf structures.

get_node ()

Relays the get_node call to the NAP instance.

Returns

ArrayA NAP compliant NODE structure.

handle ()

Relays the handle call to the component.

Returns

booleanTrue, if the component successfully handle the request, false otherwise.

initialize ($component)

Initializes the component.

It will first load all dependent libraries and then include the snippets referenced by the component. The component's local data storage area is initialized and referenced into the global storage area. Finally, the on_init event handler is called.

This should not be overwritten by the client. Instead, use the on_initialize event handler.

see \_on_initialize()

Parameters

$component

Returns

booleanIndicating successful initialization.

reindex (\midcom_db_topic $topic)

This new interface function will initiate a reindex run for the given component and topic.

See the _on_reindex() event handler for details.

see \_on_reindex()

Parameters

$topic

\midcom_db_topicThe topic that should be reindexed.

Returns

booleanIndicating success.

set_object (\midcom_db_topic $object)

Relays the set_object call to the nap instance.

Checks if the NAP instance has already been created beforehand.

Parameters

$object

\midcom_db_topicThe midcom_db_topic that should be processed.

Returns

booleanIndicating success.

show_content (int $contextid)

Relays the show content call to the component, invoking output.

Parameters

$contextid

intThe id of the context we are operating in.

trigger_watch (int $operation, mixed $object)

This function delegates all watched operations, in two phases.

First, the general _on_watched_operation handler is called, to allow for handling generic operations. After that, the individual watches are called, to allow for more specific processing.

Parameters

$operation

intThe operation that has occurred.

$object

mixedThe object on which the operation occurred. The system will do is_a checks against any registered class restriction on the watch.

_check_nap_instance ()

Checks, whether an instance of the NAP interface class has already been created and creates it if not.

This check is only done during the set_object calls, which will always be the first calls in a sequence of NAP calls. (For performance reasons.)

 Properties

 

array $_autoload_files

A list of files, relative to the component's root directory, that should be loaded during initialization.
deprecated This field is provided mainly for backwards compatibility. Dependencies should be loaded on-demand by the auoloader instead
 

array $_autoload_libraries

A list of libraries which should by loaded during initialization.

This will be done before actually loading the script files from _autoload_files.

deprecated This field is provided mainly for backwards compatibility. Dependencies should be loaded on-demand by the auoloader instead
 

mixed $_context_data

This variable holds the context-specific data during processing.

It is indexed first by context ID and second by a string key. Currently defined keys are:

  • config holds the configuration for this context
  • handler The class handling the request.
 

\midcom_core_manifest $_manifest

The component manifest instance associated with this component.

Read-Only and automatically populated during initialization.

 

string $_nap_class_suffix

This is the class suffix used when constructing the NAP handler class.

It is appended to the component class prefix, f.x. resulting in net_nehmer_static_navigation (as a default).

 

string $_site_class_suffix

This is the class suffix used when constructing the on-site handler class.

It is appended to the component class prefix, f.x. resulting in net_nehmer_static_viewer (as a default).

 

object $_nap_instance

The NAP interface instance from the component, initialized on demand.