How should we organise Velocity templates in MAF?

Iain Miller

We've been migrating the UI of the Multiple Application Framework (MAF) from XSL Stylesheets to [Velocity](
http://velocity.apache.org/), a UI template framework from Apache. As background, here's the original [MAF UI Architecture Overview](
https://thehub.thomsonreuters.com/docs/DOC-2911). We've had a couple of discussions here in the UK, and the proposals are: 1. No inheritance of velocity templates - this includes inheriting from the default theme 2. We may not even have a default theme as it adds maintenance overhead and isn't particularly useful as we can't run a default MAF 3. Each MAF implementation/product to have own velocity templates 4. Sharing of common functionality is to be done by using components - ideally the templates in a given theme will just be composing components 5. First implementations of new templates for new MAF functionality are created in/moved to components to act as examples of implementation 6. Implementation of WLUK PASs to be revisited – look at consolidating into WLUK 7. Require strict governance around code in VMs (what is allowed & what isn’t). I'm going to edit this to add some more background detail. Please give feedback as answers or comments, also you can request extra detail there. Also, please vote on the answers/comments. Finally, to keep the discussion focussed, note that this applies to *just* the Velocity templates - we'll be discussing things like static content etc separately.

Steve Tomlin

I concur on the suggestions above. The advantages of inheritance are lost due to the large amount of files that brands need to inherit. It starts getting very complicated for a brand when they don't have that file in their own space. To simplify the problem, each brand attempts to duplicate the inherited files into their own space unnecessarily and we end up with duplicate code that is difficult to maintain as well as a complicated inheritance structure. With regards to number 4. The sharing of components. I think this is a good compromise to inheritance: However, I recommend detailed clarification on what specifically a components is. For example, is a component simply a single static file such as javascript, css or html, or can a component be a collection/combination of static files. Also, with regard to future development of shared components, would it be wise to version the components, eg name the component componentName/ver1/files... And when that component has finished in development a new version is created ie componentName/ver2/files... for upgrades to prevent brands using existing components from breaking. I also recommend a constant process of breaking down any brand shared functionality into smaller chunk sized components. This may be an on going task but lead us closer to less code duplication and easier maintenance.

Enrique Molinari

I agree that the Default theme did not add anything positive. Velocity does not offer real UI components like JSF or Tapestry. That is why I think inheritance might work, at least, for MAF Apps that belong to the same family (La Ley Online and Checkpoint La Ley are the root of the LATAM MAF Apps and the same will apply to WLUK and WLMY/WLIN). Components sounds good for sharing between MAF Apps which does not belong to the same family (to clarify again, the only families we have in MAF are WLUK -> WLIN/WLMY and LLO and CPLL in LATAM). But I agree with Steve. What is a component ? we don't have this concept in Velocity. We might need to create it. For know, looks like our components are bits of html in Velocity Macros or JQuery plug ins.

Iain Miller

True, Velocity doesn't have a concept of components. We can define a component as any snippet of HTML, (I'm not going to worry about jQuery as we're only discussing the Velocity templates here!) or a collection of components. This is pretty much the way it is if you look at the Velocity templates within the *components* directory, you'll see that some templates *#parse* others from within *components*. Our current implementation is a bit lacking as it has been implemented for MAF by making the */MAFWeb/WebContent/WEB-INF/themes* directory the template root for Velocity templates, and having the *components* directory next door to the theme directories. This is a bit clumsy, as it means that when we want to *#parse* a template from within a theme template (which is in a directory below *themes/{theme id}/views*) we still have to include the full path to the *views* directory. It would be more intuitive if the template root for a theme was *themes/{theme id}/views*! There have been different approaches to address this - for example Insignis hard-codes the "insignis/views" prefix in the *#parse* statements, and the LLO/CPLL products define a variable called *$viewPath*. The current situation does mean it is possible for any theme to use any other theme's templates! Anyway, the point of this rather rambling answer is that we shouldn't get too tied up in defining what a "component" is - we already have a good definition! Secondly - how would using inheritance within the WLUK and LLO families be better than those families using components for common functionality?

Enrique Molinari

I prefer components rather than inheritance. The thing is that we already have an application (LLO) which was built without having in mind that later a big family was going to be created. On the other hand, often, these apps are so similar, that I don't want to create a vm to consume components, I just want exactly the same vm file. Why not give the possibility of inheritance in this case ? (I would like to see if we can really take advantage of this with a real example in one of the childs of LLO). I think it is acceptable what we have about components and probably with governance we make it work better than today. As we know, components needs to be self contained. For components that depends on javascript I don't want to remember to import it to make it work. Why not have another flavor of components built using Tools ? The vm template just needs to call it and customizing it via parameters. The Tool is responsible for the mark up and the addition of any javascript file required (CSS might be optional if a different style is required). Creating components from Tools, will give us, at least, better documentation (javadoc generated by jenkins) and automated testing. It might not be possible or too complex for certain complex pages though, so I'm not suggesting to replace the ones we already have, but suggest this as another option to take into account.

Steve Tomlin

That sounds fine to me. I recommend having a vm template in components contained in a folder with a unique folder name/module identifier, which is in yet another folder for its version, of which imports other css/javascript/vm templates etc that also sit in exactly the same foldername identifier in their respective locations.

rafael.aragon

I agree that components would be the best solution but regarding brands I think the options are inheritance or duplication. With both approaches we will have to be careful with maintenance. As Enrique said LLO was not initially prepared to have several brands so inheritance would be the option to avoid duplication between these brands. For instance, we had to copy these templates so as to modified only search-filters.vm. result.vm > search-left-panel.vm > search-filters.vm (Lately result.vm suffered some modifications too). I have a comment regarding this phrase in the first post. "ideally the templates in a given theme will just be composing components" For brands, this composing components in some ocassions will be duplicated too because sometimes brands share entire functionalities or only change for some details. Moreover if you have a chain of parsed composing templates and you want to change the last linked template you will have to duplicate all the chain. Perhaps inheritance will have to be controlled too, avoiding innecessary inheritance that can be resolved with configuration of components.

Steve Tomlin

If the componenets are managed well, ie any brand with shared architecture is converted to components, then the only duplication is the invoking of components.

Carlos Berdaguer

I agree with allowing inheritance within applications from the same family since experience in this type of applications show that it saves a great deal of work and duplicating code, also new brands end up being really easy to implement and developers have a chance to have something to show the business very soon in the development process. Enhancing the components parsing using tools that would take care of all the files involved is a good idea too, it'd also force us to enhance UI code (js and css) to have shareable and maintainable components there too, js code is usually messy in applications since no clear governance has been defined yet, this will give us a chance to have "oficial" js components shared accross applications.