Scratching an itch, Learning a bit

Extending the "Fragment Search" UI: Simplicity and Maintainability

Illustration: ​​​​​​​"Haystacks" by John Pavelka, CC by 2.0

Bottom line upfront: This is the background story for my reason to create this plugin.

The Problem Space:

A while ago, I filed LPS-142817 - mainly because I was in a situation where I've been working with fragments in fragment sets maintained by multiple other people, and I could never really build a reliable mental model to quickly locate a fragment when I was looking for it.

You'd guess that time would solve that problem, but I'm working in Sales Engineering. That means that I'm constantly switching to different systems with different fragment sets, that are being evolved (and composed) by others (for which I'm really thankful - it just doesn't help with this particular problem).

Here's my problem (you probably didn't click that ticket link...): When you search for a fragment, you'll have to do it fragment set by fragment set - e.g. you'll have to know which fragment set your fragment is in. And, personally, I'd like to delegate my search activity to a computer, whenever I have one at hand. When dealing with Liferay DXP, I typically have.

How to proceed, when I don't expect my code to make it into core? Simple: Write an extension.

Further Criteria:

My #1 recommendation for writing an extension is to optimize it for maintainability, and typically that means that JSP-fragments are off-limit: Those are just messy, and if Liferay ever changes a JSP in a future release, I'd have to do a 3-way-merge and understand what&why I've made a change in the ancient past.

My #1 personal self-deprecation is that I'm not a UI person: I can tell when a UI is sub-optimal, but it takes me a significantly longer time than it does for anybody else to create a good UI myself. If I'm ever suggesting a UI (more particular: UX) improvement to one of your components, that's because I couldn't do it myself in reasonable time.

Combine those two, and you'll get a quick and simple plugin that solves the problem, with a true minimalist UI - "<ul>, <li>, <a>" are good enough, right?

Coming up with a solution:

Ok, I've already ruled out JSP-fragments - but how else would I add my content to an existing UI? Well, PortletFilters to the rescue.

Luckily, the Control Panel applications are all Portlets (or Widgets), so it's trivial to write a filter for them. In the implementation: Just buffer their output, identify the location to add custom content, and do some String magic.

Maintainability Spotlight:

Let's look at this approach from a maintainability standpoint and compare it with JSP fragments:

Maintenance is necessary because Liferay might update its implementation and UI, which might change the JSP as well as the DOM.

So the risk for a filter implementation is:

  • The DOM might change at any time. Such a change might break a portlet filter's String magic.

But, in case this approach breaks, I'll just need to understand the new DOM, and find a new location for my own additional markup.

Contrast that with the risks of implementing a JSP fragment:

If a JSP changes, I'll have to execute a 3-way-merge and understand

  • what I changed (in the ancient past) and why
  • what Liferay changed and why
  • if these changes conflict
  • how to bring my changes into the newest version

So, for maintaining JSP-Fragments, I basically have to remember & understand the changes​​​​​​​ that two parties made, and their relationships. Rather than the current DOM.

Plus, the odds that any future change to the JSP would have an effect on my String magic, are a lot lower than 1. While the odds that any change to the JSP would have an effect on a custom JSP fragment are exactly 1.

Granted, it's a bit harder to write a decent UI in a portlet filter - but due to my own precondition mentioned above, I'm happy with a minimalist UI. So there's my lesson: Since PortletFilters can be deployed completely independent of a portlet, and are trivial to write: They're a good tool in a toolbelt, that can help writing well maintainable code.

And just because I only create a minimalist UI with them doesn't mean you can't do more.

So, if you also never know where to find your fragments: Install this plugin and remember to say Hi when we meet at Devcon next week.