Many days passed into the land since I have posted the last time. But now I think it is time to become a bit noisier ;-) I will try to assemble useful information about magnolia 4.0 and the new STK (Standard Templating Kit)
Doing so I will keep the interested audience informed on this blog. So don't hesitate to depose questions here.
One of the first things I plan to do is to make a kind of kick off screen cast.
So lets go!
Subscribe to:
Post Comments (Atom)
Posts
2 comments:
Here we go:
I'll provide my questions within a small report of my journey to the centre of magnolia's world. This may give you a chance to better understand and correct all my misunderstandings.
After having clicked on two pages of the demo project seeing the STK at work (being supersonic here) I want to create a new custom template for my module: A subscribe form for a newsletter. It should fit into the STK and produce STK-like HTML (reusing themes for STK).
Since a documentation is leaking starting with the new magnolia4.0 STK is far from being supersonic. I'm moving more like a shell, digging my way through the ground of source code, filtering out small pieces of information.
First of all I really like the new way of defining a page structure. Not on the jsp template any more but in the template definition space in the module configuration part. Admin central becomes kind of simple schema editor for structured content. Go on this way.
To create a new template I just copied a stk template to the template folder of my module. I choosed 'stkForm' and copied it to myModule/templates/newsletter.
Now I had a look on the template config options. Many! And here I hit the ground with supersonic speed. To understand what I'm doing with these parameters (node data) I need some background information about the ideas behind your templating architecture. What I found an guessed:
- category: ?? sounds interesting. Is it linked do page structure, navigation, site structure? What can we do with this?
- subCategory: interesting again. How to use it?
- class: Obviously a model class for a STK page providing access to page components (areas) like navigation, breadcrumb, header, mainArea, extrasArea, footer... and other config parameters like category, subcategory. Why do you hard code part of the page structure here? Developing extensions seems to be a time consuming issue relaying on a new, undocumented and probably instable api (please tell me that I'm wrong :-)). Which classes does the stk provide and what are they used for? Basically I see classes for all the supported page areas (see below).
- dialog: OK, the well known dialog that specifies which (editable!) properties we have for this page. Seeing this I learned that there are configurable and editable properties. Looking into this dialog I see that we can use references to other dialogs. Is this a nice new feature in version 4.0?
- i18nBasename: I'll provide the base name of my module localization resource bundle.
- modelClass: ops - another class. Why do we have 2? Many methods look quiet similar. What is the difference to the other class? What options do we have here and what are the implications?
- templatePath: the webapp path to the template file. If we store the template within magnolia, what should we provide here?
- title: clear
- type: the template type - but in which context? What types do we have? If there are others than 'stk' how to use them?
- visible: toggles the visibility but in which context? In template select box in website repository?
- any other config options?
- breadcrumb: toggle on/off the rendering of a breadcrumb navigation, right?
Looking into the page structure I learned that templates can be structured into areas like header, mainArea, footer... . Basically such an area seems to be just a sub contentNode of the page/template node with some configuration settings and optional sub contents. And it is backed by a model class. Thus we cannot easily declare new areas, right?
What kind of areas are supported?
What config parameters do we have and what options/values do they accept?
What are the ideas/concepts behind the areas and all the config parameters?
What are the default values?
I think, it would be a good idea for a demo project to provide ALL allowed parameters for all nodes with a (default) value. This is verbose but can help saving days of reverse engineering.
What I see is, that there are probably different kinds of parameters. Their intention I guess as follows:
- 'general' config parameters
-- class: Some kind of content model class?
-- template: OK, the template to be used for rendering some kind of frame for the sub contents
-- extreTemplate: ?? a simple alternative (template only) if no class, sub contents and template is given; A configuration option for 'static' (not edited - automatically generated) content like HTML header, navigation... ??
-- more?
- template parameters: controls the rendering
-- editable: ? a flag denoting if the value should be changeable by the authors ?
-- showSectionHeader: controls rendering of section header?
-- floating.columns: ?
-- floating.enbled: ?
-- opener.enabled: ?
-- more?
Finally we can declare the paragraphs that may be added into a page area. As far as I understood this depends on the model class given for the page area. Using info.magnolia.module.templatingkit.templates.SectionMainArea for example allows to declare a choice of paragraphs within stkSektion/mainArea/paragraphs. Using info.magnolia.module.templatingkit.templates.SingletonParagraphMainArea just allows adding one paragraph.
What are the configuration options of the various area classes?
Can we add paragraphs directly to the page, outside an area?
What about some more advanced schema editing options like
- declaring a sequence of paragraphs?
- declaring a sequence of choices?
- declaring the cardinality of a paragraph (or a choice group) e.g. making a paragraph mandatory or restrict the number of teasers on a page to stop amok running authors?
Since the configuration options depend on the backing model class of the area (page, paragraph?), why not automatically generate all allowed sub nodes with their default values?
OK, this is RC3 of version 1.0 and what we already have is a great step forward. It makes me dreaming of more to come...
Opening eyes again and looking on my new custom template, this is what I have:
- a copy of the stkForm page
- adapted i18nBaseName
- changed title (using a localisation key)
- changed singeltonParagraph in main area: using a simple stkTextImage
This works fine without understanding much of what I have done. But the main task - adding a form paragraph with a custom form action - is still open.
Best regards
Wolf
Hi Wolf
I will try to answer your questions step by step in my blog. Once you have created successfully your custom form I would appreciate if you could add a cookbook page to the wiki [1] (nothing sophisticated, a bullet list is enough).
[1] http://wiki.magnolia-cms.com/display/DEV/Standard+Templating+Kit
Post a Comment