Help requests from users commonly relate to page layout. Because the documents written in DoX CMS are compiled from the selected contents rather than made with a specified page layout, the results can at times feel less than satisfying. To avoid such situations, you can take precautions, though. The system will also bend to let you make limited changes to the page layout directly when necessary. In this article, I will highlight methods to both avoid such situations and to control documents’ layouts directly.
Should anyone who does not use DoX CMS read this piece for general CSS-related instructions, they ought to note how many of the mentioned classifications are system-specific.
Recommended precautions
You may both add rules related to page breaks in the style sheet and write documents in a manner that is more friendly to them in advance.
The style sheet accommodates rules that add, shift, or avoid page breaks. You may also limit the sizes of various elements.
The practices involved in writing material for documents also affect the need for additional page breaks. You can consciously make the content’s layout respect predetermined page breaks.
Both methods are discussed below. With respect to style sheets, I will also share information on related CSS commands.
Orphans and widows
The most common reason for an experienced need to control page breaks are orphan and widow rows of text. Orphans are individual lines that are left at the end of the preceding page. Meanwhile, widows are individual lines that are pushed to the beginning of the next page. In both instances, the results are unseemly and may also disrupt the usability of the document.
These expressions technically only denote the contents of paragraphs. However, this section will also reveal how the problem can be avoided in relation to lists, tables, and the titles of various elements.
Splitting paragraphs
There are CSS commands that specifically target how paragraphs are divided between pages. In relation to them, it is important to note how the lightweight DITA (LW-DITA) format that DoX CMS employs also includes paragraph (p) elements inside list items, for example. There are other reasons to pay attention to this fact, too, but it also entails that you need not apply these commands separately to other kinds of elements.
The command ‘orphans: X;’, where X is a positive integer, applies to blocks of text and it specifies the minimum number of rows that is allowed at the end of a page. For example, if you add the string of code below to a style sheet, it will make each paragraph that is split by a page break leave a minimum of two rows of text on the preceding page. If this proves impossible, the whole paragraph is shifted to the next page.
p {
orphans: 2;
}Correspondingly, the command ‘widows: X;’, where X is a positive integer, tells the minimum allowed number of rows of text in an element after a page break. If fewer rows would be included otherwise, more content from the preceding page is transferred to the new page. The example below adds this command. It tells the PDF compiler to include a minimum of two rows of text in a paragraph on the new page if the paragraph is split by a page break. If too little content would be left on each page, the rule related to orphans takes precedence and moves all content on the new page.
p {
orphans: 2;
widows: 2;
}As with all additions to a style sheet, you may also specify a more restrictive selector. Should you, for example, need to give different specifications related to the rows allowed on each page when list items are split by page breaks, you would use the same commands. To do so, you would target the paragraphs (p) that are child elements to list items (li).
Lists and tables
The commands provided above only work on individual blocks of text. Thus, they do not let you specify how many child elements such as the rows in a table must be included on each page when a split occurs. To anticipate such situations, you must instead target child elements that you count both from the start and the end of the parent element.
The examples below related to both lists and tables assume that each must leave a minimum of two child elements on each page. For this reason, they only include rules for the first and the last child element in each instance. Should you need to ensure that three or more child elements are left on a given page, you would need to repeat the command for the second and/or second to last child element. The instructions on how to target these elements can be found here and here, respectively.
The commands ‘break-after: avoid-page;’ and ‘break-before: avoid-page;’ tell the PDF compiler to avoid page breaks after or before the designated elements. This shifts required page breaks to the next allowed position. Do note how abusing these commands may lead to compromises. They tell the system to avoid page breaks in the specified positions where possible. If these commands apply across the board, it leaves the system fewer chances to respect them in each instance. The command ‘break-inside: avoid-page;’, on the other hand, tells the system to avoid page breaks inside the specified element. It is recommended for at least table cells to avoid making a single table row be split between pages.
// kaikki taulukot (all tables)
table th {
break-after: avoid-page;
}
table tr:first-child {
break-after: avoid-page;
}
table tr:last-child {
break-before: avoid-page;
}
td {
break-inside: avoid-page;
}
// numeroidut ja numeroimattomat listat (ordered and unordered lists)
ol li:first-child, ul li:first-child {
break-after: avoid-page;
}
ol li:last-child, ul li:last-child {
break-before: avoid-page;
}The same logic can be extended to other situations such as rules for definition lists. However, such further examples are excluded from the examples provided above.
Titles
At times, the titles of sections or specific types of elements may be left on a different page from the associated content. To control them, you can use the same commands as in the instances discussed above. The most important difference here concerns the use of the correct selectors. The example below assumes that the titles of tables lie above them and that the titles of figures lie below them.
// osioiden otsikot (section titles)
.titleWrapper {
break-after: avoid-page;
}
// taulukot (titles of tables)
.dita-table .dita-title {
break-after: avoid-page;
}
// kuvat (titles of figures)
.dita-fig .dita-title {
break-before: avoid-page;
}Should you want to always start sub-sections or other types of elements from a new page, you may also add page breaks before each such element. For elements other than whole topics, it is best to do this with the element classes in DoX CMS. The example below uses an example element class called ‘UusiSivu’ (‘NewPage’). If you only need the topics in a specific position in the hierarchy of content to be affected, you may target the class ‘.titleWrapper_LevelX’, where X is the intended level of organization.
// osioiden otsikot (section titles)
.titleWrapper {
break-before: page;
}
// elementtiluokat (element classes)
[doxelementclass="UusiSivu"] {
break-before: page;
}Element dimensions
If individual elements are too large to leave room for the necessary other elements such as associated titles, the system may need to split the two on separate pages despite the rules listed above. This issue mainly concerns images inside table cells or figure elements. In the case of tables, it may also force the content beyond the boundaries of pages or table cells in the absence of sufficient space otherwise.
The solution to this problem is determining maximum dimensions. It best to set a maximum width for pictures regardless to avoid them stretching past page borders. It is often a good idea to control their dimensions directly via the DITA attributes of the attached image files. More information on this is provided below.
The example below shows how to set maximum dimensions for images inside tables and figure elements. It also includes a general setting for other pictures to avoid them stretching past page borders horizontally. The used values are but a demonstration but their purpose is to avoid situations in which the sheer size of an image functionally prevent a layout where other associated elements fit on the same page.
// kuvatiedostot kaikkialla (image files everywhere)
img {
max-width: 100%;
}
// kuvaelementtien kuvatiedostot (image files in figures)
.dita-fig img {
max-height: 200mm;
}
// kuvat taulukoissa (image files in tables)
td img {
max-width: 50mm;
}In the case of figures and tables, the provided values are not in percentages but in amounts of millimetres suitable for standard A4 sheets. The reason for this is how percentage values relate to the dimensions of the parent element. In the case of height, such values do not necessarily correspond to page height, and in the case of tables, it would not prevent the excessive stretching of cells. Should different values be needed in different situations, thet can be set for individual images in their DITA attributes or with the help of element classes.
Content layout
Content layout is subject to a range of considerations. As such, it cannot always be optimized with page layout in mind. Should the need arise, you can still affect page layout through how you order your content, however.
Large elements to either end
Large elements require considerable space. This is why I would recommend reserving them either for the start or the end of a given section. The option to include them at the start of a section works best when each section starts from a new page as this ensures that there will be enough space directly below the section title. To push these elements to the ends of sections ensures that large elements can have their own page each where necessary without other elements needing to be split to accommodate this. This option may cause a single page in a section to be left with a large empty space but this scenario would be prevented from repeating across the whole section.
Large elements include figures and tables in particular. They require considerable space and their contents are generally larger than individual rows of text. In some instances, lists may also require that their contents fit a single page with no breaks in-between.
Avoid chaining notes
Warnings and other cautionary notes are mostly included as note elements. They often include either an appropriate image or the name of the note’s type or both. In most cases, these details are most convenient to specify in the style sheet. However, one consequence of this fact is that these additional details are harder if not outright impossible to target with some forms of further formatting such as the commands involving page breaks. As such, the more of such elements you add in succession, the greater the risks involving their proper formatting become.
Such risks include at least the following:
- The clarification of the note’s type and its content end up on different pages,
- The associated image and the note’s content end up on different pages,
- The associated image is cut in two by a page break, or
- The associated image extends into the page footer.
Different risks are associated with different implementations of these details. Some of them can be addressed with the help of CSS when these details are implemented in suitable ways. For example, an image set as a background can be cut in two by a page break. However, if you use the command ‘break-inside: avoid-page;’ (see above) to prevent page breaks inside note elements, you can avoid this issue. Yet most of the time, at least some of such additions must involve pseudo-elements such as ‘::before’ and when this happens, we cannot guarantee that the commands related to page breaks are fully compatible. Such limitations are not unique to DoX CMS.
For this reason, it is best to avoid multiple notes in succession. Should they be positioned immediately before or after figure elements, for example, the maximum height of such figures ought to reflect the additional space that said note(s) require. If it is necessary to include multiple note elements in succession, consider using an element class to add a page break before the first note and making sure that all the notes fit on a single page.
Direct formatting
Sometimes, you cannot ensure a satisfying result with precautions alone. Such measures reduce the risk of a failed layout considerably but they cannot entirely erase the possibility. When precautionary measures are not enough, you must apply direct formatting.
There are several challenges related to direct formatting in DoX CMS, though. Firstly, the system only includes a dedicated page break command for when a topic must start on a new page. Elsewhere, you must use a dedicated element class to the same effect. Secondly, the contents in structured documentation are often intended to be used in more than one document. In these instances, an added page break may only be needed in a subset of instances rather than each. This includes the translated versions of the same document.
I will explain how direct formatting can be implemented in DoX CMS and the involved considerations below.
Add page breaks
At the level of individual topics, you can use the selection field at the top of the text editor to add a page break before a given topic. If page breaks must be added in specified positions inside these topics, it must be done with the help of element classes. You can add a new element class to the system in their own meny under the Tools icon. Once you have added an element class, you can add a command that forces the PDF compiler to include a page break either before or after the elements to which it is applied. Both options are demonstrated below. The example element classes are called ‘UusiSivuEnnen’ (‘NewPageBefore’) and ‘UusiSivuJalkeen’ (‘NewPageAfter’). Remember that the title of the element class and the selector in the style sheet must be the same. Outside this detail, the actual title of the element class has no effect on functionality.
// sivunvaihto ennen (page break before)
[doxelementclass="UusiSivuEnnen"] {
break-before: page;
}
// sivunvaihto jälkeen (page break after)
[doxelementclass="UusiSivuJalkeen"] {
break-after: page;
}To apply an element class to an element, you must first select the element in the text editor. Once you do, open the list of element classes on the editor’s toolbar and click on the relevant element class there. The system will apply that element class to the selected element.
Make the page breaks conditional
When the same content is used in more than one document, the same experienced need for a page break in a specific position may well not exist in each. Although, if the relevant topic itself always starts on a new page, its contents will likely have largely the same page layout everywhere unless parts of it are conditional content.
To bypass this issue, it is generally for the best to first make a copy of the element and only then apply the element class in one of the two. This makes it possible to use tags to make both conditional in ways where the correct one is always included in a given document. In practice, you just add tags related to the document(s) that require the additional page break on the element with said element class. The copy can then be labelled with the tags in the same category which relate to other documents. This arrangement ensures that only one version of the element will be included in any given document and that the additional page break will not be inherited by all documents that include the topic with that element.
Check translations separately
The same content may involve different text lengths in different languages. This is why additional page breaks do not necessarily occur in the exact same positions on the page in different languages. Thus, whenever you apply additional page breaks in the proposed manner, you must review the translated documents for how their contents are placed. The element class responsible for the page break may be removed or moved to a different element in the revisions for other languages.
To do this, you must first publish the document as a PDF in the target language and browse through it. If the page break must be moved, you can then open the revision of the topic in that language and add the element class in the manner explained above. If you must remove the element class from an element, you may only do it in the source view of the content.
Once you open the content in the source view, find the position where the relevant element has been specified a value for ‘doxelementclass’ and erase both this variable and its value from the code. When you return to the initial view, first make sure that this change did not incur an error message. If the editor gives you an error message, close the topic without saving changes and try again. If there is no error message, you may save the contents of the revision.
Set column width for tables manually
In addition to page breaks, you may need to control the column width of at least some tables directly. The default setting is that the widths of table columns are calculated automatically. This process is susceptible to fail states where the results are unusable.
If you so desire, you may set the width of all table columns yourself or you may use an element class in the instances where this must be done. Even for automatically calculated tables, you have the option to set the width of some columns manually. To do so, open column properties and specify a value for its width in either percents or millimetres. However, unless you use the method described below, the table may still end up broken even if you do this for each of its columns.
To entirely avoid such issues, use fixed width table layouts instead of automatically calculated ones. Such layouts may also produce broken tables but the difference lies in your level of control over this. Columns with automatically determined widths may break the table itself. Columns with a fixed width may be too narrow for their contents in which case that content may stretch past their borders. This can be fixed either by editing said content or by making the column in question wider.
To use columns with fixed widths, you may use the CSS command provided below. Both a general version and one suitable for element classes have been included. The element class in the example below is called ‘VakiTaulukko’ (‘FixedTable’). Determining total width is a necessary part of the process and you may elect for narrower tables.
// yleisversio (general version)
table {
table-layout: fixed;
width: 100%;
}
// elementtiluokka (as an element class)
[doxelementclass="VakiTaulukko"] {
table-layout: fixed;
width: 100%;
}Summary
DoX CMS is not a piece of software suited for formatting text layouts. It is a content production software intended for writing reusable and modular content.
Formatting that content is primarily reliant on specifications in CSS. It is thus important to be cognizant of situations where you must have a specific layout in advance. Style sheets let you write rules to resolve such situations without requiring your manual input each time.
It is also possible to affect the need for later direct intervention by ordering your contents with such considerations in mind. Ideally, the content would be written in a form which would reduce layout-related risks in the first place.
When you must add page breaks with the help of element classes, do note the differences between the different contexts where the content is used. Remembed to mkae the content conditional to also account for situations where the additional page break is not needed. When you do this, you must also remember to review the translated versions to inspect their page layouts.