Configuration (Magic) Data: Difference between revisions

From IHRIS Wiki
Line 39: Line 39:
=Using Magic Data in PHP=
=Using Magic Data in PHP=
Each node of magic data is an instance of the class '''I2CE_MagicDataNode'''.  The "public variables" of a node are its child nodes.  Suppose $data is a magic data node, with a children named 'my_list' and 'amount' which are parent type and scalar type respectively.  Suppose that the child node 'amount' has value 10.  The children can be accessed in many ways:
Each node of magic data is an instance of the class '''I2CE_MagicDataNode'''.  The "public variables" of a node are its child nodes.  Suppose $data is a magic data node, with a children named 'my_list' and 'amount' which are parent type and scalar type respectively.  Suppose that the child node 'amount' has value 10.  The children can be accessed in many ways:
{|{| class='wikitable' border="1" cellspacing="5" cellpadding="2"
<center>
{| class='wikitable' border="1" cellspacing="5" cellpadding="2"
|-
|-
! Access Method
! Access Method
Line 56: Line 57:
| I2CE_MagicDataNode
| I2CE_MagicDataNode
|}
|}
 
</center>


These are returned
These are returned

Revision as of 11:08, 12 March 2009

Warning:The API for Magic Data has been fairly significantly updated from version 3.1 to version 3.2. Although this article applies to the version 3.2 API, much of it is relevant to version 3.1. See some of the Changes

What is Magic Data?

Magic Data is a mechanism intended to handle dynamic site level configuration data. It is the basis of much of the functionality provided by the Intrahealth Informatics Core Engine (I2CE) including how pages are served and how custom reports are made.

Magic Data is a rooted tree structure with benefits. If you wish you may think of it as the analogue of the Windows Registry for your web application. You may also think of it as a nested array.

There are two parts two parts to magic data. The magic data node class, defined in I2CE/lib/I2CE_MagicDataNode and the storage mechanisms for magic data. You may use magic data without using a storage mechanism, in which case the magic data saved does on persist across sessions. By default uses the following storage mechanisms for Magic Data:

  • Database: The data is stored into a table in the database. In I2CE, this is set to be the config table.
  • APC: The data is stored in to a memory cache provided by apc which persists across apaches session.

As APC is faster, reads are first done from APC. If the data is not found there, it is read from the database. Data is written first to the database and then to APC.

Scalar and Non-Scalar

There are two main types of nodes scalar and a parent node

A scalar node does not have any children. It does have a value which is a possibly empty string. A scalar node can be marked as being localized. In which case the value returned depends on the localization preferences for the user.

A parent node can have as many children as it wants. Each child of a parent node must have distinct names. It does not have a value. It is not localizable.

Names and Paths

With the exception of the root node, every magic data node has a name. For a name, any numeric value is allowed. Any non-empty string is valid as long as it does not start with '__' and does contains the characters:

_-+.0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

Absolute Paths

Magic Data nodes can be referenced by their path which is a concatenation of their names by '/.'

The root node has path '/'.

If the root node has a child with name 'some', it is referenced by the path '/some'

If some is a parent node with a child with name 'thing', then that child is referenced by the path '/some/thing'

Relative Paths

Paths can also be relative. In the example above, if you were at the node '/some' then could reference the other nodes by:

  • './' references '/some'
  • '../' references '/'
  • './thing' references the node '/some/thing'

Using Magic Data in PHP

Each node of magic data is an instance of the class I2CE_MagicDataNode. The "public variables" of a node are its child nodes. Suppose $data is a magic data node, with a children named 'my_list' and 'amount' which are parent type and scalar type respectively. Suppose that the child node 'amount' has value 10. The children can be accessed in many ways:

Access Method Result
$data->my_list I2CE_MagicDataNode
$data->amount 10
$data->traverse('my_list',false,false) I2CE_MagicDataNode
$data->traverse('amount',false,false) I2CE_MagicDataNode

These are returned

I2CE has a root magic data instance which can be retrieved by:

$config=I2CE::getConfig();

Suppose that we magic data set up as follows:

Path Type Value
/ parent NONE
/color scalar green
/modules parent NONE
/modules/modA parent NONE
/modules/modB parent NONE
/modules/modA/favorite_clay_animation scalar Mr. Bill

You may also something similar as:

echo "I like the color " . $config->color . "\n";
$keys = $config->getKeys();
foreach ($keys as $key) {
  if ($config->is_parent($key)) {
    echo "The node named $key under at " . $config->getPath(false) . " is a parent node.  It has children " . implode(',', $config->$key->getKeys()) . ".\n";
  } else if ($config->is_scalar($key)) {
   echo "The node named $key under at " . $config->getPath(false) . " is a scalar with value " . $config->$key ".\n";
  }
}

which would result in:

I like the color red.
The node named modules under / is a parent node.  It has children modA,modB.
The node named color under / is a scalar node with value red.


As a magic data node is an iterator, we can do things like:

foreach ($config as $key=>$node) {
  if ($node instanceof I2CE_MagicDataNode) {
   echo "The node named $key under at " . $config->getPath(false) . " is a parent node.  It has children " . implode(',', $node->getKeys()) . ".\n";
  } else {
   echo "The node named $key under at " . $config->getPath(false) . " is a scalar with value " . $node .".\n";
  }
}

which would result in:

The node named modules under / is a parent node.  It has children modA,modB.
The node named color under / is a scalar node with value red.

or:

$modules = $config->modules;
foreach ($modules as $module=>$data) {
  if ($data->is_scalar('favorite_clay_animation')) {
     echo "The module $module thinks " . $data->favorite_clay_animation . " is a super star!\n";
  }
}

would result in:

 The module modA things Mr. Bill is a super star!

Headline text

Defining Magic Data in Configuration Files

Changes from 3.1

  • Removed the __ from method calls.
  • Relaxed the rules for the names of Magic Data nodes.