Would it be possible to have the inherit define the levels, or have an option to hide/show an inherited paragraph?

I like the direction this is going. It seem like it should result in cleaner, easier templates, while at the same time providing richer functionality. Nice work!

It does seem at some point like adding more functionality may have potential to break MVC, and have logic creep into the Freemarker code. For example, does exposing the method calls on JCR nodes allow you to update JCR content, or make unit testing your Freemarker templates harder? (Probably a minor concern, but it occurred to me while reading through this.)

Topic: Area - Paragraphs to add:

1. Paragraphs in Areas should have an 'enabled' flag (info.magnolia.module.templatingkit.templates.ParagraphConfig bean right now)

2. The paragraphs should be placed into a Map and not collection (most preferable a LinkedHashMap for keeping the original order) so:

• They can be added only once
• While merging def's a site def defined paragraph can be overwritten and there fore being disabled. That does not only count got STKs def mergin, it alos applies to the 'ectends' possibilies and mechanism.

3. Not only 'role' should be defineable on the Paragraphs (and the Templates and) availability, but also Groups (and Users). Mainly groups, cause it a complete group should be able to add it, its possible the a group is defined by many roles. You would have to add all of them to fetch for sure all according groups.

Topic: Area - Creating singletonParagraphs

Wouldn't it make more sence to implement a default case on Area:

• Auto Generate Paragraphs -> you can just define paragraphs which get automatically generated
• And then on top of it the special case/more specific case -> singleton of a auto generated paragraph

I have bit trouble to understand the singleton ideology when more than one paragraph is generated. Does that mean, that you can define more than one, but only one of each?

If so that would mean for me, that the general case is configurable as such on a area:

Area/paragraphs/concreteParagraphToAdd/option1=paragraphName

option2=isAutoGenerated

option3=isSingleton

And the is singleton just prohibits, that the newBar allows to add the same type again.

The newBar:

1. Just contains all paragraphs with no property 'singleton'
2. Only shows up at all, if there is a praragraph without 'singleton'

-> adding one paragraph with 'singleton' -> just creates it and no new bar appears

-> adding a second with 'autoGenerate', will be auto generated. A new bar appears, but only the second is addable.

Another question that rises here is:

Are autogenerated paragraphs (and singletons) movable over the edit bar? I think they shouldn't.

General note on Map vs. Collections in beans:

I think all collection nodes definable on templates and paragraphs should always be Maps and not Lists or Collections. So the same item can't be added twice.

So on pobulation of the beans map you get automatically overwrite of already predefined configurations.

Topic: Functions

• getArea(paragraphContentNode) -> find out in which are the paragraph is located (think of subsub paragraphs)
• getAllAreas(pageContentNode) -> return directly all area collection nodes of a certain page node.

So you could do in a paragraph: getAllAreas(page(paragraphContentNode))and having a list of all area collection nodes

• getAncestors(paragraphOrPageNode) -> returns all page nodes of the ancestors (only page nodes)

Topic: Content Expressions:

• the @name and @handle is very usfull too
• @metaData would be nice for directly accessing the metaData itself for rendering (modificationDate could be useful) -> @metaData.templae , @metaData.activation and so on

Topic: Common attributes for passing the content to use:

Do you mean by workspace the Area? Or the JCR workspace?

Topic: Inheritance ordering:

To your question of ordering the collections:

You wrote, that the paragraph will have by default an injected edit bar.

Couldn't be injected a different edit bar on inherited parahaphs so:

• It knows the complete merged inherited collection
• It only provides a move node
• When moving, it stores on the paragraph a property or even a MetaData value 'ordered before' or/and 'orderedAfter' containing the uuid of the nodes before and after.

So when the inheritance tag is collection the nodes, it can reorder them if the uuid is a part of the complete merged inherited collection

Topic: Templates and Paragraphs in the same registry:

I personally don't think thats  good idea, even I see the benefits of it. The cons:

• You can't register a paragraph and a template with the same name
• Its now seeable to users, if it is a template or a paragraph, what leads to creating substructure -> next point
• We already have quite deep subsctructures of the paragraphs, so i guess it would become even more confusing/harder to find a element
• If there wouldn't be a substructre on the as first subfolders as templates & paragraphs, you don't see in extends property what you're extending
• If creating as best practice substructure on the as first subfolders as templates & paragraphs, then I don't see the gain compared to having them on top level in the module definition.

Probably I understand it wrong, and you mean its just one Registry, but still they are defined separetly on the module's level, but just registered by the same ManagerRegistry.

