This 'how to' may shed some light on the Data Module.

Super-short manual

1. download & build List of Magnolia Modules
2. install Just place in "WEB-INF/lib" together with the scheduler module and the quartz jar (should be all in the "bundle" build)
3. restart Magnolia Now you will find "Data" menu item
4. Create a new type Click on "Data" > "Types", hit the "New type" button at the bottom, fill out the form
5. Create a dialog for the type Click on "Data" > "Config" and add a new dialog. Set it up just like you would setup a paragraph dialog. Make sure however that you leave a "name" field there to identify the data nodes
6. Reload AdminCentral I think you will need to log out and log back in again to see the new type in the menu under "Data".
7. Now you can start entering data.
8. Access the data Setup JCR queries to access the data as you would with pages, dms nodes etc.

The works

Purpose
The purpose of the Data Module is to managed structured data (as opposed to unstructured or semi-structured data commonly used for web pages). The data module  stores content independently of any page structure. To place it on a page, you can retrieve the content from you paragraph/template. In that regard, the Data Module is similar to the DMS, which allows you to store documents independently of the page structure.

Think of a footer text on the Web page. Typically we would create a 'Footer Paragraph" and add it to the footer section in the template script. Since we don't want to author to add the footer text whenever he creates a new page, we will break over head on how to inherit from parent pages. That's where the Data Module comes into place. You can create a Data Module 'entry' and add the footer text. In your template script you can query or reference the footer text. The result is that all pages will have the same footer text and if there is a change, you can do the change in one place, the Data Module, and all web pages referencing the footer text will be showing the same, corrected, footer text.

Some "Use Cases"
As mentioned, the idea is to use the Data Module similar as the DMS, except that we deal with content rather than with files (images, movies, documents). Following are just a few ideas how I am using the Data Module in other projects.

• Boiler Plates: Similar to the "Footer Example" 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.
• Other Ideas: For example the Magnolia list of Magnolia References is driven from the Data Module. By storing the client information in the Data Module Magnolia can generate different types of lists.

What you need to know
There are a few things you need to know about the Data Module before you can get started. If you are not quite familiar with the JCR Content Repository concept, then you might scratch your head figuring out what a Node Type is. Since Nodes, Properties and Node Types are very important to understand the repository concept, I recommend downloading and reading the JSR 170 specifications for more details.
So just briefly: A Node Type is (very) simply speaking, a tag for a node. This will make 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 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. We will look at how to this later.

A simple Example: Footer Text
We will use an example to describe the steps it takes to create a Data Module entry. The idea is to create a 'footer text', which can be referenced by the template script.

1) Installation
The Data Module is part of the Magnolia Installer. If you want to download the Data Module jar file, you can get it here. To install the jar file, stop your Magnolia instance, copy the jar file into /WEB-INF/lib folder of the Magnolia instance, check that this is the only Data Module (so delete elder Data Module jar files) and restart Magnolia.

2) Create a new (Node/Data) Type
You will notice that the Data Module uses the term 'Type'. Technically the 'type' is a set of other Node Types, but on the other hand you can not really talk about a 'Data Type' either. So what you are creating is sort of a 'node tag'.
- In the left side pane of AdminCentral click on "DATA" and then on "Types". You will see the 'example' Type.
- Click on 'New type' in the bottom menu or right-click in the working pane and select 'New type' from the context menu. This will open a dialog where you can configure your new type.
- In this example we will name the new type 'exampleFooter'. Here is a sample:

Name: The name of the node type (use only a-z, 0-9).
Title: The Title will be visible in the left-side 'Data' section.
Icon: You can define an icon which will be displayed for content nodes created with this node type. You can use any 16x16 or 32x32 type image.
Root Path: You can define the parent node(s) under which content nodes of this type will be created. Quite useful if you have different projects with different Web sites and therefore different 'footer' sections. As an example we will place our footer text node(s) under /wiki/datamodule. You can also 'share' these folders among other node types (e.g. you might have a node type 'footerLayout' with the CSS styles as content. A 'footerLayout' node could be stored in a parent folder and below you have the 'footerText' nodes. In your template script you could read the styles ('footerLayout') and the footer text ('footerText') and create the footer section out of individual nodes).
JCR Node Type: You can assign additional node types ('supertypes'). For example you might have a few standard texts (footer text, header text, etc.). To make a query for these text blocks easier, you might create a 'super type' and add that node type to this field. When querying all nodes of the 'super type', you will also get all the nodes of different type, which have the 'super type' as additional JCR Node Type.
Allow Folders: By checking the box you will get a menu item 'New folder', which will help you better organize your different nodes. In our example we just have a footer text, so we do not need additional folders.
Sort by Name: This option will sort the nodes created with this type by the node names. In this example we will just have one node, so it's not required.
- Click Save to add the new Node Type 'exampleFooter'.
 
Note: After saving nothing really seems to happen. However, behind the scenes the node type is registered and the left-side Data menu is extended by the new Node Type. The new Node Type is added to the repository's custom node type configuration. If you check out the configuration file /magnoliaAuthor/repositories/magnolia/repository/nodetypes/custom_nodetypes.xml, you will notice this entry:

<nodeType hasOrderableChildNodes="true" isMixin="false" name="exampleFooter" primaryItemName="">
<supertypes><supertype>dataItem</supertype></supertypes></nodeType>

- Reload AdminCentral and you will see the new menu item Example Footer in the Data Module.

