You can use any identifiers for selectors in style sheets. Usually, this involves ID values or classes such as .dita-title.However, you can also use other attributes similarly. Because tags and element classes in DoX CMS are the designated elements’ attributes as well, instructions related to them provide some examples. I have already discussed ways for style sheets to designate tags and element classes. I will thus not include that subject here. For example, more information on styles that target specific tags is available here. Instead, I will discuss implementations that involve styles linked to the other attributes that different elements may have.
Attributes consist of additional details besides an element’s type. The element tag that starts a new element contains all these details. Both ID values and classes are themselves attributes. References to them are just so common that they involve simpler notation. Each attribute has a name and a value. If there are more than one value in relation to one name, they are combined into one value where each is separated from the rest with an empty space. For more information on HTML attributes, see here. For more information on DITA attributes, see here.
I will discuss examples of attributes that you can use for styles and related implementations below. My instructions involve edits to CSS style sheets. If you use these instructions, remember to provide internal documentation on them for future users.
The format for attributes in CSS
All references to attributes in selectors involve the same format. I will discuss the details of this format below. The ‘attribute’ part designates the attribute’s name. The ‘value’ part designates the value for that attribute. This default version only works when the total value matches what you write exactly. I will also dicuss ways to designate attributes based on partial matches in terms of their values.
[attribute="value"]If you add this identifier immediately after a different identifier such as an element type with no space between, it acts as a condition for elements of that type. For example, ‘span[doxelementclass= redtext=””]’ only designates phrase elements (ph) with the element class named ‘redText’. The system processes phrase elements as span elements for purposes of HTML publications and in the bases for PDF publications.
Selectors for partial attribute values
If references to attributes were limited to exact matches, they would have rather limited utility. Fortunately, this is not the case. The formats shown below let you refer to different parts of an attribute’s total value. With the exception of the first example, each format involves some other symbol before the equals sign (=) in a selector that is otherwise identical to the one shown above. In this case, the ‘value’ part corresponds to a part of the total value of the attribute instead of that total value. More information on such partial selectors is available here. These methods also work with the default attributes such as element classes.
- [attribute]: Designate the elements with that attribute regardless of its value.
- [attribute~= value=””]: Designate the elements where one associated value for this attribute matches this value.
- [attribute|= value=””]: Designate the elements with at least one associated value for this attribute that starts with this value.
- [attribute^= value=””]: Designate the elements with a total value for this attribute that starts with this value.
- [attribute$= value=””]: Designate the elements with a total value for this attribute that ends in this value.
- [attribute*= value=””]: Designate the elements with a total value for this attribute that includes this value.
Note element sub-types (type)
One of the most common ways to add styles to other attributes involves differentiating the different sub-types of note elements such as warnings and tips from each other. This lets you give the appropriate icons and color schemes based on ISO 3864 to the different note elements. You must only use the text editor to set the correct Type value for each in its DITA Attributes menu.
When less common sub-types of notes are involved or you apply a specific or divergent format on the contents of the common sub-types, you can use different rules for these purposes. For example, fastpaths generally include links. You can provide such links a style that is unique to them with details such as a larger font size and a different color. You can also prevent the change in color when a user uses the links.
Example implementations
What I present below is a means to add the appriate icons, titles, and colored frames to warnings. I apply a divide where the rules that apply to all note elements in these respects have their own section. This avoids repetition for each sub-type. Only the parts that differ between sub-types must then be specified like I did for warnings below.
In practice, you add the titles with a style sheet and the icons are backgrounds for different sub-types. You use a padding to make sure that content does not sit on the icon. I do not recommend that you copy this implementation directly because it does not account for all relevant details. For example, the image that I used is just a demonstration and you should generally use the language identifiers discussed below to translate the values for note titles.
[data-ditaatribute-type="warning"]::before {
content: 'warning';
}
[data-ditaatribute-type="warning"] {
background-image: url("/Content/images/warning-icon.png");
border-color: #F8A81B !important;
}
.dita-note::before {
font-weight: bold;
font-size: 12pt;
text-transform: uppercase;
}
.dita-note {
border: 2px solid #000000;
background-repeat: no-repeat;
background-position: 0 10px;
min-height: 62px;
padding-left: 60px;
padding-top: 10px
page-break-inside: avoid;
}Similarly, the mockup that I present below presupposes that fastpath elements only consist of separated links that redirect you to different parts of the document. This is why the links inside them are emphasized with a greater font size and a different text color. Just to be sure, I also removed the underlining which links can have by default. This is not viable when the same paragraphs also have other content.
[data-ditaatribute-type="fastpath"] a {
font-size: 2em;
color: #03fc9d !important;
text-decoration: none !important;
}The sub-types for note elements are only one example of a detail that you control through the DITA Attributes menu and that you can use to specify different styles for different values. In this case, you only need to select the correct value from a list when you write to have the published versions of notes have the correct styles. This lets you bypass a need to add recurring parts such as their titles to them in the text editor. You must only occasionally make updates to such details in the style sheet. This mainly happens when you add new languages to the system.
Language (lang)
You can use language identifiers to provide differences between languages. The most common detail like this are contents added with the style sheet such as the titles for note elements discussed above. You must translate such details to each language. You do this with different values for different language identifiers in the style sheet.
You can also use language identifiers to change other details of publications’ styles in different languages. You can specify different fonts for different alphabets. You can even change the reading direction. For example, if you control the widths of table cells with element classes, you can change these widths for different languages if the cells do not otherwise have enough space in languages that require it. You can also change the images added with a style sheet in different languages if different languages use different icons or you use different branding in different regions.
Example implementations
The examples that I include below are translating the titles for note elements and changing the reading direction to from right to left. The general principle is that the language identifier is an attribute of the content’s root element. As such, it is enough for you to just add the language identifier at the start of a selector and separating it from the rest with an empty space. This language identifier in DoX CMS is the same as the identifier used for that language in other parts of the system. You can also use partial values for language identifiers, such as identifiers that start with ‘en’ to designate both ‘en-US’ and ‘en-GB’ among others.
Unfortunately, you must apply translations for parts that you add through the style sheet as additions to the style sheet. Style sheets are handled after all other contents are already processed. As such, any content that you add with it such as variables would not be available to retrieve their proper values. You can use variables to have the content be translated to a new language before you copy these values to the style sheet. I recommend that you add these values at the top of the style sheet or in their own style sheet to make them easier to control.
[lang="en"] [data-ditaatribute-type="warning"]::before {content: 'warning';}
[lang="fi"] [data-ditaatribute-type="warning"]::before {content: 'varoitus';}
[lang="de"] [data-ditaatribute-type="warning"]::before {content: 'warnung';}There is a command to change the reading direction of content and it affects the layout of all content. It is easiest to use this command on the root element for content. However, if some parts of your documents include rules that specify directions such as when you float elements to one side of the text around it, you may also have to redefine these values. There is a chance that you must also do this for the icons for note elements if you use the kind of implementation illustrated above. They will then require you to change the side on which you add the background and the side on which you add the padding related to it. You only need to specify these details again. In principle, you can use a separate attribute called ‘[dir= rtl=””]’ when you need such layouts for more than one language. For more information on reversed layouts, see here.
[lang="ar"] {direction: rtl;}
[lang="ar"] .dita-note {
background-position: right 0px top 10px;
padding-right: 60px;
page-break-inside: avoid;
}Rules for different languages are important. Translations to new languages require more than just the translated content. I believe that you should use specific fonts that match your brand for different alphabets instead of default options, unless you also use default fonts regardless.
Link targets (href and src)
Attachments and links in structured documents have attributes that determine their targets. Thus, you can use selectors based on these values or parts thereof in your style sheets. For example, you can systematically name your files or elements, as well as specifically target file types, or web pages with styling rules. This lets you add frames to pictures or define their dimensions based on how they are used without the need to add further identifiers such as element classes in the text editor. You can also differentiate between internal references to different types of elements and show the targets of external links when the pointer is above those links. Image elements (img) use the Src attribute to find their content while link elements (xref) use the Href attribute for targeting.
Any changes to publications’ styles that you implement like this also require systematic formatting in terms of file names, element names, and links. These rules do not operate correctly unless you do this. The benefit of such implementations is that you only need to account them as part of tasks that are already necessary. No further steps are involved.
Example implementations
I will present several ways in which you can use styles to differentiate between different types of links below. I will also present a method that makes SVG files grow in size while users click on them.
When you differentiate between types of links, users will find them more easily at a glance and it tells them the nature of the links’ targets even when it does not show in the text itself. The method that I present below differentiates between internal links within a document and external links. As is the case with all the examples that I provide, this method is intended for DoX CMS. I base this distionction on whetjer the value for the link starts with the # sign because this is the format for all internal links. This designates the targets’ ID values. As far as I know, no external link has the same format. This order makes the latter rule apply when its conditions are fulfilled. The condition ‘.topicWrapper’ makes sure that these rules only apply to the content proper and not to the table of contents, for example.
.topicWrapper a {
color: blue;
}
.topicWrapper a[href^="#"] {
color: green;
}You can differentiate between internal links to different types of elements when the ID values for these elements are formulated to express the elements’ types. This example is based on the assumption that each element with an ID value will have that value end in the type of the element such as ‘revision_table’ for a table that shows a document’s versions. You should be careful, though, as DoX CMS will add values such as ‘_1’ at the ends of such values when you publish content if the document has more than one element with the same value. If you use more than one method to change the details of links, you should also make sure that the correct rules apply for each.
a[href$="_table"] {
color: firebrick;
}
a[href$="_fig"] {
color: goldenrod;
}
a[href$="_section"] {
color: mediumseagreen;
}You can also include identifiers such as ‘[href^= mailto=””]’ in selectors to designate links for email addresses. You can then add more complex rules to such elements such as showing external links when you hover the pointer above the link. The implementation for this that I show below uses the Scope attribute of link elements (xref): links specified to be external links show the value of their Href attribute in the specified format when the pointer is above a given link element. You can also add an animation to this display method. For more information on CSS animations, see here.
a[data-ditaatribute-scope="external"]:hover::after {
content: "🡒 " attr(href);
display: inline-block;
color: lightgrey;
padding-left: 5px;
}My example on the Src attribute for images involves the file extension. I use a partial value where the file extension must be anywhere in the reference because internal previews in DoX CMS add language information at the end of the Src value. This does not happen with the final publications.
This addition to style sheets presumes that icons for your UI use SVG files and that the main body of text does not otherwise use these files You can account for their other use cases by adding conditions that prevent these rules from taking effect. In the example that I provide below, this is done with the first paragraph inside a figure element (fig) and images inside tables. These conditions assume that the images inside a figure element are its first content. These rules make the image larger and move it in a temporary space to the left of the paragraph. These rules also assume that you added the image to content through a variable. In this case, the red text ‘see left’ shows in the initial position when the image is selected.
img[src*=".svg"]:not(.dita-fig > p:first-child img):not(td img):active {
max-width: none !important;
height: 20mm !important;
width: auto;
float: left;
border-right: 3px solid black;
padding: 3px 5px;
margin-right: 8px;
background: whitesmoke;
}
span:has(img[src*=".svg"]:not(.dita-fig > p:first-child img):not(td img):active)::before {
content: "see left";
display: inline;
color: red;
}Styling (style)
This is a minor trick that can prove helpful if you do not want to use an element clasds to control image sizes or if you would prefer to control images’ styles with keywords instead of separate element classes for each independently controlled detail. The Height attribute and the Width attribute that you write in the text editor need not have the correct syntax. You can write anything there, and you can then add rules to these values to control these elements’ styles.
Example implementation
This implementation does not differentiaste between the Height attribute and the Width attribute since both are subsumed by the Style attribute when you publish the content. The actual value consists of keywords that you can comvine to define the situationally appropriate style.
- inline: The image’s height matches the font size of the text around it.
- framed: The image has thin black borders.
- hoverHighlight: When you move the pointer above the image, it gets red borders and a yellow background that transparent images show.
img[style*="inline"] {
height: 1em;
}
img[style*="framed"] {
border: 1px solid black;
}
img[style*="hoverHighlight"]:hover {
border: 2px solid red;
background: gold;
}Translations (translate)
All elements have the Translate attribute. You use it to tell translators which elements they must translate or leave untranslated. If you add styles to it, you can highlight these sections in the copy of the publication in the initial language when you send one to the translators. This makes it easier for them to recognize which sections involve additional rules in terms of the translations. For example, you can use a phrase element (ph) with the value ‘translate: yes’ for commented sections in code samples. If these sections are highlighted with a designated color in the version published for translators’ use, it becomes easier for the translators to notice the sections. The code block element (pre) itself is not translated by default. I recommend that you use a separate style for such publications to be used by translators to only show them these highlights.
Example implementation
This implementation simply adds different colors to the sections that you designate with the use of the Translate attribute. Remember to tell the translators what the different colors mean. In this case, the sections that they must translate despite default assumptions are lime green and the sections not to translate are dark pink.
[translate="yes"] {
color: lime;
}
[translate="no"] {
color: deeppink;
}Summary
Exceptions to styles are mostly tied to element classes in DoX CMS. Doing so is not necessary, though, when other attributes with uniformly applied values are available. In this case, you need not fill the list of available element classes with options for each eventuality and you do not have to remember to apply those element classes to the relevant elements, either.
You can use the style sheet to designate elements that have a given attribute, that have specific values for those attributes, or that have values that contain the specified parts for those attributes.
Some changes to styles based on such attributes are used commonly. For example, the icons and titles for different sub-types of note elements are generally added like this. Similarly, any added text such as these titles for note elements which you add through a style sheet must also be translated in the style sheet in relation to the different values for the language attribute.
In addition to such common implementations, there are varyingly creative other applications available for linking the values for different attributes to content layout. Some do require you to account for their requirements when you edit content. For example, you can specify the colors for internal links to match their targets when the targets’ ID values include standardized parts which the Href attribute’s values for different links will contain to let you style these links accordingly.
All the implementations shown here are simply examples of the available rules and the available values. You should think of the best ways to adapt these ideas for your own use yourself.