About the Design and User Interface

Use of Colour

Within articles and posts the following colour coding is used.

  • On-page links are coloured like this.
  • Within the Kumu, links to other existing Kumu articles are coloured like this. For those with editing privileges, articles yet to be written (i.e. which do not currently exist) are coloured red like this. For those without such privileges, the putative link is not coloured, so you should never see a red link (the example above is just an example, it is not actually a link).

Other links are generally styled in the usual way, but with the addition of an explicit off-site marker like this link to encrypted Google search.

In complex diagrams, particularly the box-and-line diagrams for entity-relationship etc. diagrams, I have generally adopted a styling and colour scheme that should maximise visibility and clarity for protan, deutan and tritan colourblinds.

Responsive Design

This site is built in WordPress using the Divi theme from Elegant Themes with a number of customisations. I have been particularly concerned with making sure that the content is usefully accessible on mobile devices so that it can be consulted away from the desk, e.g. in meetings or when working while travelling.

Enhancements

Whilst Divi is a very sophisticated responsive theme, I have added some pure CSS enhancements1CSS stands for Cascading Style Sheets; see here at Wikipedia to maximise the site’s utility on mobile devices.

The key points are as follows.

  1. Tables reflow from column-oriented to row-oriented on small screens. A good example may be see in the article on Stakeholder Kinds.
  2. Highly structured articles (i.e. with many headings and sub-headings) have individually expandable and collapsible sections – and a large button at the top that will temporarily override all user display selections to show all content: previously collapsed headings will re-collapse when the button is clicked again to restore the view prevailing before all sections were shown

Implications

Clicking a link that targets a collapsed section does not reveal the target: it will not cause the relevant section to expand because control of section display is done entirely in CSS2I based my approach on the CSS + HTML only Accordion Element work of Alex Bergin; what I have done is to make his single-level accordions nestable.; there is no JavaScript involved3There is plenty of JavaScript elsewhere of course, mostly in the theme..

It was for this reason that the option to display all sections was added.

Table Formatting for Mobile – Layout and Size Changes

Although Divi is a powerful responsive theme, i.e. one which adapts the layout according the screen size of the reader’s device, additional effort has been dedicated to making tables usefully legible on mobile devices. For this, I made use of Chris Coyier’s proposals at CSS-Tricks.com for using CSS to make the columns of a table behave like rows.

One drawback of his approach is that column labels have to be hard-coded in the CSS; fortunately I am in control of my own HTML generation and so am able to sidestep this issue (and have general purpose CSS) by making use of the content and attribute capabilities of CSS to create row headings with “content: attr(data-label);” where the data-label is generated in the source HTML from the column headings.

However, on the smallest screens the headings were often still too large, so I have made then shrink with decreasing screen size.

I had one or two other difficulties in implementing his approach, but since I have now forgotten what they were, they were clearly minor and it all works very nicely now.

Diagramming

I make extensive use of Draw.io’s online drawing capability (try it here) to generate diagrams that render as SVG, which supports links on objects. In most cases here, the links are to other places on this site.

Whilst Draw.io does have the ability to export HTML (containing compressed mxGraph data) for embedding in a web page, for work-flow reasons I have chosen to directly embed the contents of the xml files that Draw.io can save. This is achieved by a personal WordPress plugin I wrote to complement Mike Thomson’s excellent DrawIt WordPress plugin, which integrates Draw.io with WordPress.

The embedding of Draw.io diagrams is generally excellent, but there are some minor variations in rendering between browsers (IE11 always seems to show scroll bars) and between desktop and mobile devices (the stock Android Internet browser on my Samsung Galaxy S4 sometimes misplaces the zoom controls).

Unfortunately, at the time of writing, Draw.io embedding does not work well when the canvas is in an HTML <div> tag which is not visible 4e.g. but not limited to, display: none; and so all rendering takes place in initially visible divs that are hidden on completion of page load by a small piece of JavaScript. Since section expanding and collapsing employs animations, I hope the effect is not jarring – in fact it almost works as a whole-page preview5Does that make it a bug or a feature? Well, it’s deliberate, so it’s a feature, but the preview effect is just a post hoc rationalisation. Maybe its a pheature..

If anything is badly wrong on a particular browser or device I would like to know, though depending on the obscurity of the issue it may or may not be addressed. Best advice: try a different browser.

HTML Generation

A considerable amount of material has been derived from previous work stored in MediaWiki (which was itself derived from documents in Word; there is some circularity of formatting); unfortunately there is no simple way to use MediaWiki content directly in WordPress6No plugin I found worked well enough – but I eventually found the Yada Wiki WordPress plugin for WordPress which provided the minimal functionality I needed. Yada Wiki is an excellent plugin that provides the key features of a wiki (via a WordPress custom post-type): links to existing articles, the option to create new articles on-the-fly, and tables of contents. It works very well for me and David McCan, the developer, has been very supportive and responsive.

Since the MediaWiki markup I had been using was very limited, I initially wrote VBA for Microsoft Word to convert to HTML. Then I extended the code to convert MediaWiki markup to Word styling and began to write in Word again. Articles are now generated by writing in Word, which is then converted, via MediaWiki markup, to HTML snippets.

HTML files are then bundled into a full or incremental CSV file that allows me, via another personal WordPress plugin to upload articles in batches. The CSV importer also takes care of setting certain custom properties, such as SEO data (derived from code generated HTML <meta>) and editing preferences. Files are date and timestamped, nominally based on the last time the source was changed (but not always).

To prevent WordPress corrupting HTML sources in the event that Visual editing mode is (accidentally) invoked, I rely on the Always Edit In HTML WordPress plugin to keep HTML only editing.

The custom VBA code also takes care of the HTML structures required to support nested accordions as well as the conversion of MediaWiki (and other) links to Yada Wiki shortcodes.

Notes   [ + ]

1.CSS stands for Cascading Style Sheets; see here at Wikipedia
2.I based my approach on the CSS + HTML only Accordion Element work of Alex Bergin; what I have done is to make his single-level accordions nestable.
3.There is plenty of JavaScript elsewhere of course, mostly in the theme.
4.e.g. but not limited to, display: none;
5.Does that make it a bug or a feature? Well, it’s deliberate, so it’s a feature, but the preview effect is just a post hoc rationalisation. Maybe its a pheature.
6.No plugin I found worked well enough

Pin It on Pinterest