midcom.helper.datamanager API

1. Loading a datamanager schema
2. Initializing datamanager with an object
3. Displaying object through datamanager
4. Editing an object with datamanager

To use midcom.helper.datamanager in a MidCOM component, you must first include it in the component's interface class:

// This is in the constructor method
$this->_autoload_libraries = Array(
    'midcom.helper.datamanager',
);

This will make the datamanager library available to the component's other classes.

Loading a datamanager schema

To load a Datamanager schema, you first need to make the schema file, and place it into the component's config directory. Typical filename is schemadb_default.inc. Then define this in your component configuration file config.inc:

// Load a particular schema file by default, can be overridden by users
"schemadb" => "file:/net/example/component/config/schemadb_default.inc",

After this the schema can be loaded in your component code in the following way:

// Load the schema definition file
$schemadb_contents = midcom_get_snippet_content($this->_config->get("schemadb"));
eval("\$schemadb = Array ( {$schemadb_contents} );");

Now your schema array is loaded into the $schemadb variable. Next you need to instantiate a datamanager with it:

// Instantiate datamanager
$datamanager = new midcom_helper_datamanager($schemadb);

if (!$datamanager) {
    debug_pop();
    $_MIDCOM->generate_error(MIDCOM_ERRCRIT, "Datamanager could not be instantinated with schema ".$this->_config->get("schemadb"));
    // This will exit.   
}

Initializing datamanager with an object

If you're working with an existing object, datamanager must be initialized with it. Otherwise you must use the creation mode.

To initialize datamanager, do the following:

// Load an article from the database
$article = new MidgardArticle(1);

// Initialize datamanager with the article
$datamanager->init($article);

After this datamanager will manage the object.

Displaying object through datamanager

Datamanager can abstract the properties of an object, and load it as a readable PHP array. When displaying an article with datamanager, do the following:

// Load article and its extended properties into an array
$article_array = $datamanager->get_array();

// Display the "title" property
echo "<h1>{$article_array['title']}</h1>";

This way you can treat properties extended through the datamanager schema similarly as object's regular properties.

Editing an object with datamanager

Once your object has been loaded into datamanager, it can also be edited with it. For this, you need to call the process_form() method and handle its different return states:

switch ($datamanager->process_form())
{
    case MIDCOM_DATAMGR_EDITING:
        // User is now in the editing form. Load possible user interface things here
        break;
    case MIDCOM_DATAMGR_SAVED:
        // The document has been saved, relocate the user
        debug_pop();
        $_MIDCOM->relocate('/path/to/article/view');
        // This will exit
    case MIDCOM_DATAMGR_CANCELLED:
        // User has cancelled without saving
        break;
    case MIDCOM_DATAMGR_FAILED:
        debug_pop();
        $_MIDCOM->generate_error(MIDCOM_ERRCRIT, "Datamanager failed with: {$GLOBALS['midcom_errstr']}.");
        // This will exit
}

Once you have called the process handler datamanager will handle locking and all the other logic. The only thing remaining for you to do is displaying the editing form in your output template:

$datamanager->display_form();