Then its a good Idea I think.

Topic: Templates and Paragraphs in the same registry -> more extendet paragraph definition

I assume, that we still register paragraphs in the module's paragraphs node.

The I would suggest having in the paragraph definition a more extendet configuration for making them interchangable within different collections. Mostly they just differ in two things:

• Differend parameters
• Different dialog

As the template will have a specialized config as a Map of Areas I would suggest something similar on paragraph level. A Configuration of the areas where it can be added, which acts a a subTemplate (paragraphs def meant) definition for the accoring area.

The paragraph def itself is the default, used for every area if not defined different. But then you can ad into a node as subTemplates, fore example:

• subTemplates/areas/main
• subTemplates/areas/extras

There you just define for example a differen dialog for subTemplates/areas/extras/dialog

So if added to the mainArea, it will pick up this dialog, and so on. This is comparable as a implicit extends mechanism.

I think subTemplates should be implmented for paragraphs too (which I think is planned) so the same config could be used for the area definitions (areas where it should pick up the subDefinition, not where it can be added, that on the templateDef/areas).

Actually I would suggest such a general base config:

paragraphDefinition/subDefintions/mimeTypes/

paragraphDefinition/subDefintions/areas/

Replacing subTemplates/mimeTypeName to subDefintions/mimeTypes/mimeTypeName

Topic: Rendering Context Object:

A dynamic mechanism of defining what additional context objects can be provided to the template scripts. Right now if you wan't to provide an additional rendering context object, you need to extend the renderer and register it. But that means that all standard components which use the former renderer don't know anything of it.

So on the RenderableDefiniition (and therefore in stk in prototype), it would be nice to configure something like:

• theRenderableDefinition/contextObjects/additionalObject  (contains the class property)
• The renderer can pick that up dynamically in the setupContext() method this config value (which in STK would be a merged one) and adds the objects to the context

Topic: Areas in TemplateDefs:

Generally I like this concept a lot! A question I want to rise here about that:

Shouldn't then a Area class contain a Map of Areas again?

I know this sound cumberson and unmanagable/hard to understand and keeping the overview.

But if you think of STK's etxras area. What we have there is actuall a top Area, and the two additional Areas again.

An Area in a Area you can compare, as having a paragraph with a collection of paragraphs, just htat the paragraph istself is not rendering anything but is enable-able and is scriptwise on page level (page freemarker includes).

Philipp, have we thought about namespacing definitions? This could address some of Christian's concern. One could reference a def without namespace, falling back to "the first", or an exception thrown in ambivalent cases.

