All posts
Liferay · 11 min read · Jul 8, 2026

Designing Fragment Configuration Non-Developers Can Actually Use

Fragment configuration panel designed for content editors

Assuming you already know how a fragment is put together and rendered, the interesting question is a different one: which parts of it should a content editor be allowed to change, and how should those choices be presented? That is not a technical question, and answering it technically is what produces fragments that are either rigid or unusable.

Two failure modes, both common

Under-configured fragments look clean and generate work forever. Every time someone wants a different heading, a different number of columns, or a different data source, the request comes back to a developer and a release. The fragment was reusable in theory and single-purpose in practice.

Over-configured fragments fail differently. A panel with thirty fields covering every CSS property the developer could think of is not flexibility - it is an interface that requires the knowledge it was meant to remove. Editors respond by using the defaults and asking a developer anyway, so you have paid for configurability and kept the change requests.

The question that sorts it

For each candidate field, ask whether it varies legitimately between two placements of the same fragment on different pages. If yes, it is configuration. If it varies only because two designers disagreed, it belongs in the design system, not in the panel.

RequestWhere it belongsWhy
Different heading text per placementConfigurationGenuinely varies by context
Which data source or category to showConfigurationThe reason the fragment is reusable at all
Number of items shownConfigurationVaries with page density, safe to bound
An arbitrary hex colourDesign systemProduces off-brand pages and unbounded support
Font family or sizeDesign systemTypography is a system decision, not a page one
Whether to show an optional sectionConfigurationA real editorial choice
API endpoint URLCode or system settingsOne wrong value breaks the page silently
The test is whether two correct placements would legitimately differ.

Constrain the values, always

Wherever the set of valid values is known, present a selection rather than free text. A select gives the editor the options, gives you a guaranteed valid value, and gives the fragment a finite number of states to test. Free text gives you an infinite input surface and a support queue.

This applies more widely than it first appears. Column counts, alignment, density, card style and even colour should usually resolve to a small named set drawn from the theme, not to raw values. A colour picker that offers any colour in the spectrum will eventually be used to produce every colour in the spectrum.

The default configuration is the product

A fragment must look finished the moment it is dropped onto a page, before anyone opens the panel. This matters more than any individual field, for a practical reason: the default state is what people see when evaluating whether to use it at all, and a fragment that renders as an empty box with a configuration prompt reads as broken.

It also sets the baseline for everything else. If the defaults are right, most placements need no configuration, and the panel becomes an occasional tool rather than a mandatory step. That is the actual goal - not a rich panel, but one that rarely needs opening.

Write labels for the page, not the code

Configuration labels are read by someone thinking about a page, not about an implementation. The field that controls how many cards appear should be called something about items shown, not about a limit parameter. The field that switches the layout should describe what the page looks like, not which CSS class is applied.

  • Label by outcome - what changes on the page - rather than by mechanism.
  • Order fields by how often they are changed, with the common ones first.
  • Group related fields into sets so the panel reads as sections rather than a list.
  • Keep help text to one line that says what the field affects, not how it works.
  • Use the editor's own vocabulary; if the team says tile, do not call it a card.

There is no validation, so degrade gracefully

Configuration values arrive as whatever was stored, and there is no layer that guarantees they make sense. A number field can be empty. A selected data source can be deleted afterwards. A collection can return nothing.

The fragment therefore has to handle every one of those states deliberately, and the most important is the empty one. A fragment whose data source returns nothing should render a clear empty state, not a blank region that looks like a rendering failure. This is the same discipline as handling absence explicitly rather than letting it look like false - silent nothing is the worst possible output.

Configuration keys are a published contract

Once a fragment is on pages, its configuration keys cannot be renamed. A rename does not migrate existing values - it abandons them, so every existing placement silently reverts to defaults, usually noticed weeks later by someone who did not change anything.

  1. Choose key names carefully at the start, because they are effectively permanent.
  2. Add new fields with safe defaults rather than repurposing existing ones.
  3. When a field must go, leave the key in place and stop reading it instead of deleting it.
  4. Never change the meaning of an existing value - add a new option instead.

Behave correctly while being configured

A fragment is configured live, with the page editor re-rendering as values change. Anything with JavaScript has to survive being initialised repeatedly on the same page, and the usual bug is that it does not: listeners accumulate, timers multiply, and a chart or slider ends up rendered several times on top of itself.

The fix is to make initialisation idempotent - clean up before setting up, and key any instance state to the specific element rather than to the page. It is a small amount of code that is invisible in normal use and obvious the first time someone spends five minutes adjusting settings.

Conclusion

Good fragment configuration is mostly restraint. Expose what legitimately varies between placements, constrain every value to a known set, make the defaults good enough that the panel is optional, label fields for the person editing the page, and treat the keys as a contract you cannot take back. It is the same balance as deciding how far to externalize any logic: the goal is not maximum flexibility, it is letting the right person change the right thing safely.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar