Style sheets are not merely a means to define layouts for finished publications. You may use distinct styles to highlight parts which are relevant for preview purposes. The layout rules need not be limited to styling included content, either. You can hide some parts situationally. Such options effectively let you add new features to a system.
I will dedicate this piece to exploring methods that let you show the identifiers of different document parts, such as the targets for links and which tags were used, and to situationally adjust the title format for various elements in DoX CMS. Mind how these methods involve the use of CSS style sheets.
I have previously discussed similar ways to use style sheets in the following posts:
Styles for previews
You can have dedicated styles that are never used for deliveries. With the help of style sheets, you can show distinctions and information which only benefit draft reviews. An earlier example of this principle is a notification about figures with missing images, for which I suggested an implementation here.
This time, I will focus on how to show the values for elements’ attributes in a preview document, and how to highlight elements with tags according to the tag categories involved. I will also suggest several minor changes that also help with previews. For more information on how to designate elements based on their attributes such as tags, see here.
Unfortunately, you cannot show the sources of images like this, because images cannot have elements below them in the content hierarchy.
Show attributes
Where does this link lead? Which tags did these elements have again? Which elements did I give specifications such as set width in the text editor, and what were the values that I used?
The review process occasionally involves such questions, and simply browsing a publication provides no answers to them. For incidental cases, you may of course find these values from the document previews in DoX CMS with your browser’s Inspect command.
The method I am about to describe shows whichever attributes you specify as part of the document being reviewed. This method requires that you specify which attributes to show and how they are presented.
Attribute values
You can show attribute values with pseudo-elements added either at the start or the end of each related element. Each element can only have one such pseudo-element on each end. As a result, you must specify all shown values at once instead of having separate rules for each.
To show an attribute in this way, you must use the value ‘attr()’ as part of the ‘content’ rule and add the name of that attribute inside these parentheses. For example, you can show ID values with the rule ‘content: attr(id);’, which you must then add as a ::before or ::after pseudo-element to the relevant types of elements. The selector for this should also itself include the relevant attributes. The simplest expression for this is the name of the attribute inside angled parentheses, such as ‘[id]’. For more information on selectors based on attributes, see here.
I provide some examples of the values that you can retrieve like this below. These examples do not yet include any rules for how to present these values. I chose the ::after pseudo-element for this because it has fewer other uses than the ::before pseudo-element.
ID
[id]:not(body)::after {
content: attr(id);
}
This format shows the ID values of all elements that have them when this style is in use. This lets you see any errors in these values more easily, for example. That will prove particularly useful whenever links to a specific element do not function. The system also adjusts ID values in some circumstances. The most common such circumstances involve an otherwise repeated ID value, and multilanguage publications which add language identifiers.
Href
.topicBodyWrapper [href]::after {
content:attr(href);
}
This format shows the targets of link elements. You need to include ‘.topicBodyWrapper’ here to not apply this rule to the links in the table of contents as well. This way, you will see the ID values of the links’ targets and the topics that contain them. You can then easily find them in the Editor menu. The format also shows the targets of external links if you must check their format.
Style
[style]::after {
content:attr(style);
}
If you give elements style-related values in the text editor, you can show them like this. You cannot show the dimensions of pictures, though, because you still cannot make these additions to image elements. As such, the most common way to use this value is to show the widths of table columns that were added in the text editor.
Tags
[data-doxattribute-manual]::after {
content: 'Manual: 'attr(data-doxattribute-manual)'';
}
[data-doxattribute-device]::after {
content: 'Device: 'attr(data-doxattribute-device)'';
}
[data-doxattribute-manual][data-doxattribute-device]::after {
content: 'Manual: 'attr(data-doxattribute-manual)'\A Device: 'attr(data-doxattribute-device)'';
}
When you use this method to show the tags used to filter content, the preview will clearly show which elements are not shared between all publications. You can also review a publication which includes the alternatives for all related publications. You will then see the parts used for different publications side by side.
The examples of tag categories that I used above (manual and device) are based on the showcase content for DoX CMS. I chose to use two categories to demonstrate how you can show the values for different categories at the same time. In effect, you must specify the rules for each possible combination of tag categories separately to manage this. This can prove strenuous as the number of categories increases.
I also decided to show the names of included tag categories. I did not differentiate between languages for this because that infomation is not included in deliveries. The part with ‘\A’ adds a forced line break between categories.
Attribute presentation
You have several alternative ways to present attributes’ values. Besides deciding on the placement of the text that shows said values, you can also highlight the marked elements in various ways. You can also limit how much these additions distort the view by only showing attributes’ values for elements under a cursor. Highlighting them first helps identify the relevant parts for this. This way, everyone will know which elements to target with their cursors. This option only functions for responsive formats such as HTML which is also used by the preview and review features of DoX CMS. For example, PDF publications cannot respond to a cursor like this after you compile them.
Below are some examples of each such alternative. The option that involves the cursor just combines the other two solutions, and you must add the pseudo-class ‘:hover’ to the selector related to showing attributes’ values. I will not thus separately list an implementation for it.
Show values
*::after {
display: inline-block;
float: right;
color: lightgrey;
}
This implementation assumes that you will use ::after pseudo-elements for all values as I suggested above, and that there are no other uses for ::after pseudo-elements in your publications. As such, I can just specify the rules for all ::after pseudo-elements on any element at once. If you needed to add exceptions to this rule, you would have to account for them in the selector with qualifiers like ‘:not()’, for example. Alternatively, you can specify the exceptions later in the style sheet with more specific selectors, of course.
In this case, you will just see the values in question as light grey text which shows in the lower right corners of the related elements. You can change these details to suit your needs. In this case, all types of values use the same rules to avoid having to specify the rules separately for each alternative. You can use different colors for different attributes if needed.
Highlights
[data-doxattribute-manual] {
background-color: rgba(50,205,50,0.5);
}
[data-doxattribute-device] {
background-color: rgba(159,0,255,0.5);
}
*[data-doxattribute-manual][data-doxattribute-device] {
background-image: linear-gradient(to right, rgba(50,205,50,0.5), rgba(159,0,255,0.5));
}
It is easier to identify elements with specific attributes when you highlight them in different ways. You can also use these methods even when you do not show the actual values in the way that I presented above.
Such highlights can be based on having any value for a given attribute such as any tag from a specific category, or on having specific values for these attributes. You can also realize them in various ways. My example is based on tag categories with different background colors. I used a semitransparent color because this color becomes deeper for elements with tags embedded in parents with the same tags. This way, you can still tell the tagged elements apart without other details such as added frames. I also made sure that you can identify elements with tags from more than one category, as there is a gradient between the colors associated with each such category.
Other aids for reviews
Here are a few other ways to use styles written to only be used during review to help with that process.
Visible missing links
.topicBodyWrapper a {
display: inline-block;
border: 1px solid black;
min-width: 1em;
min-height: 1em;
}
At this time, our system does not tell or otherwise show to the user if some link in a publication fails to find its target. Related positions will just display nothing that expresses that there are links there. This rule temporarily adds frames and minimum dimensions to link elements. This makes empty links show up as framed empty boxes.
Like this, you can easily find both internal links to parts outside that publication and external links without added anchor text. Internal links without targets can also result from their target accidentally being left out due to filtering or an outdated topic tree.
Highlights for empty elements
*:empty {
height: 1em;
background-color: rgba(255,0,0,0.5)
}
Usually, I recommend that you hide empty paragraphs, for example, because it is easy to accidentally add them. This is not the ideal solution to all empty elements, though. Sometimes you just forget to add content to some table cells, for example. You can also leave behind empty framing elements when you filter out tagged content and the tags were applied at the wrong level.
In this solution, all empty elements have a red background and a minimum height equal to one line of text to make sure that they are visible.
Hide covers and the table of contents
.coverPageWrapper, .tocWrapper {
display: none;
}
If you review the same content repeatedly and you have already made sure that the covers and table of contents have no issues, you can save quite a bit of time and energy by hiding them. You would then no longer need to scroll past them to start reviewing the actual content.
In DoX CMS, you can also do this in the settings for a style instead of using a style sheet for it. This is an easier solution for users who do not want to touch style sheets. It is faster to switch this setting on and off with a style sheet, though, if it is not buried deep inside one. This ability should prove particularly helpful for testing a style sheet with content previews, since you are not using a style for previews but rather, previewing the style.
Different page headers and footers
You specify page headers and footers in DoX CMS as part of a given style. This is thus not a matter of editing your style sheets but rather, you need to write new headers and footers to use with your preview styles. I will thus not provide direct examples of how to implement this.
However, you can add information only needed for review purposes to the page headers and footers of a style for reviews, such as
- a marker that this is a draft for review,
- the date when it was published,
- the revision number of the publication, or
- the username of the person who published it.
For most of these details, you can use the system variables in DoX CMS which retrieve that information from the system and place it there when you publish the content. In the case of the default PDF compiler in DoX CMS, you can also use values that you make conditional with tags. You cannot do that when you publish with DocRaptor.
Adaptive title format
By default, the same format for element titles in DoX CMS is applied to all related types of elements. They all share a title format which you can change in the Settings menu. The same format also gets used in internal links targeted at these elements. You can, however, add identifiers around parts of this format, and then you may add layout rules to these identifiers to situationally control the visibility of these parts. This allows you to show a different title format in different contexts.
Thus, you can do this to use different formats for different elements’ titles, or to have a different format between an element’s title and links that target it.
Different titles for different elements
You can have the titles for different types of elements use different formats. Normally, the three main distinctions are based on possible values of the system variable {{series}} which gets replaced by the variables
- {{figure}}
- {{table}}, and
- {{default-series}}.
In this case, all the other parts of titles remain the same between applications.
However, the field used to write the template for element titles is compatible with structured content in HTML and corresponding identifiers. You may then control the situational visibility of different parts with the identifiers that you added like this. If you would prefer not to write complex distinctions such as tag-based filters inside this field, you may also add such further distinctions inside variables used there and controlled by you.
Title format
Because you can write HTML tags directly in the title format field, you can utilize both elements and attributes. Since you write the values here yourself, you can also use your own classifications instead of those used elsewhere in the system.
Elements in titles
The main elements that you add to element titles are images as img elements, and distinct passages with span elements.
The format for images in the title field is as follows:
<img class="" src="" style=""/>
You must add that slash at the end. When you return to the Settings menu, the system may remove it. If this happens, you just need to add it back. As such, it is easier to just use variables to add images. Of these attributes, only src must have a value. However, you may also add classes or an inline style to that image as well. Although, you can still also use a style sheet to define its style. In addition to these identifiers, you may also include the standard attributes in DoX CMS such as element classes and tags.
The format for span elements here is completely standard. Add the opening and closing tags for them, and include the attributes that you need inside the brackets for the opening tag. You can use them to designate the parts which you want to only show in specific contexts. You control their visibility with a style sheet. In practice, the results look something like this:
<span class="" ></span>
This way, you can use a different numbering format for different types of elements, for example. Even if the numbering for tables and figures were to span the whole document, for example, you could make the numbering for end notes be tied to sections. You do this with span elements around the parts that specify the numbering format, such as the variables inside the title format. I will provide an example of this in relation to identifiers tied to each such part further below.
Identifiers in titles
With the help of identifiers, you can target different parts of elements’ title format in different situations with rules in a style sheet. I recommend that you use custom classes for this. If you do, you can designate them in the style sheet in the way that I show below. In this case, I separate the title formats for figures, tables, and end notes for main sections. A simplifying assumption that I make here is that you will not use links to target other types of elements such as list items. You can adjust the solution to allow for it if you must also link to them, though.
For this demonstration, this is the title format that I set in the Settings menu:
<span class="show_series">{{Series}} </span><span class="fig_num">{{TargetFirstLevelTopicNumber}}.{{FirstLevelNumber}</span><span class="table_num">{{Number}}</span><span class="endnote_num">{{FirstLevelNumber}}</span>
You would control the layout of that title format with this addition to your style sheet:
.dita-fig > .dita-title > .anchor-title > span:not(.show_series):not(.fig_num),
.dita-table > .dita-title > .anchor-title > span:not(.show_series):not(.table_num),
.anchor-title:has(+ .dita-fn) > span:not(.endnote_num) {
display: none;
}
This involves three selectors on different lines, where each is connected to the same rule. Each of these selectors targets the parts of the title format presented above that are intended for other elements’ use to hide them. Even if you use different identifiers, the presented model still works: In the case of figures and full tables, you can target rules at titles directly inside their frames, and then to specific parts inside those. Elsewhere, you can target the rules at parts with the .anchor-title identifier when those parts are immediately followed by the kind of element in question, and then at the specific parts inside those title fields. This option also works with figures and tables when you leave their title fields empty.
This implementation only affects the titles of elements. You must also add a means to identify the links which target these elements to make the format between them consistent. You can thus use this formulation by itself if you never link to those elements.
Using variables
You can also use variables other than this field’s own system variables in the titles of elements. Additionally, you can add more structure inside the default variables that replace the {{series}} variable in publications, such as {{default-series}}. Do note that you cannot use the system variables for only this field, such as {{series}}, inside other variables, even if you were to then use those variables as part of element titles. The system does not retrieve values for these system variables if you add them like this.
Variables are, for example, an easier way to add images to these titles. When you do this, you need not add the images in the title format itself. As such, you need not worry about the issue with the disappearing slash symbol that I mentioned above. If you want to use identifiers to control the visibility of that part, you can apply an element class on the image or even the span element for the variable itself. Because the used values for element classes are not compared to a list, you can also write new such values directly in the text editor’s Source view instead of adding each into the system separately.
Likely the most important way to use variables here is to add different values for the {{default-series}} variable inside it. DoX CMS uses this variable to replace the {{series}} variable in the title format whenever an internal link targets some element other than a topic, a section, a full table, or a figure. If you need such links to different types of elements, it can be hard to find a suitable word for all of them to use in this variable. To then successfully translate one would perhaps prove even harder.
You can add different values inside the {{default-series}} variable for each position where it gets used. By default, this alternative still only uses one counter instead of each of its applications having its own counter. As such, I recommend that you instead use no counters with these values. You can hide all counters for them with the methods that I showed above. In this case, I also recommend that you hide all related title fields that the system adds to the elements targeted with links. The result would be that such links only name the type of element that they target, such as when you write ‘See this list to make sure which tools you will need.’ The part in italics inside this quote would correspond to the generated text for a link which targets a list. Make sure that such wording can be translated before you commit to it, because the values of a variable cannot be grammatically adjusted for different use cases. If a more detailed reference to a named list is important because, for example, the manual will also be printed, you can target a surrounding section element or topic with the link instead of the list itself.
In practice, all this involves the same method that I already presented above, but the selectors in the style sheet should target one level deeper due to the boundaries of the variable itself. You also cannot use custom classes as identifiers inside a variable. As I mentioned above, element classes provide the closest parallel as a replacement. I discuss such uses for them in more detail here. When you target such elements, formatting links to them requires the solutions that I will provide below.
Links with distinct formats
As I have alluded to above, changes to titles themselves do not entail that links to those elements inherit the same format. All links use the same value in the Settings menu as the titles themselves. You thus control the visibility of its parts in similar ways. The main issue with this involves finding suitable identifiers to make the necessary distinctions because the positions available to links are not static in the same way as those of the titles for various types of elements.
Identify the targets
To make the links match the situationally adjusted titles requires them to have identifiers that correspond to their targets. Links themselves have their href values as an option that you can control like this. It specifies their targets. You can thus format the ID values of the targets in a way which allows you to coordinate the layout for links with their targets. Alternatively, you can separately apply an element class to each link to specify the type of its target. I have seen this done to support substitute counters, but it adds an extra step to each time that you add a new link.
In effect, you would thus be adding a standardized identifier at the start or end of the ID value of each element with one to specify which type of element it is. For example, a table’s ID value could be along the lines of ‘table_01’ or ‘table_techsheet’. I recommend the use of some kind of separator such as an an underscore for this identifier to avoid ID values which are also compatible the wrong rule. This could happen with ‘li’ and ‘list’, for example. Do note how internal references always start with the ID value of a topic, and that in the case of repeated ID values and multilanguage publications, the system may add further identifiers at the ends of ID values to make sure that each remains unique.
As I discuss here, you can attach styles to the values of different attributes or to parts of those values. When it is used in this way, the part that defines the type of the target as part of its ID value, which the href value of the link inherits, provides a foundation for a style which controls the parts of the title format that a link shows in a way which account for the type of its target. By default, a target’s title and the link to that element correspond to each other. This need not always remain the case, however. You may also only show some parts of the base format in one and hide them in the other if necessary.
This example shows the contents that I used for the {{default-series}} variable. It only accounts for lists and paragraphs. I use a separate variable for each value to make managing them easier.
<ph doxelementclass="default-series"><ph doxelementclass="DS_list">{{list}}</ph><ph doxelementclass="DS_p">{{paragraph}}</ph></ph>
The corresponding addition to a style sheet, based on which the system only shows the correct part for each link, is below. The condition that I added is that there is a part anywhere in the link’s target value which starts with an underscore and tells you the type of the targeted element. This is not without risk because ID values could contain that string in other situations as well. In return, this option avoids problems related to the language identifiers in multilanguage publications, for example. The remaining parts of these selectors just check which parts inside the links have element classes, and whether not to hide the parts that have specific element classes. I recommend that you use situationally appropriate versions of such values in these situations rather than just my examples.
.doxInnerReference[href*="_list"] [doxelementclass]:not([doxelementclass="default-series"]):not([doxelementclass="DS_list"]),
.doxInnerReference[href*="_p"] [doxelementclass]:not([doxelementclass="default-series"]):not([doxelementclass="DS_p"]) {
display: none !important;
}
Link formats
In the example that I provided above, I simply hid any extra parts of the title format inside links to make these links match the titles of their target elements. In this case, both the title and the link apply the same layout rules. However, the links need not match the titles. Their layout can differ from that of their targets either by showing more, or by showing less than the related titles. Additionally, you may of course add other rules that distinguish links to different targets from each other, such as text colors.
Additions to links
At times, links need to show more than just the actual titles. For example, when I asked for feedback on a planned update to DoX CMS‘s user manual, one comment was that the use of ‘menu’ in the titles of related section elements was unnecessary. The reason for its inclusion, though, is how I need to specify this to distinguish between references to instructions to delete topics and the Delete Topics menu, for example. Since this clarification is only needed for links, I thus elected to only add it to links through the style sheet.
In this case, I will not employ situationally displayed parts written in the title format. You can still choose to do so. I also base this solution on a new distinction besides those I already discussed: it will not affect all section elements. As it is still based on the target’s ID value, though, I can freely add whichever distinctions are needed.
Thus, the example that I provide below adds the word ‘menu’ at the end of links in English publications when their target includes the phrase ‘_menu’. Similar rules would need to be added separately for each language. My formulation anticipates this by separating the rules for layout and the rules for content. This formulation does not retain continuous underlining below links because I do not use underlining with links. You can keep it by removing the left padding and by including an empty space at the beginning of each content value, though.
[lang="en"] .doxInnerReference[href*="_menu"]::after {content: "menu";}
.doxInnerReference::after {
display: inline;
padding-left: 1ch;
}
Simplified Links
Likewise, you sometimes want links not to include all the content in related titles. An example of this would be titles with added images which you do not want to repeat inside links. An image like this can, for example, direct the reader’s attention at where (some) tables start when this matters and when other means to direct their attention do not work as well for such situations for whichever reason. If that image is standardized, you should add it as a pseudo-element through the style sheet. Sometimes, you need that pseudo-element for other things, though. A situational image is likely also easiest to manage with the method that I presented above where you use variables inside the title format for elements.
I will not separately illustrate the same method based on hiding parts situationally as I did above. Do still note that in such situations, it is still better to use identifiers rather than selectors that just designate all images inside links, for example. After all, you may also use links anchored in images for links to social media, for example. Thus, even if you were not to need them for now, it is better not to fill the system with traps in advance, when you would need to then disarm them if you ever needed new solutions like that.
Distinct links
All distinctions between links based on their targets can also be applied to how you style them in general. You can thus make links to different types of elements have different text colors, for example. While this may prove distracting in some cases, it does increase readers’ ability to quickly locate the types of links that they need. This is especially true if you use links often and they cluster near each other, and if the readers are likely to browse content instead of reading it in sequence.
Keep in mind how you can also attach such distinctions to the other attributes of link elements. In this case, these distinctions do not target differences between targeted elements. However, you can distinguish between internal and external links, for example, based on the values of the scope attribute.
Summary
CSS is not only a means to define the layouts of finalized content. In particular, you may use the option to hide alongside complex selectors to expand the functionality of the system. Similar instructions for CSS-based tricks with animations, transforming SVG images, and so on can be found all over the web.
In DoX CMS, such extensions to the system’s functionality include styles for previews that show more information about contents and highlight it in different ways, as well as adapting the titles of different elements and links to them situationally. You can also, for example, add variables with values that change based on where they are used like I described here. I also know of other ways to produce the same effect. Ask for more information if you are interested.
To help with previews, you can, for example, show the values of relevant attributed for elements other than images or highlight elements that have attributes such as tags from specific categories. Your implementation for this must still account for the limit on the number of pseudo-elements if you need them for other parts of your layout. More complex combinations of tags also complicate how to present them by quite a bit because the selectors in your style sheets must account for each required combination of categories separately.
Other ways to support previews include adding highlights for links without targets and other empty elements to the style for previews, hiding covers and tables of contents, and adding information related to the preview in page headers and footers. This way, you can record which pre-production version a given publication is, for example.
You may also adapt element titles situationally, even though all elements use the title format defined by the same field otherwise. All that this requires is that you write HTML tags in this field and then add identifiers to those elements alongside rules in style sheets for them in different situations. This way, you can use automatically filled text for links without any numbering for elements that would otherwise use shared counters. To have links match these values, you need identifiers as a foundation for styling them. If you do not want to use element classes to do this, you can instead use standardized sections inside the ID values of targeted elements as these will systematically be inherited by related links’ href values.
Besides matching links to the custom titles for different elements, you can instead adapt the layouts of links independently. Those layouts need not be the same as the titles of targeted elements. You may add more content to some links, remove parts used in titles such as visual aids from them, or style links targeted at different things differently.