You can use DoX CMS to publish online content in the WebHelp format which applies a predefined frame to HTML content. I have previously discussed how you can adjust the appearance of this frame here. Here, I will instead discuss the details involved when you must adapt a WebHelp publication for mobile use. The default style for them includes rules for mobile devices, but these methods improve the mobile functionality of such content.
These instructions will not directly address how you can adapt your content for mobile use given your current style sheets. I will also try to address situations in which the details of prior style sheets can limit usability on mobile unless you specify alternative values for mobile use.
Similarly to the prior piece, this piece will also primarily involve the use of CSS-based style sheets. This makes the information here most useful to those who can already write and edit style sheets.
Content for mobile use
Ideal content for mobile use is different from content that fits other online use and paged publications. You should thus also consider how the content is formulated if it will be published for mobile use. I will address such considerations below.
Tables
Tables are an important means to structure information. However, their proper use can often require more space than what mobile devices can afford. A device in portrait mode has considerably less of the horizontal space that tables with more columns need. Meanwhile, a device in landscape mode might not even show a full row of a given table at a time if it contains much content or if its content is packed to narrow but tall cells.
New content
If you must write the content for mobile use from scratch, avoid tables where cells must fit whole sentences. An exception to this are tables with two columns where the cells with full sentences have nearly the normal amount of horizontal space available. If tables would have three or more columns, use, for example, definition lists instead. The definition field (dd) can then have a list which corresponds to the cells of a table row. You can also use tables where the equivalent of one item consists of multiple rows of content. You can merge some of the cells on the extra rows to make room for longer content. The image above contains examples of such models for organizing content.
Prior content
If you must adapt former structured content for mobile use and it already contains tables which are not suited for mobile use, you should condition these elements to match where they will be used. There are instructions for how to do this below.
You can add alternatives like those described above for mobile use and condition them accordingly, in the way described below. Because all tables in the LW-DITA format that DoX CMS uses contain paragraph elements, you can reuse many of them through content references. This requires that the original cells’ contents are suited for use as, for example, list items (or additional paragraphs inside list items). Add ID values to the paragraph (p) elements inside table cells, and add proper references to these elements as the Conref values for the corresponding paragraph elements in the new content. This keeps this content in both versions the same with no extra effort needed even if you make changes to it later.
Images
As I emphasize in relation to style sheets below, mobile use generally requires that you use no metric units or inches. This also includes elements where such values were added in the text editor. Images are the prime example. Ideally, image size depends on element classes that let you control it through the style sheet in different situations and simultaneously across all of them. However, if image sizes in the editor are in non-scaling units such as millimeters, you must change these values to scaling units for publications used on mobile. You can also override them with the style sheet. This involves maximum dimensions that you specify for mobile use. Instructions for this are available below.
Conditioning
Tag-based conditioning lets you make publications where you will only include the versions which are suited for mobile use if you set them up like I described above. This lets you use the content that you conditioned like this either to publish online in general, because adaptations for mobile use do not limit other usage, or as publications intended only for mobile use.
In practice, you must add a new tag category with separate tags for mobile publications and other publications to do this. You must then apply these tags in the editor to the parts of publications that have separate versions for mobile use. Use the tag for mobile publications on the elements suited for mobile use and the alternatives other tags from the same category that match their use cases. Finally, specify as part of each related publication template whether they are to be published for mobile use or not. For each, use the corresponding tag to filter out the alternatives.
You can also control whether content with specific tags shows with a style sheet as I discuss here and here. As such, I will describe below how you can use a style sheet to only show the proper content for a specific device in the same publication.
Style sheets for mobile use
The primary means to adapt WebHelp publications for mobile use relies on style sheets. Fortunately, you can specify separate rules only for mobile devices. If you are already happy with your style in other situations, you can just provide the exceptions that apply to mobile devices and add them to that style. If you want to keep the style sheet(s) for the default style well-organized, you can add these parts either at its end or in a different style sheet.
Review the mobile view
You cannot review WebHelp-publications directly with the Preview command. They must be published first. You can then review them in your browser. This will almost invariably involve a desktop device rather than a mobile device. This would require you to make the content available online to review it on a mobile device. Fortunately, at least some browsers such as Chrome and its derivatives let you review content in a mobile device view directly from a desktop device.
The image above shows how the Inspect command can show pages as they appear on mobile devices. In practice, this is what you must do:
- Open the WebHelp publication in a browser through its index.html file.
- Click on some element in the view with the right mouse button and select the Inspect command from the menu that this opens.
- Then, click the icon for the Toggle Device Toolbar command in the upper left corner of the DevTools toolbar.
- Specify the dimensions for the device and turn the view that shows with these commands in the toolbar above the view.
This view lets you make changes to the stylesheet(s) to see their effects before you edit the style sheets in DoX CMS. However, note that not all changes that you make like this will also have exactly the same results when you publish the content after you make the same changes to your style sheets. You must always review such publications afterwards because of the risk of such differences.
Challenges of mobile use
I am not a developer for mobile. This made the experience of adapting a style for mobile frustrating at times because of the innate functions involved. Such functions change the layout without them showing as part of a style sheet. My observations may not even include all the relevant functions like this. You must thus acount for the possibility that otherwise inexplicable behaviour can relate to some such difference in how mobile devices operate.
Scaled font sizes
The majority of browsers for mobile devices scales the font size to the available space by default. Further information on this is available here. These browsers try to retain sufficient functionality like this even when the page is not designed with mobile use in mind. Such scaling is based on available space, especially available horizontal space. This can make the font sizes for some elements shift seemingly at random.
I stumbled into this when I examined why the font sizes for the number identifiers for topics did not match the font sizes of the rest of their titles. Depending on the orientation of the view, the number identifiers became either smaller or larger than the rest of the titles. The cause was eventually revealed to be how the .titleNumberWrapper field for these number identifiers was specified to be an inline-box. This detail added hidden frames within which their font sizes were determined. The solution was to change their display mode to inline (on mobile devices).
You should also note that sometimes the content that looks off actually matches your specifications and the content that looks good was scaled to that size by this function. In this case, you should check the font sizes for these elements and set them to what you need.
If you want to ensure that the results are predictable or that any issues are related to this function, you can use a style sheet to control such automatic scaling of font sizes. You can enable this function or change its settings in browsers which support it. You can also disable it entirely. Further information on this is available here. The demonstration below shows how you can disable this function completely.
* {
-webkit-text-size-adjust: none;
text-size-adjust: none;
}Vertical margins and flexbox
This section is not directly related to mobile devices. However, flexbox is a good way to make a view more mobile friendly. It lets specify proportional dimensions for elements and to reorganize them. For example, the instructions that I provide below that let you move the transition buttons in WebHelp publications to the top of the view use a flexbox. Further information on this is available here.
You must note, though, that elements displayed with a flexbox also do not adhere to all the same layout rules otherwise. The most relevant feature like this involves vertical margins not collapsing. The vertical margins for content usually collapse to only use the largest applicable value instead of summing them all together. This applies to both embedded and sequential elements’ margins. This is a feature of the block model used by default. For more information on the block model, see here. Flexboxes, on the other hand, show all these elements’ vertical margins in full. For more information on margin collapses, see here.
As a result, you should check the vertical margins of your content if you use a flexbox layout on mobile (or otherwise). You can retain the original layout like this if you use halved vertical margins for elements in sequence which each had the same vertical margins between them. At either end of such a sequence, you can remove the vertical margins that face that direction from the element that has the lower vertical margin there. If this will only affect mobile use, you can specify these vertical margins for mobile use only with the additional selectors introduced below.
Touchscreens
The users of mobile devices do not usually connect them to accessories that let them use pointers with these devices. Without a pointer, you cannot interact with content in ways which would depend on one. The most common example involves moving the pointer above a specific element. You can add rules to such situations with the :hover selector. For more information on the :hover selector, see here.
If the layout or style of your content involve such selectors in ways which would limit the content’s usability with touchscreens, you must change them. This may require a wider renovation of your layout. In some instances, it can instead be enough that you also add the :active selector to these parts of the layout. This makes the rules actvate when someone selects the affected element. You can select with a touchscreen when you press the element for a moment and do not just touch it momentarily. For more information on the :active selector, see here.
Styles only for mobile devices
You can specify some styles to only apply on specified types of devices. The most common condition for this involves screen size. For example, the default style for WebHelp publications on DoX CMS includes rules that only apply to
- viewports that are 1279 or fewer pixels wide,
- viewports that are 1023 or fewer pixels wide, and
- viewports that are 767 or fewer pixels wide.
Each of these cutoff points is specified separately in the default style sheets, and each is associated with its own set of rules.
You write such additional selectors with a @media selector and associated further specifications. Further information on this is available here. You can use such selectors as a higher order selector inside which you write associated rules as though it were its own style sheet: such embedded parts include both selectors and the associated rules. You can have more than one such selector inside the @media selector’s parentheses and they must each have their own sets of parentheses. I will provide an example below, where viewports that are 1279 or fewer pixels wide will have red backgrounds in landscape mode and yellow backgrounds in portrait mode. It also sets the default text color to white in landscape mode. Such immediately obvious effects let you test the thresholds and functioning of @media selectors. Remove them before you proceed with your edits to the style sheet.
@media only screen and (max-width: 1279px) and (orientation: landscape) {
body {
color: white;
}
.topicWrapper {
background-color: red;
}
}
@media only screen and (max-width: 1279px) and (orientation: portrait) {
.topicWrapper {
background-color: yellow;
}
}Better space management
Mobile devices have considerably less available space than desktop devices. As such, you should remove any excess empty space to improve space management. The default setting for WebHelp publications on DoX CMS do not do this enough for mobile use. I cannot provide you with default values that will work in every use case. You must adjust the values to fit your manuals.
Size boundaries
Ideally, you already use element classes to control details such as image sizes and the widths of table columns instead of their settings in the text editor. In this case, you can directly change their values with a style sheet. This lets you give them different values on mobile with the method provided above. If this is not the case, you can still specify maximum and minimum dimensions in different situations while on mobile. This limits values that go past these thresholds to these values. Images, for example, would then not be too large for mobile use even when their original sizes were defined in non-scaling units such as millimeters.
You can provide different boundaries for different situations, such as to keep images inside tables within the space available to them. In this case, you can use percentages for the maximum size of images inside table cells to let cells sizes determine how big the images can be. This only applies when the space available within these tables is already defined, though. If tables use automated layouts, you must instead provide the maximum dimensions for images in unrelated units such as those linked to font size (rem or em) or pixels. You can also provide similar values for cases such as images immediately inside figure elements or list items.
A key values in this respect is the maximum width for the content field. If you will use specific layouts in different situations such as for landscape and portrait modes on mobile, this value contributes greatly to that. The default style sheets already have a defined value. Thus, you must use the !important qualifier to replace it. Below, I present a means to do so. I use the default value which you can then adjust to fit the situation.
.topicWrapper {
max-width: 750px !important;
}Margins
When space is limited, unnecessary margins are the first thing to cut. In this context, margins include any form of empty space around elements rather than only the values for the margin rule. In particular, you must set the margins for the default elements which are not a part of content proper to match the use case. Otherwise, a small mobile viewport in landscape mode may only show half a text row at once, and the limited available space even prevents scrolling through the content.
To help with this, you should adjust details such as the vertical margins for titles, at least in landscape layouts. You can also remove the margins around the whole WebHelp publication from mobile viewports. I present the values that I applied to the manual for DoX CMS below. You can adjust them to fit your style sheet.
@media only screen and (max-width: 1279px) {
.tocTitleWrapper {
padding: 12px 20px !important;
}
.paginationWrapper {
margin-top: 10px !important;
}
body {
padding: 0 !important;
}
h1, h2, h3, h4, h5, h6, h7, h8 {
line-height: 1em !important;
margin: 10px 0 10px 0 !important;
}
.documentBodyWrapper {
padding: 20px !important;
}
p {
margin: 0.6rem 0 !important;
}
}Move transition buttons
By default, the transition buttons to the previous and next section show at the bottom of the view. A mobile device in portrait mode can leave these buttons apart, when content does not cover the available vertical space. To address this by reorganizing the view, you must use a flexbox. As such, you may have to define the vertical margins for content again if you do so. More information on flexbox in relation to vertical margins is available above. I show a solution that moves these transition buttons above the content titles below.
.topicWrapper {
display: flex;
flex-direction: column;
}
.paginationWrapper {
order: 1;
}
.titleWrapper {
order: 2;
}
.topicBodyWrapper {
order: 3;
}Switch to mobile content
Elements retain their tags and you can use tags to control their visibility as I explain here. Thus, one publication can include both the elements for mobile use and the elements not for mobile use. The system will only show the appropriate versions of said contents for each use case.
First, condition the content based on its use case like I described above. Select each tag associated with these different use cases to be used by the publication template. You can, for example, define the same content to be in use both in the default view and the landscape mode on mobile but use a different one in the portrait mode on mobile. In the example I provide below, all mobile views will use the same content which was conditioned for mobile use only.
The tags involved are just an example. If you use these rules, instead use the values for your tag categories and the tags within. You can also change which content shows and when. This example uses the same qualifiers for mobile use as the default rules for mobile use in WebHelp publications on DoX CMS.
*[data-doxattribute-usecase="mobile"] {
display: none;
}
@media only screen and (max-width: 1279px) {
*[data-doxattribute-usecase="mobile"] {
display: initial !important;
}
*[data-doxattribute-usecase]:not([data-doxattribute-usecase="mobile"]) {
display: none !important;
}
}Summary
Not all content and not all settings for content are suited for mobile use. Thus, if you know that your publications will be available on mobile, you can formulate them accordingly. You can either use types of content suited for mobile for everything or add new publications specifically for mobile use. The biggest issue are tables with many columns. You can replace them with definition lists, for example. If you have separate versions of the content for mobile use, you can use tags to differentiate them from the default versions. Content references (conref) are the simplest way to keep the content between the two versions identical. Use parts of the default versions as source elements. The best way to define image size involves element classes. If you use the editor for this instead, you should avoid metric units and inches.
When you edit a style sheet for mobile use, you can review the results with the Inspect command. At least Chrome and its derivatives also let you emulate different mobile viewports when you do this. Do note how the changes that you make in the browser might not be reflected in full by the publication when you add these changes to its style sheet and publish the content again. Always review the content in the changed publication again.
The most important tool to make WebHelp publications suitable for mobile use are style sheets. Changes to them have their own challenges, though, such as font size scaling which only applies on mobile. Touchscreens also do not support functions which rely on pointer position. You can respond to these challenges when you acknowledge them beforehand.
You can define rules only for mobile devices when you place the selectors and associated rules inside selectors that use media queries. Use this option to reduce unnecessary margins that take up space that you need for content, and to specify boundaries for the sizes of various elements. When you do this, an image set to be ten centimeters wide for printing purposes will not stay the same on a five centrimeters wide smartphone screen. You should also consider the layout and changes to it which improve mobile use. For example, screens that can be tilted work better with transition buttons that you move to the top of the view with a flexbox layout. Otherwise, there is a risk that they are left separated from content proper.
The most extreme form of adaptation for mobile use involves conditioned content and controlling its visibility with style sheets. This involves conditioning the content based on its use case. The publication itself will include each version of such content, though. You only show one situationally appropriate version at a time by using a style sheet to hide the alternatives that have different tags from this tag category.