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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

GREYSimplification of our current tag library. See MAGNOLIA-2993@jiraGREY

Rationale

The current tag library has a few shortcomings:

  • too complex to maintain (complex inheritance logic, ...)
  • too complex to use, in part due lots of legacy (naming (paragraph, dialog), usage of now mostly irrelevant concepts such as nodeCollectionName, ...)
  • not useable outside the context of JSP templates (we're lucky that FreeMarker provides support; support for other templating engines would require duplicating everything that's in those tags)

We need to provide solutions for this; we will most likely deprecate a bunch of the existing tags in favor of new ones.

Goals

  • Whatever we introduce should still make some sense with Magnolia 5 (underlying implementations will be changed/swapped, but the templates should ideally be 1:1 compatible)
  • Easier support for other templating engines than JSP tags;
  • Hide underlying complexity: provide a sensible, simple API, with "good defaults"; can be wrapped for Freemarker, JSP tags or any other kind of templating engine.
  • Extensibility: Corner cases that are currently possible to reach, by accident or not, will probably be not supported. On the other hand, it should be easy to extend/replace/add functionality such that such corner cases can provided for on a case-by-case basis.
  • Deprecate current tags, at least those we provide a direct replacement for.
  • Lastly, we should have a look at the (generated documentation). We currently have 2 different formats that document the taglib; neither is great. We should stick to a single one, and improve it. (for ex: http://dev.magnolia-cms.com/ref/latest/magnolia-taglib-cms/tagreference.html has some html tags in the attributes' description which should not have been encoded)

Details

Targets

Our primary target are the button, editBar, editButton, mainBar and newBar tags.

We should provide good, sensible, default behaviours. Simple buttons/actions, and the ability to customize/expose new buttons/bars easily, rather than try to cover each and every corner case like our current taglib does.

Rendering, currently done via the use of the magnolia-gui components, could be swapped at a later time to use FreeMarker, but this is independent from the templating language with which these tags/bars/buttons are used. If we want to do rendering of the components via templates, we'll need to expose something similar to the rendering models, to expose methods like "isAuthorized" etc.

Future improvements

Other tags, like isAdmin, ifEmpty, etc, are still useful in the context of JSP (not so much in FreeMarker; for other templating engines, they may or may not be, but are generally simple enough to be reimplemented)

Such tags could/should be kept around, but simplified, too. There's a whole lot of legacy in there that we could get rid of.

Subclasses of BaseContentTag are the most "complex" one because they rely on the complex inheritance patterns provided by getFirstMatchingNode() and resolveNode() - which use different parameters and combinations thereof.

Cms:out and cms:include are also quite complex, and could most likely be simplified. The latter's behaviour is already in part reproduced with MgnlTemplatingUtilities.renderTemplate() methods.

Some other tags should be replaced/reimplemented/split away:

  • cms:links (html head tags for js and css)
  • set, setNode, user, loadPage, ...

In any case: we could already:

  • Split, at least packages. Separate concerns.
  • Some renaming might help clarifying too.
  • We could do this without a deprecation phase, since the tags classes are not a public API. (i.e. the API is the TLD, which would not change)

Concepts

For the 5 tags above (button, editBar, editButton, mainBar and newBar), we can simply see 2 concepts: bars and buttons; or containers and items.

The rendering, or output, of these is mostly irrelevant for this issue; for 4.3, this will most likely still simply delegate to the magnolia-gui components. The important thing being that this becomes a hidden implementation detail, which we will be able to replace/update/improve later without the hassle of having to figure out each and every corner case the current taglib covers.

Buttons have actions, but these do nothing on their own other than generate links to servlets, so this can be considered an implementation detail, hidden in the rendering.

Another point to take into consideration is permissions. Currently, some of the tags or magnolia-gui components do check for permissions, for instance before rendering the editBar, but it doesn't seem to be a consistent behavior.

Common properties of items:

  • label, description (help). i18n is implied. This can even exist at "container"-level.
  • target: the node which the action is about (i.e for "edit", the paragraph node we're editing; for "new", the node into which we'll add a new child; etc.)

Ideally, the above should be enough: dialog name for edit-paragraph can be deduced, allowed paragraphs for new-button can be deduced from configuration, ... There are however sensible, often used, properties we can support too:

  • dialog: the name of the dialog to use (page properties, page header, ...)
  • allowed paragraphs: in current templates, this list is always passed to the jsp tag (even though with STK its value comes from the configuration). In some cases, it's just convenient if the template itself can enforce which paragraphs are added, even if not exactly the most elegant thing.

FreeMarker

JSP

  • JSP tags - either coded (should be fairly straightforward, just a little repetitive), could be generated.
  • Using the JSP 2.0 SimpleTag API - removes concerns about pooling, etc.
  • I'd rather keep the jsp-specific implementation separate from the new components, and keep those completely independant: testability, reusability.

Naming

Still haven't found a good name for these "new components".
Some of the brainstorm keywords: tag, ui component, admininterface, editor, bars, greenbars, author, authoring, buttons, dialog, edit paragraph, page edit, content edition

Current implementation

Some details about the current implementation:

  • nodeCollectionName is used inconsistently. In most cases, it ends up being concatenated with a node path (in some cases in javascript, for example with mgnlDeleteNode(), in other instances the final path is "calculated" by the end point (servlet), and in yet other instances, it's simply ignored.

Additional notes

Just some random bits of things I need to look at:

  • No labels