Best practices: HTML macro usage

Development
#1

Hi everyone,

The Application Development Best Practices includes this item:

Page content must contain the minimum of HTML (since HTML doesn’t translate in discrete XDOM elements and thus are not always handled by all Renderers). For example don’t use <div class="something">...</div> and instead use (% class="something" %)(((...))). One notable exception is for HTML forms for which we don’t have a macro yet.

I thought we discussed about this in the past but I can’t find the discussion and I’m pretty sure I’ve expressed by disagreement with this rule a couple of times. My point of view:

  • we need to distinguish between user interface and user content; in simplistic terms this means:
    • user interface: what the end user can view and interact with but should not change
    • user content: what the end user can view and interact with but also can change
  • HTML is not suited for writing user content because it’s too technical, too verbose and thus error prone
  • on the other hand, wiki syntax is simpler, less verbose, because it was specifically designed to be used for writing user content, not user interfaces
  • HTML is better suited for writing user interfaces (on the web) than wiki syntax
  • XWiki is primarily a web application and thus XWiki’s user interface will end up as HTML/DOM in the browser
  • web developers must have full control over the HTML that ends up in the browser (e.g. when developing the user interface of an XWiki application)

With these in mind it’s pretty obvious for me that we should recommend using:

  • wiki syntax for writing user content
  • and the HTML macro ({{html clean="false"}}) for writing user interfaces

So this vote is about changing the item I quoted above with this:

  • Use the HTML macro ({{html clean="false"}}) for writing the user interface of your application (e.g. layouts, forms, dialogs, menus, tabs, accordions, trees, panels, etc.). This usually goes inside technical and thus hidden code pages.
  • Don’t use HTML for writing user content (e.g. documentation, help or demo pages). Use wiki syntax instead. This usually goes inside public, non-hidden, pages.

WDYT? +1 on my side obviously.

Thanks,
Marius

#2

+1

#3

For the sake of the discussion let me list some potential issues with the usage of the HTML macro:

  • We wanted to be able to have xwiki working when it’s disabled, see https://jira.xwiki.org/browse/XRENDERING-27. Now, since then, the HTML macro has been used a lot in various places and it’s probably quite hard. Instead, we should just have a way to protect its content.
    • Since the user interface is controlled by the developers, there should not be as many risks as when using the HTML macro for content.
  • It generates RawBlock in the XDOM (of syntax = HTML) and these blocks may not be understood by all Renderers. This is actually why we didn’t recommend to use it and why we tried to be able to express almost everything in XWiki Syntax. Thus, if we want to generalize the use of the HTML macro and even increase it (as Marius is proposing), we need to be sure that this content will never be needed to be rendered by any Renderer other than the HTML ones (which obviously understand HTML).
    • Here’s one simple example to be more precise: the LaTeX Renderer doesn’t support the HTML macro ATM and this causes losses if we export to PDF content that uses it.
    • Note: I think this is compatible with what Marius is proposing when he says that it should only be used for the user interface (which is not supposed to be rendered by a Renderer other than the HTML ones)

I’d add these 2 items to the rationale for allowing the HTML macro for user interface and not user content in the doc.

I’m not sure I agree with the phrasing. I think it still makes sense to use wiki markup for user interface and I’d say instead Allow the usage of the HTML macro ... in addition to wiki markup. Use what makes the code the most readable (+ add some best practice examples of readbility : do-s and don’t-s. In other words, I wouldn’t force the unique usage of the HTML macro for user interface.

WDYT?

Thanks Marius for starting this topic. I don’t remember if we discussed it on any list or forum in the past (we did discuss it on chats for sure).

#4

I’m fine with that. I agree that sometime the line between user interface and user content is very thin and sometimes we have to mix user interface with user content in the same page (e.g. arrange the content in a special layout), in which case I prefer to use wiki syntax for the UI (layout) if it’s not too much in order to better integrate the content (and because I’m not a fan of {{html wiki="true"}}, I try to avoid it as much as possible).

Thanks,
Marius