A diagram provides a fairly basic means of showing relationships.
The diagram element is a basic canvas on which a variety of elements can be placed. It is not a scalable vector-graphic like SVG, but it can provide basic diagrams with links. This makes it suitable for graphical tables of contents, organisation charts, process diagrams and other simple layouts. The advantage of diagrams over images is that their content can be read by screen readers for the visually impaired and SEO bots.
Note that Smallsite Design does not allow SVG images to be uploaded because they can contain malicious code or links with no reliable way of vetting them, and simply removing possible sources of such in them when uploading will likely break their functionality.
The elements have some options to provide variety, such as background colours or line styles, but not so there is a steep learning curve to being able to use them. Positioning and sizing is in pixels.
The elements that can be used in a diagram, in order of visual stacking priority, and with their hover button icons, are:△
- 🄰 – basic rectangle with text and a selectable background colour. Can be a link.
- A – Text area for labelling. Can be a link. Text size is smaller than for boxes. Shows a pink background tinge while editing, but not when viewed.
- ⯆ – Arrowhead with selectable direction. Its size is 6x6 pixels.
- ∟ – Right angle line of selectable type. Set a dimension to 0 to have a straight line. Border can be solid, dashed or dotted.
- ⌗ – An invisible (when not editing) element to put in diagonally-opposite corners to force sizing of the canvas. Its size is 10x10 pixels.
- ⧈ – Element with optional image background (transparent if none) and/or border with colour and style. For overlaying its parent overlay. Can contain other diagram items but not overlays or other suboverlays. Shows a pink background tinge while editing, but not when viewed.
- ☐ – As for suboverlays but for overlaying the diagram background. Can contain other diagram items except another overlay. Shows a pink background tinge while editing, but not when viewed.
- Universal border-to-border background image for the diagram, if selected, otherwise a neutral grey. Any image is repeated in each direction.
The visual stacking priority dictates which elements appear over others.
This visual stacking priority ensures that:
- a.Boxes are always on top.
- b.Text can cover lines for labelling them.
- c.Lines are underneath, so that their sizing doesn't have to be exact when placing them to appear joined to boxes or arrows.
- d.Arrows can be placed anywhere, including in multiple places along lines.
- e.Elements can be positioned over the overlays.
- f.Later elements of the same type cover earlier ones if they overlap.
- g.These apply within the one stacking context of a diagram, overlay or suboverlay, but might not between them.
Elements can be moved, and except for arrows and anchors, can be sized.
Some things about dimensions and sizing are:
- a.The rendering direction defaults to the reading direction for the locale, but setting the diagram's Direction will set the starting side to be independent of the viewing locale.
- b.Sizes and axes offsets start at 0 from the upper starting-side of the diagram. However, after any move or sizing, the top of the uppermost element is set to 0, and the start of the start-most element is set to 0, leading to all sibling element offsets being recalculated.
- c.While boxes and text sizes are always positive, setting any line dimension negative will flip it around that dimension. This allows lines to be any orthogonal orientation of a right angle.
- d.While a line is two dimensional, setting one of the dimensions to 0 makes it a straight line in the other dimension.
- e.Dimensions always include any border or line widths, which are always two pixels, but the offsets for child elements are from within the border. These need to be accounted for if deciding to turn on or off the border for an overlay or suboverlay, as their content position will change in relation to that outside them.
- f.Arrows are 6 by 6 pixels and anchors are 10 by 10 pixels, with their origins also at the upper start of that sizing rectangle, which will help with pixel-accurate placement.
When created, all elements appear in the upper start-side corner. Preferably use the Clone action to place further elements of the same type, because that will likely only involve incremental moving from the current offsets rather than from the parent origin. All elements are created as having errors. This ensures that each will have a direct link to them in the diagram's child navigation bar, as some may be obscured by other elements. The errors are cleared when moved and text provided for those that need it.
When background images are specified for diagrams and overlays they cover the whole area up to the borders, repeating in each direction if needed. If an element has a border, anchors in opposite corners will usually be required to provide an area between its contents and the borders to look aesthetically framed.
If an element is moved to another element using the To facility or Spikes, its coordinates are retained to retain relative positions with other elements that may be being moved as well. Preferably use overlays and suboverlays to enable moving multiple elements at once as they make it easier to reposition them at their new location in their current spatial relationships.
When moving a bunch of elements from a diagram into a new overlay, many may be well outside of the overlay because of the retained offsets. Once all the required elements have been transferred, adjust any one of them by as little as one pixel and all their offsets will be recalculated to make the uppermost, start-most element be at the overlay origin.
However, deleting an element will trigger a recalculation of all offsets if it was the top-most or start-most element. To avoid unnecessary recalculations while editing, perhaps use some anchors to keep the editing origin stable until all edits are done, and then delete it.
A diagram will size to include its contents when rendered, but will never scale itself to fit. Instead, if it is too large for the area allowed for it, such as when next to an aside, a horizontal scroll bar will appear. However, while editing, even if the contents are fully exposed, a scroll bar may still appear. This will be because an element's invisible hover button is extended over the end of the visible elements. Scrolling to the end will allow the button to be hovered over to become visible.
Diagrams, overlays and suboverlays can have a background image for their child elements to annotate, though overlays and suboverlays are transparent if they don't have one.
A diagram's background image could be a detailed map for annotating. An overlay can provide a small inset of a wider area that shows the location of the detailed map within it, which is helpful for those not familiar with the geography of the area. A background could be an image of a piece of equipment, with an overlay for showing more detail or indicating the particular controls to be focused upon.
Because there are no locale-specific dimensions for diagram sub-elements, the best uses for background images and overlays are for real-world objects which are not locale-dependent. This means screenshots for documenting computer programs may not work if using multiple locales because particular areas of the screen layouts will likely vary between locales, especially if scripts of different reading directions are used. Better to use a figure with images with multiple pre-annotated locale variants for that scenario, or use labels – which can have per-locale coordinates – on it as bi-directional links to a table or list with explanations.
The images are repeated in both directions, so can be used for decorative embellishment, but be aware that that may make them more likely to be a distraction. The major consideration in using images is that what is shown of it is limited by the diagram or overlay size. The diagram size is limited to the size of its contents and not its background image.
That means that some drawing elements must be in diagonally-opposite corners to ensure that the wanted parts of the image are displayed. Use anchor elements if no other element is suitable, preferably in the lower-start and upper-end corners to keep the upper start free so that new elements can be easily selected. The size of overlays is explicitly set, irrespective of contents or image.
Overlays and suboverlays are like a mini diagram in that they:
Overlays and suboverlays differ from diagrams because they:
During editing, overlays and suboverlays have a slightly opaque grey background so that their size and position can be seen when they do not have any border or background image. It also tinges any background image. The backgrounds are subtractive, so the more they are stacked, the darker the grey gets. If one is selected, its background colour will change to pink, which also happens with a text element.
Overlays and suboverlays provide a way of grouping elements so they can be placed or copied as one, to two levels, giving a lot of flexibility and saving time for constructing repeated sections of a diagram. When copied, they are a real copy and become independently editable.
Lines can be sized in two dimensions like boxes and texts, but that their dimensions can be negative perhaps needs some explanation.
Boxes and texts are conceptually simple to size because their dimensions are always positive and the top and start-side border stay in the same place. To understand how to size lines, know that a newly-created line is a box without two of its edges, and so the two visible edges are exactly like the top and start-side of a box, namely, the top edge points to the end of the diagram, and the start-side points to its bottom. Increasing width or height positively extends the line in the dimension changed.
When decreasing a dimension of a line, the line gets shorter, and at 0 leaves just a straight line in the other dimension. Further decreasing the dimension, the dimension becomes negative and the line starts extending in the opposite direction. Throughout all these changes the point where the two edges join has not shifted, just like with a box. So the trick is to consider that point the origin of the line, so increasing height extends the vertical part of the line downwards, and vice-versa. And increasing the width extends the horizontal part of the line towards the end, and vice-versa.
Because lines have low visual priority, if they venture within the outline of another element, that part of the line that is within will be hidden. This means that lines don't have to be exactly matched to the edges of what they are supposed to be joining, allowing their dimensions to be less precise. Overlays themselves have the lowest visual priority, but their children have their normal priority, so a line will generally appear over the borders and background of an overlay, but behind any of its boxes, texts or arrows.
Diagrams will obviously not help those with severe visual impairments, but for many others, such visual paradigms also don't work.
We live in a world principally geared towards people with working eyesight, even if we need glasses. But just because we can see does not mean we will comprehend what any diagram using this element is meant to show. Just like words, diagrams are an arrangement of patterns, and just like some have difficulty visually understanding word patterns, many have difficulty understanding what the shapes mean, either in themselves or their spatial relationships.
Keeping diagrams simple enough to have their content easily understood means that they usually cannot carry the full narrative of the article, without including more content in them that would only confuse visually. Stick to using diagrams to illustrate simple concepts, relationships or workflows. Make sure their introduction accurately indicates what they are about, so the viewer will look for that information in the body of the article. It may be better to split content into separate diagrams to keep them simple.
This means that diagrams must not be the only way of communicating the information. Unless they can be used standalone, such as a visual table of contents, where the labels of the links would be read out by the screen-readers of the visually impaired, consider using diagrams in aside elements and using the article body to completely narrate the sequence, along with any clarifying comments along the way, perhaps with lists or tables.
The item limits applying to diagrams are:
- a.Diagram: 99 items, counting each overlay as one.
- b.Overlay: 50 items, counting each suboverlay as one.
- c.Suboverlay: 25 items.
- d.Element: maximum 1000px width or height.
- e.Line: maximum 300px negative width or height.
- f.Diagram: maximum 2000px width, 3000px height.
- g.Overlay|suboverlay: child origin is within its size.
These item limits are not expected to ever be exceeded. The limits for diagrams and overlays are for where an element can be positioned. With a width of up to 1000px, an element placed in the furthest corner with increase the diagram by its dimensions. Same for a extending a line or a moving an element in a negative direction. Allowing this excessive expansion is better than forcing absolute sizes, which would limit flexibility while designing, or moving all elements inwards because of an inadvertent negative movement.
Unless items are well spaced out, navigate using the element block hierarchy, or the keyboard as it allows tabbing forward or backwards from visible hover buttons to those for a buried element, which can then be selected by pressing Enter | return. An element can be selected for tabbing purposes by clicking somewhere in it (except if it has a link), then tabbing from there.
The tabbing order of elements is visual, proceeding from start-to-end then top-to-bottom, and they are shown in that order in element block lists. The content elements of an overlay or suboverlay are tabbed to after it. Later siblings of an overlay|suboverlay will have visual priority, even if some of its elements appear after or below them.
The stacking order works within the elements of a diagram, overlay or suboverlay, but not necessarily between them.
Which page elements are drawn over others is defined in CSS by each element's z-level, and this is used to enforce the stacking order specified earlier. All elements within a diagram will abide by its stacking order. Likewise in turn for overlays and suboverlays. However the stacking context for one overlay or suboverlay is different for its elements than another, and is different from that for the diagram itself. This is not an issue until two overlap and elements from one cover those of the other, where the one rendered later takes precedence.
The rendering order is by the top offset of each element, followed by the start offset, making the flow start to end, then top to bottom, with later elements in the flow taking priority over those earlier. Note that the coordinates are for an element's origin, with its body away and below, except for lines, which can have part of themselves before or above their origin, or have one dimension zero.
A related situation is that the hover buttons for a covered overlay's elements may not be directly accessible, so they need to be accessed for editing by either temporarily disabling the covering element, tabbing from an accessible element, or drilling down through the element block hierarchy, as might need to be done for a complex diagram with elements near or covering each other.