(the "namespace" would be the module's name?)

Christian, regarding duplicate names - if 2 modules register the same name, yeah, that's a problem. Perhaps addressed with namespaces. If it's within one single module, the fact that names have to be unique is probably a good thing, to avoid confusion.

I'd like to give my comments to the above proposal. We have been doing extensive work expanding magnolia for our customer in some of these areas, so I think I have some experience to share, and of course also a vested interest in what happens here, since it has to do with the future compatibility of our extensions.

Areas

I like this idea a lot. It's a logical generalization of the STK concept of Areas. Storing the areas in the template definition in a map is a critical improvement. Removing the STKs fixed idea of what areas make up a website will also greatly improve the versatility of the STK.
One difference to think about is that so far, areas have been handled "inline" (using #include), while paragraphs are normally handled in their own rendering context (using @cms.includeTemplate). I'm guessing that Areas will be able to have model-classes, like paras and pages, and so areas will in future have to be handled in "their own rendering contexts" (like paragraphs). This will have an impact on template design.
Will the areas be associated with a node type, the way paragraphs are associated with a mgnl:contentNode, and pages with a mgnl:content? Maybe mgnl:contentArea? Or will areas be without their own node, as they can be at the moment?
Will there be direct Area acess, in the same way there is direct Paragraph access?

Aligning Paragraphs and Templates (and Areas)

is a good idea! Do it. While you're doing it, add the subTemplate functionality to Paragraphs and Areas as well as Pages, subTemplates are useful.

Tags / Directives

We have created a complete set of CMS-Tags, implemented via freeMarker Directives, building on the ideas in the currently unfinished "templating-components" module.
Our goals for our implementation included:

• Improving the Look & Feel of the templating components (we added icons, a prettier design, the possibilty to set more labels and tool-tips)
• More powerful components (we have pop-up menus, drag-n-drop support for moving and sorting, moving between different container nodes)
• Extended Front-End editing features (we can create new pages, move pages, delete pages, activate and deactivate all from the front-end)

The reasons for these goals were:
Our customer's editors are not trained specialists, and the backend was deemed to complicated to learn. With our extended templating components, we can create front-end UIs that more or less guide a completely inexperienced user through the process of creating content.
Implementing the CMS-Tags as Freemarker directives was no problem at all. It is somehow much nicer to work within freemarker templates using the directives, rather than the JSP Tags.
Aligning the tag-attribute names is certainly a good idea - having to write "contentNodeCollection=" each time (when "node=" would be sufficient) really drives me crazy!
The directives you propose look interesting, but I think there are still some flaws:

• Providing automatic "bars" for the area and paragraph tags seems like a convenient idea, but I don't think it will work well in practice. Experience has shown that it is imporant to have control over the placement of the bars, otherwise the GUI can be hard to understand for the user. An example: A paragraph can contain quite a lot of HTML code that just renders decorative borders, etc... around the actual text content. For useability, it is important that the edit-bar be placed next to the text to be edited, within the decorative borders, otherwise it can be unclear for the editor what button edits what content.
• cms:render - make the template script optional. If not provided, use the native script according to the type definition. Also consider allowing "inline-templates", eg: [@cms.render node=something]
  ... inline template goes here ...
  [/@cms.render]
• cms:iterate - providing iteration in cms:area is ok, but what if I want to iterate over a different collection than an area? cms:iterate and cms:render would be essentially the same, with the difference that cms:render operates on the target node, while cms:iterate operates on the set of children of the target node.
• cms:adminScripts - provide a tag to render the required admin-scripts, so that they can be rendered in the page-header, rather than the middle of the page.
• cms:publicOnly, cms:adminOnly - these are useful shorthands!

Another comment: in your current proposal, it is not clear how the move function will work? I take it that whether move is shown in the edit-bar in some way depends on being within the same area tag?

Inline Editing

A good idea, and logical extension of the current functionality.

Inheritance

These ideas seem good. Consider providing two kinds of inheritance:
inheritAll()  --> like the current functionality: content is inherited from ancestors, and aggregated into a list. Result is all such named nodes in the path to root.
inheritFirst() --> inherits only one such named node, the first one found when traversing ancestors towards the root. Similar to inheritAll()?first, but more efficient.

Ok, that's my 2c worth for the direct feedback. I will include abother post below, with some additional ideas at a more general level.
Richard Unger

Templating-Components-API

As mentioned in my previous comment, we have developed considerable extensions to the magnolia templating components for our customer. With the current proposal, we are of course concerned about the future compatibility of our modules.

In creating our customized templating components, I noted that currently there is a lack of a clear API via which the templating components talk to the rest of magnolia. Essentially, once it is rendered and displayed on the front-end, for a templating component (like an edit-button) to get something done, it currently has to make use of one of two "hooks" into magnolia, neither of which is a "clean API", and neither of which is "stable".

These are:

1. The cms-InterceptFiltor  - configured in the magnolia filter-chain, this filter reacts to certain (undocumented) get-parameters in the request, and performs content-manipulation tasks like "move", "delete", activating preview mode, and similar.

2. The "javascript.js" javascript functions, also dialogs.js. These javaScript files provide convenience functions which take care of opening dialogs in pop-up windows (needed for "edit" and "new" buttons) and also provide the javaScript "GUI" code to highlight buttons, implement the move action, etc... These javaScript files are shared with parts of adminCentral, and can contain nasty interactions with the content javascripts. Also this javaScript API-layer is not documented, and not stable.

In addition, the templating components use the MgnlContext, the AggregationContext, RenderingEngine, Request-Attributes, etc... - these generally availabile APIs are also available, and used where necessary.

Proposal: Create a clean and stable API for templating components in magnolia.

This would allow different implementations of the front-end GUI to co-exist in the magnolia world, and would provide security for the investments made by your customers in customized GUIs.

The API would build on what exists today, and formalize it into a stable and general API.

The API would have a request-based interface, handled by the InterceptFilter.

API functions would include:

MOVE

Parameters: 

• node (source node to move, it must exist), 
• newParent  (destination parent node, created if not existing, optional, default is same parent as source),
• orderBefore (for sorting, source will be sorted before this node, optional)
• orderAfter (for sorting, source will be sorted after this node, optional)

DELETE

Parameters:

• node (node to delete, it must exist)

UPDATE (for inline-editing)

Parameters:

• node (node to update, it must exist)
• property (property to update, created if not existing)
• value (the new value to set)

OPENDIALOG

Parameters:

• name of dialog
• additional parameters as required by the specific dialog

OPENPAGE

Parameters:

• name of page
• additional parameters as required by the specific page

I don't think much more than this would be needed.

Additional Comments:

MOVE and DELETE can operate on contentNodes or on pages. If moving pages, destination-parent must also be a page.

Except for OPENPAGE and OPENDIALOG, which only make sense when you want to show the resulting dialog window, all other commands can be called in an "AJAX" mode, which only returns success/error information. Alternatively, the commands can be called in "normal" mode, which re-renders the page content as the response.

In Magnolia 5, OPENPAGE and OPENDIALOG will probably be replaced by something like OPENVIEW which opens the given Vaadin view.

Combined with your suggestions for improving the templating mechanism I think such an API would be a very nice feature for magnolia, and open the door to interesting new front-end GUIs for the editors.

After some confusion I renamed the singleton area and use now the term "slot". An area is of type "collection" or "slot". This allows us to define more types if neede.

The directives/tags and the functions need a different name so I felt back on cmsfn for the functions. This is a bit uggly but I have not found a nicer solution. 

cms:render

If passing a node to render, why the script has to be passed. Is the definition not stored in the metadate anymore? Probably I understand it wrong. As an optional value its really nice, but if mandatory not.

I big plus of rendering magnolia content is that you can render it, without knowing what the script it to render it with -> fetching some target node and you can just render it.

topic functions:

parent(content, [type])

children(content, [type])

would be nice, if both could be used without a [type] -> when no type passed, the type of the passed content is taken.

Here are a few requests I often get from content authors:

1. Ability to copy a paragraph from one page to another. Basically, they want a copy button, along with the move, edit and delete buttons. Once the paragraph has been moved to the new page, it's content should be editable without effecting the original content that it was copied from.
2. Related to copy, and the inheritance discussion, ability to reference a paragraph (think alias) in another page. This would help with content reuse, like inheritance does, but with out the hierarchy rules of inheritance. If the original content is edited, all references would be updated. Magnolia already has the reference node available for dialog configuration, etc. in the STK. UI wise, content that is referenced should be marked as such when in edit mode (maybe something like the alias arrow in Mac OS X could be used). There should also be a button available in the editBar to create the reference from the original paragraph. Additionally, similar to the current dependencies tab, content authors should be able to view a list of all pages that refer to a particular paragraph. Developers should be able to configure whether content can be referenced, perhaps a referenceable node with a boolean value in the {{paragraph/template def)?
3. Undo/Redo - Opps, I didn't mean to delete that paragraph

It would also be nice to see a list of all pages that have existing content that use a particular paragraph/template def. This would help with testing and refactoring. For instance, if I update this paragraph definition, what pages do I need to look at to verify I didn't break something?

what is the difference between a slot and a paragraph? If a slot can hold only one paragraph, where an area can hold many, somewhere the semantics of these words don't add up. Either you have an area, where all paragraphs are in slots, or you have areas where all content are paragraphs, and some are collections, some are not. The idea to call a single paragraph slot instead of singleton-paragraph is confusing for me.

Another point:

For the template variants, you mention that json and xml variants will be always available.

Please make sure that these can be easily deactivated, it would be a definate No-No for us to permit our end-users to export arbitrary content as XML as JSON.

It's a nice feature, but needs to be disabled by default on the public instance, IMHO.

cms:render and other tags

It would be great to have more flexibility here. You permit passing the content and the template (definition).

• How about making the model class a parameter as well?
• Or also the template-script (as opposed to the definition)?
• It would be cool to be able to pass the "template-variant", ie to include content rendered with a different variant than the parent.
• Or how about making all the fields of the definition "overridable" in the render tag?

Also, I express again the usefulness of inline-templates: allow specifying the freemarker code inline in the render tag. It's a really useful feature, mainly for debugging, but also to render some content with an alternate template, without having to create a whole new definition...

Can somebody tell me how to properly get the property value of an inherited (string) property?

[#assign visual = cmsfn.inheritProperty(content, "visual")]
Visual: ${visual!""}

does not give me the value, neither does ${visual?string!""} nor ${visual.value!""}

${visual.string!""} gives me something what looks like the path to the property, but not the value: 

Visual: property /mypage/visual

${visual.value!""} gives me:

Visual: org.apache.jackrabbit.spi.commons.value.QValueValue@db251769

How to get the value from the QValueValue object in a freemaker template? I already googled for it, but ${visual.value.string} nor ${visual.value.value} does not work.