Page tree
Skip to end of metadata
Go to start of metadata

I discussed with Pascal an idea I have since a long time in my mind about apps within Magnolia.
He asked me to write it down that he and Boris could have a look at it together. So here it is (smile)

Project Creator App


The idea is is basically, that the main structure of a project is created by a wizard like app.
What it would create:

  • The site definitions needed
  • The module itself within magnolia
  • All templates and dialogs as proper extends form STK
  • The physical module structure containing the poms and module descriptors
  • Bootstrapping all the created definitions into the modules

So the final result would be a proper module structure in the file system, containing all the work created by the app, ready to check in and build.


1. Lower Entry Barriers

We are trying with Magnolia Academy to lower the entry barrier for new projects. For people trying out Magnolia the first time.
Also we put a lot of effort into documentation, to make this easier.
But from my experience in training, written information, presentations and movies only help to a certain degree.
The first usage of it is still usually quite hard, because doing something and understanding it are two different things.

2. Project Best Practice

Also we had in the past quite a lot of discussions about the best practice on how to start a project.
Which was not easy to define and is still not in documentation at one single place as a guide line, because to many things coming there together:

  • What IDE you use
  • Do you have Maven knowledge
  • Do you have STK knowledge
  • ...and so on

3. Usage of STK

Some client still hesitate to use STK out of various reasons. Quite often out of "not understanding that STK is not the html, its powerful mechanism useful to any project" reasons.
Providing a project creator app doing a lot of work out of the box, but based on the STK will increase the usage of STK.
Providing a quick creation of projects out of the box, but based on STK, will be a strong counter force of not using STK at all.


I'm strongly convinced, that such a Project Creator App could close all these gaps, being exactly the connector of all this information coming together at one place.
Being asked the right and relevant questions already help understanding what a project builds upon and what steps are done after the others.

Main steps what the app would do

These are just rough steps of the wizard/creator. I'm sure some more thoughts have to be invested into this. More nice possibilities are likely to be found if invested more.

  1. Project and Module definitions
    • Input about project names (for Maven)
    • Input about artifact names (for Maven)
    • Input about module names (for Magnolia)
    • Creation of the module(s) in config/modules in Magnolia
      (will not work without jar, clear, but for having correct bootstrap paths of registered items)
  2. Site definition creation
    • Creation of the site definition(s) needed
    • Input about the site it should apply to
      • Creates the top root node and maps to it.
    • Input about the areas needed site wide
      • Creates the according area configurations
    • Input about the STK pages needed
      • Creates them directly in the site definitions templates availability
      • Creates the basic extends of all these templates in the project modules
    • Input about the languages server content wise
      • Creates the correct i18n configuration
    • Input about the theme that should be used.
      • Creates a basic theme configuration and a theme module. Containing a copy of the pop.
      • Add the mapping to the created theme.
    • Input about the usage of mobile
      • Creates a mobile theme, its sub variation in the site definition
      • Asks relevant questions about mobile related things such as which areas not to use for mobile.
      • Creates the correct sub variation configurations.
  3. Templates & Dialogs creation
    • The base extend is done of each available template by step 2. Now the more granular configurations can be created.
    • Letting parts of the original templates choose in a graphical UI.
      • As we can know by Java reflection exactly what is configurable, the users can be asked in a graphical way what they want to use&not use.
      • Each possible configuration and property can be used with check boxes.
      • The wizard steps create then the according configurations in the template definitions as extend and extends overrides.
    • Page templates extends & configuration.
      • Input about the page templates what should be used specifically.
      • For each template the merged behavior of the site definitions prototype and the current template is shown. Also of course the stkTemplate in between.
      • The additional overwriting properties are added.
      • The needed override extends are created.
      • The area configurations of available components are added for each area.
    • Component extends creation & configuration.
      • Input about the component templates what should be used specifically.
      • After all the page templates are known and their available components, all the used components are known.
      • All extends of the components get added and their registration in the page templates areas.
      • Same algorithm on the component definitions as for the page definitions, ui like choosing.
    • Creation of the dialog extends & configuration
      •  As all page & component that are used are known, all their dialogs can be also extended and being registered.
      • Of every used dialog by pages and components a dialog extends is created, and the new dialog is registered on the definitions.
      • Also UI like the possible controls and their properties can be chosen.
  4. Creation of the physical project
    1. Creation of the physical modules
      • The project structure is created with the Maven archetypes within the file system of the webapp.
      • All needed information was gathered in step 1 of the app.
      • The project folder, parent pom and all sub-module are being created, containing valid pom files and module descriptors.
    2. Extraction of all configurations as bootstraps
      • All created definitions form step 2&3 are exported into the according modules.
  5. A complete project is created and ready to use!
    1. The created project can now be checked in into version conteol.
    2. A first maven built can be ran on it.
    3. It can already be imported into the IDE an the real development can start.

Additional idea:

  • Each step & sub step could always show, what configuration it created or changed -> direct learning effect
  • Each step could supply information according to what has been done right now -> links to the academy movies, links to documentation etc.

That would provide a perfect "coming" together of all this separate information.

Resources estimation for development

