In this tutorial you create an app that operates on data stored outside the JCR repository. The app uses the content app framework but stores data on the local file system. This is an example of connecting to a custom data source. Editors don't have to leave Magnolia in order to work on third-party data.
The content app framework allows you to create standardized apps. Standardization makes apps easy to use and learn. Since all content apps look and behave the same way, a user who has used one can quickly learn another, even if the apps operate on different content.
The data that content apps operate on is typically stored in the Java Content Repository (JCR). However, apps can also operate on data that resides outside the JCR. Editing and viewing custom data is a common requirement. For example, editors may need to access product data in a remote ERP system in order to create content to sell the products. Such remote data can reside in a relational database, on the filesystem, in a Web service, or some other data delivery service. For convenience, you want to make the remote data available inside Magnolia in a familiar environment so editors don't need to jump from one system to another.
Read My first content app and the content app framework if you are not yet familiar with JCR-based content apps. In this tutorial you customize an app which requires some Java programming. You need a development environment and a basic understanding of Magnolia modules. You will work with interfaces originating from the Vaadin framework used to build the Magnolia UI. It helps if you already know Google Web Toolkit (GWT).
Create a module
The file system browser app created in this tutorial needs to be deployed as a Magnolia module. Choose from the following options depending on your skill level.
Option 1: Clone the project in Git
Choose this option if you know how to work with a Magnolia project and Git. You get the module code on your local system and can edit it in your IDE.
- Import the project into your IDE. Here's what the project looks like in IntelliJ IDEA:
- Build the project into a JAR and deploy it to Magnolia instance or run the project in your IDE. To run it in the IDE, add the module as a dependency in the .pom file of your bundle, see below.
Option 2: Add the project as a dependency to your bundle
Choose this option if you want to add the project to your own Magnolia bundle. The module code will not be stored on your local system but you can examine it in the IDE.
For the standard Community Edition bundle:
dependencyManagementsection of the CE bundle parent POM file, add a
dependencyelement with a version number. Use the latest version available.
dependenciessection of the bundled webapp POM file, add a
dependencyelement without a version number:
If you use IBM WebSphere or Oracle WebLogic, add the dependency element in the appropriate POM file of the webapp of your choice.
If you use a custom bundle add the
dependency element with a version number in the POM file of your custom bundle.
Option 3: Download the module JAR
Choose this option if you are new to Magnolia or don't have a development environment. You get the complete app and can use it.
- Download the fs-browser-app-1.0.1.jar JAR from Nexus and follow the standard module installation instructions.
- Copy the JAR into
<CATALINA_HOME>/webapps/<contextPath>/WEB-INF/libfolder. Typically this is
- Restart your Magnolia instance and run the Web update. This will install the module.
To create a custom content app you need to implement:
- Container and related classes.
- Custom presenter classes for every view type you want (
Actionclasses to interact with and manipulate your custom content
AvailabilityRuleclasses (if required)
Creating a container
A container represents your data source in Vaadin context. The container provides methods to get, add and remove items and properties in the data source. The container can hold 0 to n items. It might help to first understand Vaadin's concept of an item, see
com.vaadin.data.Item. See also the
Property are important and used heavily in containers.
The interface you have to implement for your container is
com.vaadin.data.Container. If you want to have a more sophisticated container you also may want to implement:
The Vaadin framework itself provides some container implementations which may be helpful for your own custom container. Use them as a source of inspiration or just as a superclass:
File system container
The container class for the file system browser app is
info.magnolia.filesystembrowser.app.contentview.RefreshableFSContainer. The class delegates most of the work to
com.vaadin.data.util.FilesystemContainer which again is a container implementation provided by the Vaadin framework. When creating your own custom container, study the interface and related classes.
Content views and presenters
Workbench is a view that displays a list of content items in a workspace. It is part of the content app framework, typically defined in the browser subapp. The workbench contains at list of content views. Typical view types are tree, list and thumbnail. The workbench also provides a search box; results from search are displayed in the search view.
Your custom app can use the same views as a typical JCR content app such as tree, list and thumbnail but other views are possible too.
To implement a presenter:
Provide a concrete implementation of
initializeContainer()method. This method is a link to your custom container. Instantiate and initialize the container in the method.
Depending on whether you want your custom content presenter to display a tree, list or thumbnail view, extend one of the following:
In the example app we extend the
The code fragment above is simplified. The package declaration, imports and some comments have been removed.
The other presenter used for the fs-browser-app is very similar; it extends
info.magnolia.ui.workbench.thumbnail.ThumbnailPresenter, but the method
initializeContainer() is a little bit more complicated, but still easy.
When you have the custom-presenters, you also should create definition classes:
Now the views can be configured:
The tree above is just a part of the whole configuration of the fs-browser-app. However, it contains the relevant parts for the content views and presenters.
Creating a custom content connector
The content connector is one of the core pieces for the your custom content app with non-JCR content. You need a custom implementation and
contentConnector node in the configuration.
In the fs-browser-app, the custom implementation is
info.magnolia.filesystembrowser.app.contentconnector.FileSystemContentConnector. Its definition class is
contentConnector node of your own custom content app can have more properties. It depends on the implementation of your definition class. Here
FSContentConnectorDefinition has just one bean-property: the root folder. The other property
class comes from the superclass of the definition class (
info.magnolia.ui.vaadin.integration.contentconnector.ConfiguredContentConnectorDefinition). You must always provide the property
class when creating a custom content app.
Implement action classes to operate on custom content
Now that you have a container and a content connector, your data-source is anchored in the content-app and is now ready to be used. As you already know from JCR-related content apps, to work with the items you have to create actions, action definitions and you have to configure the app with the available actions. This is probably now a good moment to update your knowledge concerning Dialog action definition and Action bar definition.
This action does not do a lot. The execute method is only firing an event which leads to a refresh of the content view. Imagine that you have added a file to a root folder which is represented by your fs-browser-app and you want your app to reflect the changes in the filesystem. You can inject the contentConnector into the constructor which is really handy.
The next example shows the typical pattern where the scenario is started with
OpenEditDialogAction and where a dialog must be provided. In that case the custom action
info.magnolia.filesystembrowser.app.action.SaveFileActionDefinition is defined as the commit action in the dialog.
In your custom conten-app you would have more sophisticated action - e.g. you could implement actions to create, update and delete (CRUD) items.
Implement custom availability rules
Availability rules are optional. Generally, availability classes implement
info.magnolia.ui.api.availability.AvailabilityRule, most of them by extending
Note, that the older version was depending on
javax.jcr.Item to compare, whereas the newer version is less strict typed - which allows it to implement availability rule classes for non-JCR related content. The fs-browser-app has such an availability rule class, too:
The rule class itself has a definition class -
info.magnolia.filesystembrowser.app.action.availability.IsImageRuleDefinition - which then is used in the configuration:
In the above tree you can see that it is possible to combine more than one availability rule classes. The 2nd and the 3rd one under the node filename doesn't exist and is just an example. When using more then one class, their results are combined with AND-operator.
Instead of using the class-property, which points to a definition-class, you also can use the implementationClass-property, which then must point directly to the rule-implementation-class,
Now all parts are ready and if not already done - the app can be configured. If you are unsure about how to do that, have a look at Configuration. Some of the details of the configuration have been shown above. To finish, have a look at the screenshot of the configuration of the fs-browser-ap: