Version 8.7 of DoX CMS added the identifiers for the revisions of used publication templates to publications. In a previous piece, I discussed the changes to filtering in version 8.7. This time, I will show how to use this new identifier to control publications’ content and style.
At a general level, this is a matter of adding options for publication-specific adjustments. If each of your publications contains unique content, it would require a new tag associated with each publication at minimum to control visibility for that content without this option. Publishing variables only allow for short injections of publication-specific text. As for the new feature, it supports options such as changing the image in a specified position depending on the publication.
First, I will explain the principle behind this feature and its intended method of application. Afterwards, I will introduce several ways to apply it.
The operating principle of publication-specific styles
Originally, this feature was a quick solution to a specific customer’s need: Each of their publications has a diagram which is unique to a given delivery. Each such delivery requires a unique image in the specified position. The publications in question otherwise use combinations of reused content.
Since this addition was simply an identifier, using it depends on style sheets. This identifier is the unique value listed for each revision of any publication template in the ID column of the Publications menu. Since each publication template has a unique value, you can add rules that only apply to them in style sheets.
The name of the attribute used for this is ‘data-publication-id’. This attribute is applied to the html root element in publication formats based on HTML. These formats are HTML, WebHelp, and PDF. For now, you thus cannot reference it when the publishing format is set to DITA.
How to use it
Since this attribute is applied to the root element, you can just add a reference to it at the start of a selector and separate it from the rest with an empty space. This notation expresses the rest of the selector matching anywhere inside a root element with that value. Because the root element has all the content of the publication inside it, any matching part of a publication with that value will do.
I recommend that you have their own style sheet for such additions as you will need to edit that sheet every time that you add a new revision of a publication template. In principle, you may even have a new style sheet for each publication and only include the changes related to all of its revisions there. If these values remain the same for different revisions of that publication, you can just add the values for new revisions in the selectors. Such separated style sheets must of course be included in the styles which require them.
It is possible that our further development will include another identifier which ties later revisions to the first revision of the same publication as well. This identifier would be associated with a specific publication rather than a specific revision of one. However, this change would require us to specify how such values relate to copied publications and possibly to add a new column which would show these values for all revisions.
If you will only have such changes occur in positions specified in advance, I recommend that you use the familiar methods of adding either element classes or ID values there. If some such part must be included in several positions, you can also use a variable with such an element class, or content references.
Beyond you applying the general principle that I described above, there is no universal template for how to use this identifier. The examples that I present below in part illustrate the available formatting, though.
Examples of publication-specific adjustments to style
Here are some thoughts on ways to use these identifiers for the revisions of publication templates to adjust their styles. Besides contextual changes to images or text, you can also add a style which involves multiple choice selection between specified options for each revision of a publication.
Change images
You cannot use publishing variables to adjust images between publications. As such, this is the best alternative for having a different image in use for each publication.
Unique product images
Structured authoring is particularly suited for modular products. However, it is less than ideal for presenting unique configurations of such components when the same pieces can occur multiple times or be placed in different ways.
Images added through a style sheet like this are one solution to this challenge. In this way, you can show a delivery-specific assembly diagram in an added image.
Of course, the parts for such images must have been marked in unambiguous ways. If several positions must include the image that you add like this, I recommend that you use a dedicated variable which has a dedicated element class added to it in the variables editor.
If the image must only be used in a single position in each publication, for example, you can apply an element class to mark that spot or add an ID value to it.
In my example below, the image has been added inside the first p element inside a fig element with the provided ID value. This example assumes that each publication will include this image only in this one position. The identifier for that revision of the publication template is 145. A reference to just the element’s ID value would technically be enough with no need to specify the type of element. However, mentioning the type of the element lets those who read the style sheet understand the context for the reference. Instead of a direct reference to the specific ID value, I use a looser selector because ID values can be adjusted during publishing. For example, multilanguage publications include the same position multiple times as part of one publication.
[data-publication-id="145"] .dita-fig[id^="DeliveryFullAssembly"] p:nth-of-type(1)::before {
content: url("Content/Images/Assemblies/26386720.png");
}
Remember that you can provide all these publication-specific images more style details such as size specifications in one place instead of repeating those rules for each added image.
Unique covers
Cover images are no different from other images added like this. Usually, changing cover images are best controlled with distinct styles for different product families or tags related to different products. However, if such images are unique to each delivery, it is better to add them like this.
In my example below, the image was added as a background image for the cover. This option does not generally suffice by itself. It requires other rules to support it. It is not the only option for this, either. You could add images inside other elements in the way shown above, for example.
[data-publication-id="145"] .coverPageWrapper {
background: url("Content/Images/Covers/26386720.png") no-repeat;
background-size: cover;
}
Changing text
You normally use publishing variables to control publication-specific pieces of text. However, the same results can also be achieved with the help of this new feature, and there are situations where it works better. Some reasons to use it would include the need for longer pieces of text or a need not to cram the list of publishing variables. I will discuss some suggestions related to this below.
Local contact information
To add contact information with publishing variables would likely take several variables because of the line breaks between pieces of information. This would keep adding lines to the list of publishing variables. When it comes to your company’s main contact information, you can use normal variables for it. For the contact information of specific liaisons where only around a dozen exist, you can provide delivery-specific information with normal variables and tag-based conditioning.
If such contact information varies enough to be nearly unique for each delivery, though, because you must provide local support liaisons globally, for example, this would likely prove to be the best method.
You can separate such information into distinct chunks or add them in one go, especially if you need not also add details such as that this line shows a phone number. To use separate chunks involves more complicated in terms of the required selectors since each chunk requires its own selector and an unambiguously identified position for one. You can, however, just add an identifier for this to an element in which the parts for all the information are embedded, and then distinguish the types of contact information through counters for their position inside that element, for example.
In my example below, all information was added at once. This example shows how you can add line breaks when you write ‘\A’. The white-space rule’s value is requires for these added line breaks to work.
[data-publication-id="145"] [doxelementclass="LocalDealerDetails"]::before {
content: "Jane Doe \A Distribution representative, TX \A +1 356 2691-728 \A jane.doe@na.distr.machinex.com";
white-space: pre;
}
Replacements for publishing variables
Should you need a full table of publication-specific values, you can still add them as publishing variables. In this case, you should likely add an organizational aid to them in the form of alphabetical prefixes, though. This makes it hard to slip in new variables, and the list could prove long for the Edit Publication menu.
Instead of publishing variables, you can also use parts which you control through a style sheet like this, should the these details become a problem for you.
This solution involves no details unique to it, which is why I will not illustrate it separately. It is just a matter of larger wholes with parts that correspond to the previous example but generally with less need for added line breaks. This solution in particular benefits from the use of counters as part of selectors and other methods which allow you to specify the positions in ways where only the higher level elements require unique identifiers. Tables to be filled in this way benefit from that greatly.
Parts outside content in online publications
WebHelp publications in particular allow you to show information such as product details or the version of the manual outside the content proper. The content in these positions is not normally able to be made publication-specific with alternatives like publishing variables. Since the new identifier is added to the root element for the whole publication rather than just one for its contents, you can also add these rules to the parts outside content proper.
For more information on how to adjust the style of WebHelp publications, see here.
In my example below, I add a publication-specific product name and the revision number for its manual in the header of a WebHelp publication. You cannot use system variables that would automatically update these values for those positions for this because values for variables get fetched before style sheets get applied when you publish content. All details other than the exact value that I used were copied from the earlier piece that I linked above. I also added the new identifier used for this in the first selector.
[data-publication-id="145"] .documentHeaderLogoWrapper::before {
content: "Let's Get Kraken ERP Manual v2.41";
padding-left: 80%;
white-space: nowrap;
color: white;
font-size: 1.5em;
}
.documentHeaderLogoWrapper {
display: flex;
flex-grow: 1;
align-self: flex-end;
}
.documentHeaderTitle {
display: none !important;
}
Special styles
Besides changing contents, you can use this feature to adjust styles themselves in publication-specific ways. That option is likely less needed but below, I will discuss some situations where implementing it like this could prove useful. For example, if each publication includes a set of choices from already provided alternatives, you can select from those alternatives like this. Additionally, the fact that previews in the Editor menu never include this identifier can be used to enrich those previews in ways which better serve their uses.
Multiple selection styles
Let us imagine that your products’ manuals have different styles for each delivery. Perhaps you use the same baseline style for all deliveries but the manuals that you write are for completely unrelated products from different customers, and each of them requires adapting the style. Especially if these are all one-off projects, you would have little reason to write separate styles for each such customer.
In a situation like this, for example, one option would be to have alternative rules in your style sheet already and then adding selectors that match specific publications to them. This would in effect make defining the style for a given publication into a multiple choice selection list. Some examples of such choices would be list styles, type of emphasized text, and the color scheme.
In my example below, I show two alternatives for the list style of unordered lists and publication-specific selectors associated with each. In principle, it would be ideal to use the :is() pseudo-selector in such situations to only need to add the publication-specific identifiers inside it. It is not guaranteed that available compilers support this option, though. As such, I recommend that you copy the recurring parts and just change the publication-specific value, instead. Use a comma to separate the selectors for different publications and preferably, also list them on different lines as seen below.
[data-publication-id="145"] ul:not(.toccontent),
[data-publication-id="143"] ul:not(.toccontent) {
list-style-type: disc;
}
[data-publication-id="144"] ul:not(.toccontent),
[data-publication-id="142"] ul:not(.toccontent) {
list-style-type: circle;
}
Topic previews
Sometimes, situational identifiers can have the unexpected benefit of you being able to specify details for when those identifiers are not in use.
The identifiers for the used revisions of publication templates are only added to publications based on publication templates. They are thus inapplicable for publications from the Editor menu or related previews. As such, you can use the absence of this attribute to target rules at just these publications done in the Editor menu, or even at just their previews.
This allows you to do things such as check how many topics are currently selected. This would be a less than direct means to access information which the system does not otherwise share at this time. Should there be a clear need for one, we would also add such a counter to help with controlling views, of course. In the meantime, this solution is yet another means to use style sheets to add new functionality to the system, just like the methods that I introduced here.
In my example below, only previews for publications made in the Editor menu will have a counters at the start to show the number of topics included in them whenever two or more are present. I also use the identifier data-document-type=”dox-preview” as part of these selectors because otherwise, this rule would also affect the actual publications made in this way. The counter is also positioned at the end of the publication and then moved to the start of the publication to first allow it to count how many topics there are in the publication. If I had directly positioned it at the start, its value would always remain at zero.
html[data-document-type="dox-preview"]:not([data-publication-id]) body:has(.topicWrapper + .topicWrapper)::after {
content: "Topics:" counter(topics);
position: absolute;
top: 0;
right: 0;
}
html {
counter-reset: topics;
}
.topicWrapper {
counter-increment: topics;
}
Summary
Version 8.7 of DoX CMS added a new attribute, data-publication-id, which you can use to add rules related to specific revisions of publication templates to style sheets. If you add rules tied to the values of this identifier to your style sheets, you can have those rules only apply to publications made with the specified revisions of publication templates. This value need simply be added at the start of a given selector and be separated from the rest of it with an empty space. You should tie the rest to unambiguous identifiers such as element classes or ID values, if you want to restrict changing content, for example, only to specific positions.
The available applications for this attribute include, for example, publication-specific images and pieces of text. At minimum, such additions would otherwise require each different publication to have a related tag to mark the associated alternatives in these positions. When it comes to text, you could do the same with publishing variables but this could grow their number to an unmanageable amount.
You can also apply changes to styles proper like this. For example, you can have style sheets with multiple choice selection lists that allow new revisions of publication templates to be added in a way where you specify which of the listed options it actually includes. This means that each variant would not require its own style.
The absence of this attribute can also define which rules apply. The attribute is only included in publications compiled from revisions for publication templates. Sets of topics published in the Editor menu lack this attribute, which is what allows you to, for example, add a counter at the start of their previews to show how many topics you have selected at the time.