Skip to content

Margin

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 12 revisions

Margin is used to set space around a container component. It is usually better to do this in application specific CSS.

Introduction

A number of layout-related WComponents are able to have a margin applied to them to allow for more flexible layouts without having to resort to multiple nested WPanels with FlowLayout or similar.

A margin may be set on any or all of the following sides of a the component:

  • TOP;
  • RIGHT;
  • BOTTOM; or
  • LEFT.

Margins may be used to move blocks of content away from each other and would most often be used as one of TOP or BOTTOM in a set of vertically arranged components.

Why use Margin

Margin can be used to put space between sibling components in the same container and are, in most circumstances, preferable than using a VERTICAL WPanel FlowLayout to apply space between a set of blocks.

It is difficult to justify the existence of Margin in that it is another of those features which exists so that a Java web application does not have to use web technologies, which is a bit of a stretch.

Margin does exist however and it does allow a pure Java mechanism to apply space around some WComponents.

Adding margin

Margin has two constructors. One takes a single Size argument and this margin is set on all sides of the Marginable component; the other takes four Size arguments which are then applied to a side of the component.

Margin symmetricMargin = new Margin(Size.MEDIUM);

// a Margin which is applied only to the top and bottom of
// a component: SMALL at the top and LARGE at the bottom:
Margin topBottomMargin = new Margin(Size.SMALL, null, Size.LARGE, null);

// a margin which _could_ be different on each side of a component
Margin weirdMargin = new Margin(Size.SMALL, Size.LARGE, Size.MEDIUM, Size.XL);

Marginable components all have accessors for a Margin so:

marginable.setMargin(margin);

// or an inline instantiation:
anotherMarginable.setMargin(new Margin(Size.MEDIUM));

Implementing Margin

Margins are specified as one or four Size options but are applied as one of a set of margin class attribute values. The implementation of Margin using a set of classes is done to help implement a consistent UI design standard.

Margin sizes

If a Margin is applied to a WComponent it is exposed as a class value with the prefix as listed in the table below and a suffix determined by the margin size.

Margin type class prefix
all wc-margin-all-
TOP wc-margin-n-
RIGHT wc-margin-e-
BOTTOM wc-margin-s-
LEFT wc-margin-w-

The suffix is one of four values where Size of margin is converted to a class in order to enforce UI consistency and design standards. This uses the same size determination as gap, vgap and hgap as outlined in Theme intra component spacing.

  • sm for a small margin;
  • med for a medium margin;
  • lg for a large margin; and
  • xl for a very large margin.

The actual cut-off points and sizes of these margins are theme dependent. See Size for more information. It may be more appropriate to specify common inter-block margins in a theme or by using application level CSS; see:

Marginable WComponents

The full, up-do-date list should be in the Marginable JavaDoc. The following are the most common Marginable WComponents:

Using margin classes in templates

The classes used to set margins around a HTML element, as described above, may be applied to elements used in templates. This allows construction of consistent template layouts which will fit well with WComponents added to them.

<div class="wc-margin-all-xl">
  This div has a really big margin all around it.
</div>

Theme developers

The Sass used to generate the margin classes and sizes are controlled by a set of variables (all of which may be overridden). Note that these variables and associated classes are also key to intra-component spacing. See Size for more information.

Templates

If the list values in variable $wc-gap-suffix-list are changed then the template used to generate the margin classes must also be changed. In WComponents 1.x this is an XSLT file. The two need to be kept in sync for any of this to work.

Older versions

Before v1.4 Margins were set as integers but then manipulated in the client code to emit a limited set of margin sizes as HTML class attribute values. This was done to enforce consistency and allow easier responsive design. From WComponents 1.4 Margins are instantiated using a size enum to bring the Java API and UI back into a consistent state.

Further information

Some start pages

Clone this wiki locally