Customization of Tiny Marbles CMS

This chapter is addressed to developers who have knowledge in Java, Hibernate, Freemarker and Struts. If you intend to customize Tiny Marbles CMS then you have basically the following possibilities:

  • Customization CSS files
  • Customization Freemarker templates
  • Add a new layout
  • Add a new scheme
  • Extending Tiny Marbles CMS

Customization of CSS files and/or Freemarker templates
This customization is very simple for an experienced developer. Take a look at the default.css files in the CSS directory (for each scheme exists a set of CSS files), and take a look in /templates/ at the Freemarker files 'widget_default_show.ftl' (Horizontal tab system), 'widget_flex_show.ftl' (Flexible layout) and 'widget_financial_show.ftl' (Financial theme). With these files you can customize the look and feel of your website very easily. The downside would be, in case you have to update your installation with a new Tiny Marbles CMS release, because in this case you have to merge these files.




Using Eclipse
The easiest way to work with Tiny Marbles CMS is to use Eclipse. Install the wsm manager (wsm), for the dependencies use the Ivy plugin of Eclipse and the ivy.xml of which comes with the wsm project.

Here the link to the Ivy repository for the Tiny Marbles CMS:

Download the complete Tiny Marbles CMS based on the Eclipse project (zip file). Unzip the file, open Eclipse and create a new Java project. Choose 'Create project from existing source' and navigate to the directory where you unzipped the project files. In case you have Ivy properly installed and the path to the Ivy repository for Tiny Marbles CMS is correct all dependencies are now downloaded automatically.

When everything is installed properly your Ant tasks in Eclipse would look like that:



Add a new scheme/layout

The next level of customization is to add layouts or a new scheme to Tiny Marbles CMS. Both you can do without any changes in the existing Java code. You only have to change the configuration, add a new Freemarker template and the related action for that.

Add a new language for the public website
This is simple. Just open the 'languages.properties'-file and customize the following lines (Attention: both lines needs to be changed !):


Don't forget to update the display languages, for instance 'French':

# Display language for English

# Display language for German

# Display language for French

Add a new layout
By default the system comes with a basic set of layouts. In case you need a new layout you should keep in mind, that the layouts should work for all schemes. The next step would to make a decision for which article type you would like to change the layout: for the type 'Article, short' or 'Article, long'. In the template directory you will find the type 'Article, short' in the directory 'html', and the type 'Article,long' in the directory 'news':


Take a look for example at 'team.ftl' or 'dictionary.ftl'. Both templates uses the article type 'Article, short' with the content of the HTML-editor box, but show  adifferent layout on the public website. After creating the new template you have to add this new template to your 'config-properties'-file.  Go to the section 'New handle to article layouts'. There you see all layouts for the three schemes. Add the new layout to the property file like this (don't forget to add these lines to all schemes):

article.layout.default.identifiers = newLayout
article.layout.default.type.html = newLayout
article.layout.default.namespace.newLayout = /html/
article.layout.default.action.newLayout = newlayout
article.layout.default.class.newLayout = org.cws.cms.model.article.version.Html

Now create a new action with the name 'ShowNewLayoutAction' and extend the 'ShowHtmlAction'. Add your new business logic if needed in this new action. Don't forget to add the new mapping to the 'struts.xml'-file. When everything goes fine the new layout appears in the drop-down list of the article categories.

Add a new scheme
By default the system comes with 3 schemes (Flexible layout, Horizontal tab system, Financial theme). If you decide to add a new theme you need to understand that this would be a bit more work. Probably the easiest way is to copy an existing scheme which you like best for your needs. You don't need to change anything in the action part. But what you need to do is to create a new section in /templates/, /view/, /css/, /images/ and /js/ for all new Freemarker template files, CSS files, images and Javascript. Now you need to customize the 'config.properties'-file and the 'freemarker.properties' file (first line). In the 'config.properties'-file you need to add a complete new layout description for your new scheme (underneath the section 'New handle to article layouts'). 

When you update Tiny Marbles with a new release you need to save your new scheme folders, add them after installing the new release and merge the 'config.properties' and 'freemarker.properties'-files.


Extending Tiny Marbles CMS

In case you like to extend Tiny Marbles CMS for instance as a base for a new project, then you should keep in mind that 'Tiny Marbles CMS' is the website manager 'WSM' which includes the libraries: 'Luigi', 'Talos', 'repository', 'webcore', 'MUM' and 'CMS' (and of course all Open Source libraries like Hibernate, Struts, Spring etc ...).

Basically you have three possibilities:

  • Including Tiny Marbles CMS to your project
  • Using Tiny Marbles CMS as a library
  • Using the Tiny Marbles Framework

The first possibility, including Tiny Marbles CMS, is recommended if you only like to customize the website manager (WSM)  to your needs. You can add new features and new business logic using the underlying Tiny Marbles Framework (for example to create a new shop system). The downside of this appraoch is the update. In case a new release of the 'WSM' (= Tiny Marbles CMS) module appears you have to merge your project with the new 'WSM'-release.

The second posibility is to use Tiny Marbles CMS as a library (as a jar file in your classpath). This way is recommened if you like the CMS as it is (no further customization of WSM planned) and you would like to add your new business logic (for instance the shop system) using the underlying Tiny Marbles Framework. When a new Tiny Marbles CMS release appears, updating is no problem. But the customization of the CMS system itself is not as convenient as in the first possibility. 

The third possibility: Use the complete Tiny Marbles Framework ! For this you have to install the complete Tiny Marbles Framework in Eclipse. In that case you have access to all features of the complete framework: 'Luigi', 'Talos', 'repository', 'webcore', 'MUM', 'CMS' and 'WSM'. Certainly a challenge and only recommended for experienced Java developers, but you will have access to a very well organized Java code and a stable framework. The downside: you have to manage somehow the update in case new releases are published.