Skip to content

Responsive Design

Jump to bottom
Mark Reeves edited this page Mar 21, 2018 · 12 revisions

Introduction

WComponents was originally built as an in-house toolkit for Intranet applications. It has undergone a great deal of change to make components more responsive but more work needs to be done.

It is possible to create a responsive UI using WComponents in ways similar to any other web framework. WComponents may be given custom IDs and classNames; they have a consistent structure and inbuilt className convention; and they are extensible using templates, and application level CSS.

Some components have in-built responsiveness. These are often form controls which may have sub-optimal appearance on small screens. There is still much more to be done with this.

Theme support

Build-time properties exist to turn off all or parts of the default responsive design CSS. This allows a reasonably significant reduction in WComponents CSS if the applications using a theme do not require responsiveness (e.g. intranet applications) or if the theme or application builds its own.

The Sass var $wc-use-respond is used as a global swtich for almost all responsive design. If it is set to a value other than its default (true) then the inbuilt responsive CSS is not built.

The build-time properties are Sass variables found in the source file src/main/sass/vars/_respond.scss as tabulated below. For most purposes a "narrow" viewport is one the width of a large phone in landscape orientation or below. Setting the value of any of these to anything other than true will result in the default responsive CSS not being output.

Sass var Default Purpose
$wc-use-respond true Build responsive CSS. If this is off, all others are off.
$wc-gap-reduce-when-narrow true Reduce intra-component spaces on narrow viewports.
$wc-fieldlayout-use-respond true Allow WFieldLayout LAYOUT_FLAT to become STACKED on narrow viewports.
$wc-use-respond-table true Basic responsive design for WTable.
$wc-use-respond-dialog true Make all WDialogs full screen on narrow viewports.

If responsive CSS is built into the theme there are other properties which then control specific aspects of the CSS.

Components with in-built responsive design

Some components which produce complex artefacts or multi-column input sets have basic responsive design built in. This may be overridden using application level CSS but this is complex and should not usually be necessary.

The following components have in built responsive design (unless disabled by the theme) which is invoked when the viewport falls below 774px (as of WComponents v1.2) unless stated otherwise.

  • WCheckBoxSelect and WRadioButtonSelect with COLUMN layout the checkboxes will be laid out in a single column.
  • WTabSet of all types except accordion the WTabSet will take on an accordion appearance and functionality when the viewport width is 1000px or below.
  • WSubMenu when the containing WMenu Type is not TREE the pop-up submenu will be fill screen.
  • WPartialDateField and the polyfill for WDateField the calendar control is displayed full-screen.
  • WDialog displays full screen and is neither movable nor resizeable.

Components with opt-in responsive design

Some layout components provide a simple degree of responsive design which is enough to cover many simple UI use cases. This opt-in is via setting a HTML className using HtmlClassProperties.RESPOND:

// given WRow row turn on responsive design for its columns:
row.setHtmlClass(HtmlClassProperties.RESPOND);

The following components have this opt-in which applies when the viewport width falls below 774px (as of WComponents v1.2).

  • WPanel ColumnLayout:

    when the WPanel to which the layout is applied has the RESPOND class value set then each column will occupy the full width of the viewport and a small margin will exist between each "column" in a "row".

  • WPanel GridLayout:

    when the WPanel has the RESPOND class value and there are 12 or fewer columns in the grid then the grid will rearrange itself below 1000px to show fewer columns in the grid (depending on the original number this will be between 1 and 5 columns) and again at below 774px to show no more than 3 columns in the grid. In each case the cells will be rearranged into more rows, no cell will fail to render.

  • WRow:

    each WColumn will occupy the full width of the viewport and a small margin will exist between each "column" in a "row".

  • WTable:

    each row of the table will be a block and each column in the row will occupy the full width of the viewport. It is highly recommended that the WTable have row striping enabled.

    There is no attempt to place the content of the column headers into a pseudo-element of the cell to make the row headers appear in-situ. This can be done quite easily in CSS for a given use-case where the content is known in advance but is outside of the remit of simple default responsive design at the framework level.

  • WMenu MenuType.BAR and MenuType.FLYOUT:

    when the WMenu has more than one WSubMenu and/or WMenuItem child (not descendant) the menu will be re-structured to be a single launch point with a (configurable) icon which, by default is a "hamburger" icon as per HtmlClassProperties.MENU.

Optimising layouts

If the application is complex or the audience predominantly mobile it is probably more appropriate to create layouts using a WTemplate and employing a responsive layout library than to attempt to use WPanel layouts. The layout components in WComponents are considered legacy components and may be phased out.

The core dev team is continually looking into alternate layout libraries and we are keen to work with anyone who has some good ideas/suggestions in this area.

Some start pages

Clone this wiki locally