{"id":3366,"date":"2023-02-06T08:22:30","date_gmt":"2023-02-06T06:22:30","guid":{"rendered":"https:\/\/dox.fi\/?p=3366"},"modified":"2023-02-06T08:22:31","modified_gmt":"2023-02-06T06:22:31","slug":"how-to-adapt-the-webhelp-template-for-mobile-use","status":"publish","type":"post","link":"https:\/\/dox.fi\/en\/how-to-adapt-the-webhelp-template-for-mobile-use\/","title":{"rendered":"How to adapt the WebHelp template for mobile use"},"content":{"rendered":"\n

You can use DoX CMS<\/strong><\/a> to publish online content in the WebHelp<\/strong><\/a> format which applies a predefined frame to HTML<\/strong><\/a> content. I have previously discussed how you can adjust the appearance of this frame here<\/strong><\/a>. Here, I will instead discuss the details involved when you must adapt a WebHelp<\/strong><\/a> publication for mobile use. The default style for them includes rules for mobile devices, but these methods improve the mobile functionality of such content.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

Similarly to the prior piece, this piece will also primarily involve the use of CSS<\/strong><\/a>-based style sheets. This makes the information here most useful to those who can already write and edit style sheets.<\/p>\n\n\n\n

Content for mobile use<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

Tables<\/h3>\n\n\n\n

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.<\/p>\n\n\n\n

New content<\/h4>\n\n\n\n
\"\"
Screenshot of the text editor. Below the table, there is a definition list which is conditioned for mobile use and which has the same content as the table because of content references and shared variables.<\/em><\/figcaption><\/figure>\n\n\n\n

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.<\/p>\n\n\n\n

Prior content<\/h4>\n\n\n\n

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.<\/p>\n\n\n\n

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<\/strong><\/a> format that DoX CMS<\/strong><\/a> 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<\/strong> values to the paragraph (p) elements inside table cells, and add proper references to these elements as the Conref<\/strong> 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.<\/p>\n\n\n\n

Images<\/h3>\n\n\n\n

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.<\/p>\n\n\n\n

Conditioning<\/h3>\n\n\n\n

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.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

You can also control whether content with specific tags shows with a style sheet as I discuss here<\/strong><\/a> and here<\/strong><\/a>. 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.<\/p>\n\n\n\n

Style sheets for mobile use<\/h2>\n\n\n\n

The primary means to adapt WebHelp<\/strong><\/a> 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.<\/p>\n\n\n\n

Review the mobile view<\/h3>\n\n\n\n
\"\"
Screenshot of the cover for DoX CMS’s manual being inspected in a mobile view. The Inspect command and the Toggle Device Toolbar button have green frames.<\/em><\/figcaption><\/figure>\n\n\n\n

You cannot review WebHelp<\/strong><\/a>-publications directly with the Preview<\/strong> 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<\/strong><\/a> and its derivatives let you review content in a mobile device view directly from a desktop device.<\/p>\n\n\n\n

The image above shows how the Inspect<\/strong> command can show pages as they appear on mobile devices. In practice, this is what you must do:<\/p>\n\n\n\n

    \n
  1. Open the WebHelp<\/strong><\/a> publication in a browser through its index.html<\/strong> file.<\/li>\n\n\n\n
  2. Click on some element in the view with the right mouse button and select the Inspect<\/strong> command from the menu that this opens.<\/li>\n\n\n\n
  3. Then, click the icon for the Toggle Device Toolbar<\/strong> command in the upper left corner of the DevTools<\/strong> toolbar.<\/li>\n\n\n\n
  4. Specify the dimensions for the device and turn the view that shows with these commands in the toolbar above the view.<\/li>\n<\/ol>\n\n\n\n

    This view lets you make changes to the stylesheet(s) to see their effects before you edit the style sheets in DoX CMS<\/strong><\/a>. 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.<\/p>\n\n\n\n

    Challenges of mobile use<\/h3>\n\n\n\n

    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.<\/p>\n\n\n\n

    Scaled font sizes<\/h4>\n\n\n\n

    The majority of browsers for mobile devices scales the font size to the available space by default. Further information on this is available here<\/strong><\/a>. 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.<\/p>\n\n\n\n

    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<\/strong> 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).<\/p>\n\n\n\n

    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.<\/p>\n\n\n\n

    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<\/strong><\/a>. The demonstration below shows how you can disable this function completely.<\/p>\n\n\n\n

    * {\n -webkit-text-size-adjust: none;\n  text-size-adjust: none;\n}<\/code><\/pre>\n\n\n\n
    Vertical margins and flexbox<\/h4>\n\n\n\n
    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<\/strong><\/a> publications to the top of the view use a flexbox. Further information on this is available here<\/strong><\/a>.<\/p>\n\n\n\n
    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<\/strong><\/a>. Flexboxes, on the other hand, show all these elements’ vertical margins in full. For more information on margin collapses, see here<\/strong><\/a>.<\/p>\n\n\n\n
    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.<\/p>\n\n\n\n
    Touchscreens<\/h4>\n\n\n\n
    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<\/strong><\/a>.<\/p>\n\n\n\n
    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<\/strong><\/a>.<\/p>\n\n\n\n
    Styles only for mobile devices<\/h3>\n\n\n\n
    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<\/strong><\/a> publications on DoX CMS<\/strong><\/a> includes rules that only apply to<\/p>\n\n\n\n