3) Review what the Data Module has prepared for you
Two additional tasks the Data Module has prepared for you:
a) Created the folder hierarchy we specified in 'Root Path' of the Node Type creation dialog. To review click on the 'JCR Browser' entry of the Data module. You will notice a folder 'wiki' and sub folder 'datamodule'. That is where nodes of our Node Type 'exampleFooter' will be added. The JCR Browser is very useful to double-check on the content added to the Data Module.
b) Created a simple content dialog which will be opened whenever you want to create a new 'exampleFooter' type content node. Click on the 'Config (Dialogs)' entry of the Data module and you will be brought to the /dialogs folder of the Data Module. There you will find the prepared dialog 'exampleFooter'. As next we will extend this dialog.

4) Extend the Content Dialog to add Content to 'exampleFooter' type of Content Nodes
The Data Module 'only' stores content, it does not have any sorts of presentation logic (e.g. like a Magnolia Paragraph does). However, content is still added the "Magnolia way" by means of a dialog. So whenever you create a new content node, Magnolia knows which Node Type and therefore which dialog to show.
When saving the new Node Type the Data Module automatically creates an initial dialog. So all we have to do know is extend that dialog. The beauty of the Data Module is that you can create any kind of dialog, same as you do for Magnolia Paragraphs!
For our footer text we will use the 'fckEdit' control, allowing some formating of the footer text.
- Click 'Config (Dialogs)' entry in the Data Module.
- Open the 'exampleFooter' folder, open the 'mainTab' node.
- Add a new content node with the controlType 'fckEdit' and the according properties. You can copy it from the Samples Module (/dialogs/samples-editor/tabContent/content) and then rename the content node from 'content' to 'footerText' and adapted 'label' and 'description'.

Note: There is already a dialog node 'name'. Don't delete it, use it instead! The value you enter in the 'Name' field is used as the name of the new content node you will create later. 

- After you added the 'fckEdit' dialog control, your dialog will look similar:

 
5) Create the 'Footer Text' Content Node
Now that we have the Node Type and the Dialog ready, we can create the content node containing the footer text.

Note: What at a first glance may sound a little unusual, will appear as quite obvious once you created your first content node. You would expect to create a new content node and then select the Node Type (similar as selecting a Template). In the Data Module it's slightly different. You click on the Node Type entry in the Data Module and then you add the new node. The reason is that the configuration (dialog, root path) is assigned to the node type, avoiding that you will have to choose folders or dialogs.
- Click on the 'Example Footer' Node Type entry in the Data Module.
- Select 'New item' from the bottom menu or right-click into the work pane and select 'New item' from the context menu.
- This will open the content dialog we have extended in step 4).
- Enter a name for the new content node and type a footer text (and format as you like).

- After saving the content and closing the dialog, you will notice the new node in the work pane.
Well, you just have created your first content node in the Data Module!
 
Note: Remember when we entered a 'Root Path' when creating the Node Type? Don't get confused if you don't see the folders in the 'Example Footer' pane. What you see is all content below the root path.
- Click on the JCR Browser entry of the Data Module.  Open folder 'wiki' and then 'datamodule'. You will see your new content node and the content properties!

6) How to use the Data Module Content in your Scripts
There are two ways you can access the content stored in the Data Module:
a) Run a query (e.g. Select * from exampleFooter) and iterate through the result set.
b) Instantiate a node object and read the content property values.

You can try out a JCR Query without having to write a JSP. Click on 'JCR Queries' in the Tools Module. In the Query form select repository 'data'. Now you can enter a first simple query: Select * from exampleFooter and then click the 'Execute' button. In the 'Result' window you will see that one node has been found.

Here is an example how you can instantiate the content node and then read the text property:

  final String DATA_FOOTER_PATH = "/wiki/datamodule/Wiki-Example-Footer-Text"; // The path/node within the data module
  final String FOOTER_TEXT_PROPERTY = "footerText";                            // The property name for the footer text

  Content footerTextNode = null;
  String footerText = StringUtils.EMPTY;

  try {
    footerTextNode = MgnlContext.getHierarchyManager("data").getContent(DATA_FOOTER_PATH);
  } catch (Exception e) {
    log.warn(logHeader + "Can not retrieve the footer text from the data module. Message: {}", e.getMessage());
  }

  footerText = StringUtils.defaultIfEmpty(footerTextNode.getNodeData(FOOTER_TEXT_PROPERTY).getString(), " ")

 
7) Using the Data Module with your Custom Modules
As mentioned in the beginning of this post you must register Node Types before you can bootstrap Data Module content (e.g. dialogs or content nodes). This can be quite tricky knowing that your custom module has a 'mgnl-bootstrap' folder where you will put all what needs to be bootstrapped when installing the module.
To make sure your node types are registered before the rest of the bootstrap-content you will need to write a 'ModuleVersionHandler' which extends the 'DefaultModuleVersionHandler'. In that handler you can instantiate and perform installation tasks.

At this point I am still struggling to find a solution that works and can be recommended. Below is an idea from the magic kitchen of Jan Haderka, which I will elaborate on:

   protected List getBasicInstallTasks(InstallContext installContext) {
       final List installTasks = new ArrayList();
       // make sure we register the type before doing anything else
       installTasks.add(new AbstractRepositoryTask("Register node type", "Registers RSSAggegator node type") {

           protected void doExecute(InstallContext installContext)
                   throws RepositoryException, TaskExecutionException {
                   // register a node type here.
           }});

       installTasks.addAll(super.getBasicInstallTasks(installContext));
       return installTasks;
   }

If any one has a solution, please update this post (or let me know). As soon as I have a working example I will update this section.

Your Rating:

Thanks for voting!

Please Wait

Results:

6

rates