Data

Overview

The Data Module also provides functionality for automated import of external data which is specially useful for exposing the data from the other internal systems like warehousing or CRM solutions in Magnolia. Using the Data Module as an intermediary storage for the imported data allows to introduce the single point of entry for such data which can then be used from the web pages in an uniform way, same as any other Magnolia content. It also allows for post-import editing of the content to further improve automatically imported data in case they are not always directly suitable for publishing.

Usage

• Boiler Plates: You can define multiple text modules which can be referenced either within the template script or through a simple "Reference Paragraph".
• Look-up Tables: Another widely used concept are so called "Look-up Tables". E.g. you can define a folder "US States" and for each state a node with properties like "abbreviation", "state name", "size of state" and more.
• Product or manual catalogues for e-commerce solutions
• Other Ideas: For example the list of Magnolia References on Magnolia's website is driven from the Data Module. By storing the client information in the Data Module Magnolia can generate different types of lists with different amount of details displayed from same set of data.

Just a brief explanation here: A Node Type is (very) simply speaking, a tag for a node. Node Type makes it easier to search "for nodes of type 'myNodeType'". Once you understand the reason why the Data Module starts with creating a custom Node Type, the rest should be straight forward. Another important note about Node Types. Node Types have to be registered before they can be used! While this is done automatically when you create a new Data Module entry, installing a custom module (using the Data Module) will need you to first bootstrap the custom Node Types before you can bootstrap the config and content nodes. The module provides a special install task to do this and it will be explained in more details further down the page.

How it works

Node Types

The "New Type" dialog (below) pops in and the type can be defined.

    @Override
    protected List getBasicInstallTasks(InstallContext installContext) {
        final List<Task> installTasks = new ArrayList<Task>();
        // make sure we register the type before doing anything else
        installTasks.add(new RegisterNodeTypeTask("RSSAggegator"));
        installTasks.addAll(super.getBasicInstallTasks(installContext));
        return installTasks;
    }

Dialogs

Controls

Same as with other controls and dialogs also in Data Module the custom controls can be used. The important part to remember when writing custom controls for Data Module Node Types is that if such custom control is creating more complex structure underneath the Node Type, the Node Types of the sub nodes need to dataItemNode in order to get activated as part of the content of given type. In case this is not possible the activation command needs to be adopted to deal with the fact. Read on further to find out more about commands in Data module and activation related details.

Commands

Installed commands are divided into two catalogues. The dataType catalogue contains commands specific to the Node Types definitions and the data catalogue contains commands common to the all defined types. dataType catalogue commands are

• delete commands ensure that all the structures defined at the time of creation of new type (dialog, tree, sub menu entry) are deleted together with the type
• importData command allows for manual invocation of ImportHandler of choice directly from the toolbar of the Types sub menu. The ImportHandler can be specified in product/importer entry of the command. The value specified here has to match one of the ImportHandlers defined at config:/modules/data/config/importers

• activate Activates a content from Data repository. The node of given custom type and all it's sub nodes of type dataItemNode are configured as one piece of content and will be activated together. Sub nodes of any other types will not be activated together with the content.
• import The default ImportHandler invoker. This command will try to find the importer definition matching the name of the type at config:/modules/config/importers. If such matching importer is found, it will be invoked. If not the command will delegate to the importData command.
• importData Same as this command in dataType catalogue, when called command will try to invoke importer specified in its sub node product/importer.
• activateAll Activates all the content including all the sub content. This command may be optionally called by ImportHandler.
• deactivateAll Deactivates all the content in given path. This command may be optionally called by ImportHandler.
• deleteAll Deactivates and deletes all content in given path. This command may be optionally called by ImportHandler.

Import Handlers

Import handlers are special tasks supported by Data module that can be invoked periodically to synchronize data in Data Module repository with external data storage. The import handlers, as the name suggests, are meant to import content into repository, rather then export it. Optionally import handlers can be configured to activate all the changes to public instances after finishing the import run.

Import handlers are configured in data module under config:/modules/data/config/importers. Each entry looks like shown below.

Hierarchical Types

It is an extension which exposes more of the underlying content repository functionality to the user. Previously, the data module was capable of handling any sort of custom content types. But so far there was only one level of such types and any sort of dependencies have to be either incorporated directly in the type, or maintained separately and linked together. With hierarchical types, it is possible to to build a types that are more realistic and more closely aligned to the business needs. One example to show this. Imagine using Data Module to store a information about various companies. For the sake of the example, let's say we are concerned with storing only some simple info about different departments in each company and employee information. Prior to Data Module 1.4 such scenario could be solved by creating "Employee", "Department" and "Company". Then for each instance of the Type company we would use the multiselect control to specify whatever departments or employees we would want to list under the company. While this is doable you can quickly see shortcomings of such solution - same name collisions, no way to see which department belongs to which company without actually opening the dialog, etc.

As of Data Module 1.4 the same scenario can be solved with the hierarchy of the types. The main type "Company" remains as before, but for this type we create 2 sub types - "Department" and "Employees". This is done simply by selecting the main type and clicking on "New Type" in the toolbar, or in the context menu. Since we want to also distinguish different kinds of employees, we create 3 distinct sub types for the "Employee" type: "Director", "Manager", "Developer".

After reading the above, one might ask why the "Department" type is defined directly under the "Company" while the employees are grouped in the sub type. This is a valid question and there are no hard rules. In general if you expect many different instances of the subtype, it is better to group them so they can be split if necessary, while if there are only few instances expected, it is easier to keep them directly under the main type so user doesn't have to browse through too deep a type hierarchy.

The details of each type creation.

The only difference between main dialog type and sub type is the fact that one can't select Root Path for the sub types, nor can one change "Sort Items" or "Allow Folders" setting.

After defining the types as described above, the instance of such type might look for example like the one shown below:

The creation of the instances of types, no matter whether flat or hierarchical, have not changed. Just select the folder in which instance of given type should be created and click "New Item". To create instance of the subtype in it, select the instance of the main type and click the "New Item" again. If there are more then one sub types that can be chosen at given level, the selection dialog similar to selection of paragraphs will be displayed letting user choose which sub type to create. The amount of instances of given subtype is not limited in any way.

The screenshot should be self explaining. Ability to assign different icons to each of the subtypes further helps to visualize the entries. Also as I mentioned above, there are 2 different instances of the "Employee" type - Permanent and Temporary to further aid working with the tree (Imagine the company had 100+ employees). You can also see the other advantage of such structure I mentioned - looking at company, I'm always interested at different departments in it, and so i see them directly when expanding Company tree item, however I'm not slowed down by the need to fetch all the employees either. This way comparing departments in too Companies visually is still possible.

Known Limitations of hierarchical types implementation:

• Each type or sub type is a separate content type in the underlying repository, since the repository requires the type names to be unique, it is not possible to have sub type of the same name in multiple main types.

Examples

• Advanced Data Module Example (Not publicly available at the moment.)
• Footer Management Example

• RSS Aggregator
• Categorization
• ETK (Contacts)