Of course a estimation is hard to do.
It depends a lot on to which extend such a app should catch all corner cases.
How fancy such a UI should be, and how backward compatible it should be. Meaning if you can reran such a wizard also on existing projects.
And of course on how many bugs of M5 will appear and contradict the actual development of the app itself such as missing or wrong working functionalists etc.

I would assume:

  • 2 core developers 1 Month of work
  • My coordination of the ideas and technical STK aspects 1-2 Weeks.


I hope you like the idea! (smile)



  • No labels


  1. Christian Ringele please clarify what the proposed application does that isn't already done with a Maven Archetype, and additionally, what couldn't be done with such an Archetype. Also, how do you envision the application to be provisioned? As a Magnolia 5 app? as a standalone Java application? As a web service? An Eclipse plugin? (A maven archetype?)

  2. App -> Magnolia 5 App. An app that is a part of Magnolia itself. Creating a Project out of a running Magnolia.
    It won't be directly deploy able in the running Magnolia, for that it would need a jar in the web-inf lib out of it.
    But with a maven built and a restart this would even be possible

    Maven Archetype: Can only create an empty project hull. The hard thing is to create all configurations. You need to knwo exactly, how things work together.
    For example Site Definition defines the available tempates, defines the areas site wide, defines the available components within the areas site wide.
    Creating a project template you need to register in the site definition, remove the original, needs to extends the right stkPage. Needs then to override the right values site and page dependent.
    This for areas and their components and its dialogs. In dialogs the same -> the only way to know what you can configure is from the documentation and looking into the code, and then you would need to know where to add it -> into the extends, or adding an extends override and so on.
    in other words -> steps 1 to 3 can't be done by an archetype.

    A Maven archetype is creating an empty hull - this app would place everything into it what makes out of an empty hull a real Magnolia project.

  3. There is a potential overlap between the proposed project creator and an improved configuration UI. For instance, it is envisioned that we will eventually provide a graphical form builder that also allows to alter forms at runtime, much like we already can today through configuration. I understand that such a change would also need to be propagated back to the proper dev environment, at the very least by crating a JIRA (or similar) task that contains the relevant changes.

    Also, I imagine that it will eventually be possible to create sites (i.e. site definitions etc) using a graphical UI. In short, it might be possible that such a creator app would reuse existing config apps for some of the work. Thoughts?

  4. Exactly!
    I also think it overlaps with the improved configuration UI.
    Or you could say its a process based on the configuration UI that guides you through these complex configurations.
    A better UI for the configurations don't help you for knowing all the things that work together -> site definitions -> template definitions > area definitions -> component definitions and all their dialogs.
    An all that always in the scope of "should it be achieved site wide or just for a certain page", that has a big impact on where it must be added.
    A nicer UI for configuring a page definition does not necessarily help you with registering it at all relevant places.

    So in other words: The wizard would most preferably use existing UI configurations in their single steps and put them together in the right order. Breaking down the whole process of an project creation.

    Propagating back to def environment:
    I think this is not even needed. Of course that would be nice, but probably a big overhead for not much:

    1. This could be done in a stand alone magnolia from a downloaded version.
    2. The output, the created project in the file system just has to be checked in, and imported into an IDE.

    So the start would be even without an IDE:

    • Download Magnolia
    • Run the App
    • Take the created folder and open it on you IDE.
    • Start it up in you IDE
    • -> Project running.

    Its more in the scope of an initial project creation.
    Later changes are anyhow how hard to propagate back. As soon hard customizations start, there would be many corner cases which I doubt you can all catch.
    And Java classes and scripting have to be done anyhow within the IDE.

    Main gain:
    Anybody has within minutes a running project in their IDE which is start-able and that can directly be used and enhanced.
    A Proper base setup where all the things can be done wrong are from the beginning one correct.
    It can be re-ran many times, so each single step can be looked at detailed and by that providing better understanding.
    So basically the biggest source of frustration, not having anything run-able for days or even weeks, is eliminated.
    One can focus on the implementations, and not the pure project frame setup.

  5. Exactly, got your point about using this to create an initial running project. What I mean by "propagating back to developer" was in the scope of later, configuration UI based changes. (Same problem we have today, if you change something directly in Magnolia instead of your IDE, how do you make sure it goes back to the proper project release cycle). But that is a side note. Or actually not. BEcause the reason I mentioned it is that you might want to keep the initial project creation to a minimum. Maybe you don't yet want to decide or don't know how many languages you use or if mobile is needed or not. If the UI's to add that later would have a way to propagate the changes to the module it would be easy to skip these steps in the beginning.

    Related to that I suggest you define a clear "minimal" set of functionality that would make this tool useful. Limit the scope to the essential. BTW I like the idea of using it also as an educational tool, in the sense of showing a newbie what has been done and where to learn more. Possibly this could be in the form of a generated PDF for later reference.

  6. The base configurations as adding a new language an thing like this could be reran anytime.
    These are basic configurations very unlikely the change in its structure (i18n node in site definition).

    The limitation of rerunning it was more in the scope of custom controls, extended definition classes and so on.

    Extended defintions are hard to map on a default sites prototype, cause we can't guess what the properties the dev has added will do.

  7. Summarized I would say:

    A project creator would be a good start.

    A project maintainer app would be even better on top of it (later) (smile)