I remember when a Russian lecturer for a university course on international communication joked that ‘Everything in Finland works but nothing can be done about anything, whereas in Russia, nothing works but you can make anything happen.’ This kind of tug-of-war between readiness and flexibility in execution also applies elsewhere, and bribes are involved only some of the time. Instead, implementatons based on flexible features require more planning and assembly. The instructions in this piece should prove helpful in this respect when it comes to applying the features in DoX CMS like this.
Many of the features of DoX CMS involve a degree of such applicability. Some such features are more flexible than others. When you use tags, you must always also account for their innate role in filtering the contents of publications. Element classes, on the other hand, are nothing but an unrestricted targeting method, and any associated functionality must be added through style sheets, for example. In the same vein, changes to style sheets let you add styling to any elements that you can target, such as individual elements based on their ID values.
In this piece, I will discuss how to best utilize the freedom that such general features afford when you use DoX CMS, and the restrictions that apply.
Background architecture
You can view the features used to format and manage content as building materials and tools which let users construct their contents. More defined features consists of harder materials and their shapes are predefined. If you try to bend them for new applications, there is always a risk that they will snap to pieces. General features are more like raw materials. You can shape them to your needs but this requires more effort from you.
Functional implementations to answer different needs like this requires planning. The more creative such solutions become, the more attention you must pay to their background architecture. General features are an important part of this process because their wider applicability lets you fill any gaps inside and between systems. I will discuss the involved principles and also present an example implementation that I developed for DoX CMS below.
Construction of functionality
Each such feature corresponds to at least one of two key roles. These roles are targeting and adding functionality. Some features, such as tags, involve both. In such cases, fitting them to serve another function requires you to build around their existing usage.
Targeting
All targeting relies on identifiers. This model is at the heart of structured authoring: the default layouts for all elements are based on their identifiers such as ‘<p>’ for paragraphs. Similarly, other identifiers applied to different types of elements such as their DITA attributes or tags define, how systems related to these kinds of identifiers process such content. For example, DoX CMS filters content based on tags, and these tags are a form of attribute applied to different elements.
A general targeting methods involves no such innately associated functionality. This lets you use it as you see fit in different contexts. Ideally, a system explicitly supports a targeting method like this. Such support ensures that formatting standards will cause no issues and that you can add such identifiers with help from the system instead of writing them in full each time.
A general targeting method like this in DoX CMS consists of element classes. We primarily recommend that you use them to add exceptions to the general layout rules for different types of elements. In such cases, you use a style sheet to specify situational rules in relation to the element classes, such as the details for designated tables’ layouts. Such functionality is based entirely on the use of style sheets after you apply the element classes, though. It is is not innate to element classes.
In principle, you can use other identifiers in the system such as tags in the same way. However, since they already involve a different function, you would have to account for its effects to avoid issues. For example, in the case of tags, you must also select the involved tags for publications to still include the content related to them. One example of such an implementation involves controlling the visibility of mobile-specific content with tags referenced in a style sheet. Further information on this is available here.
Variables do not let you specify targets for functions as such. Instead, they let you position the content inside them in a single-sourced way after you target it with other features. This reduces the workload for applicable complex constructuons. You need not repeat the implementations in each position where they are used.
Functionality
Targeting alone is never enough. You must also build functional differences around targeting methods. You can have have pre-existing functionality be inherited from features such as tags by guiding how they are targeted in new ways. You can also code such functionality with open methods that are compatible with the system. In DoX CMS, this mainly involves CSS style sheets. When you transfer content to be used by other systems after they are published, for example, such functionality can also be derived from those other systems.
Style sheets let you, for example, control the visibility of specific pieces of content situationally, as I have discussed in previous articles. For example, a method to switch which elements show on mobile devices is available here. The same article also references means to reorder content with a flexbox layout. CSS also supports other similar methods. You can also use them to define page groups for DocRaptor. You can then use these page groups for other functions such as a different layout for attachments or rotating the page orientation. Style sheets also let you add new content as pseudo elements or new functions with pseudo classes such as the :hover selector which is based on the position of the cursor. CSS animations are also available. You can find out more about them here. Such tools let you add surprisingly much new functionality with style sheets alone.
Greater freedom in this respect is dependent on preparing content for the use of other systems, though.
System integration
The identifiers that you add to content in DoX CMS remain a part of it when you publish that content in structured formats such as HTML or DITA. This lets the systems where you deploy that content use these identifiers to target parts of content with their own features. Of course, this requires control over such targeting. I will discuss some examples of this below.
The most important functions in terms of integration-based processing of content relate to partitioning content and positioning it. You can partition structured content based on the identifiers that it contains, and you can then position these pieces of content to be displayed in specific ways. You can also add new identifiers to support controlling content like this. You can have the integrated system add them to content written in DoX CMS based on prior identifiers. Such additional identifiers can be contextual and you can actively control when they apply. For example, WebHelp publications in DoX CMS are in part based on such identifiers such as the .open class, which the table of contents has when it shows and lacks when you hide it.
Other ways to affect the functionality of documents based on targeting methods applied to them in advance include, for example,
- enabling users to edit some of the content,
- enabling targeted comments,
- enabling user-controlled highlighting,
- anchoring bookmarks,
- reorganizing content,
- enabling users to add their own transitions between parts of content,
- enabling embedded sharing, and
- controlling access.
Example case: Single-sourced but not uniform within a publication
I have presented various ways to mix the features in DoX CMS in previous pieces. For basic use, the most important combinations involve embedded variables and variables with conditioned content. The latter are a common way to reference product models, for example.
Normally, conditioning is limited to the values shown being based on the tags for the whole publication, though. For example, the values for a variable implemented in this way will be the same across the whole document.
This entails that the usual methods do not suffice to single-source recurring templates within a document when they refer to different things each time, though. For example, the sections that describe the toolbars for different menus cannot use content references (conref) when they refer to those menus by name because this introduces differences in content.
To bypass this, you basically need tags that denote different subjects within a publication. Select each tag from this category for content that the publication will have for a given publication. Also do this when a publication will include all of that content. Also add an element class for designating such sections. Otherwise, publications can have errors because of this solution when its conditions are met by accident. An element class ensures that a writer must have specified that this functionality applies.
You can single-source parts of a document that recur while referencing different things like this:
- Add a tag for each possible value for a template in one tag category.
- Add an element class in the system to target this functionality.
- Add source versions for these sections in separate topics.
- Use the designated element class on the source versions.
- Add phrase (ph) elements inside the source versions for each alternative value in each related position. Unfortunately, variables do not currently function properly inside content references (conref).
- Add the tag that corresponds to its content to each phrase element.
- Add ID values to the source versions and Conref values that correspond to the addresses of the source versions to the target versions inside content to be published.
- Add the tags that correspond to the values for those parts to either topics or section elements that contain the target versions.
- Add the rules below to your styles with the correct values for the element class and the tags.
In this case, you control visibility with the style sheet. The rules that control content visibility are targeted to show the parts that correspond to the tags of the parts in which they are embedded when the inner part is inside an element that has the designated element class. Unfortunately, you cannot express that relation with one general rule in CSS alone. Instead, you must provide a different selector for each involved tag.
Remember to replace the names of the tag categories, the tags, and the element class to match your own. This is also a maximally general formulation. If you add further specifications to the selector to only match your use cases, you reduce the risk that the rules apply accidentally.
[data-doxattribute-featurenames="Feature1"] [doxelementclass~="TopicalValue"] span[data-doxattribute-featurenames]:not([data-doxattribute-featurenames="Feature1"]) {
display: none;
}Limitations
Implementations that rely on applications of general features also have their limitations. I will discuss three considerations that apply below. For these reasons, it is sometimes best to acquiesce to the procedures already defined by the system even if they involve compromises relative to available implementations.
Default functionality
If developing a solution requires you to fiddle with parts of the system which have predefined functions, there is always a risk of this breaking these parts’ normal functioning. This can either limit or complicate the use of the system because that part of it will no longer be available in its original form or you must build a new way to implement the same functionality. When such features are a part of a planned solution, make sure that their use remains compatible with their primary function.
I have seen quite varied such implementations. Perhaps the most cautionary example is the most functional one. Its creators had enough expertise to see their solution to the end. From a technical perspective, it was rather impressive. Unless I have misinterpreted the situation, all that work was unnecessary, though, as a simple solution would have been available from the start.
In this instance, they wanted to frame a combination of contents to act as steps with multiple elements inside them. The writers had opted to use tables for this. As simpletables lacked some of the required options, they used full tables, instead. Since full tables have a numbered title each which counts every full table, they removed the default format for titles and wrote their own in a style sheet. The default title format also applies to figure elements which needed to receive the same treatment as a result. Because the text that the system adds for links to these types of elements uses the values of the original title field, they had to add implement a way to refer to the new values instead. This implementation required them to specify the type for each link’s target with an element class applied to the link. In other words, toppling one basic functionality of the system led to a domino effect where each stage required them to build their own replacement for a default functionality that the previous solution had upset.
As I see it, this whole situation was avoidable if they had used section elements instead of table elements for the frames. Before you build such an implementation, you should thus carefully consider the available options and preferably also consult the system’s provider.
Complexity
The unfortunate reality is that sometimes, even when a suitable implementation is available, putting it together or using it would prove too complicated to be worthwhile. In such cases, it is better to accept that the derived value will not reflect the time and effort that the implementation and maintenance would involve.
Complex implementations are also always a further challenge to new users who must infer the correct conventions. This is especially challenging when default features are being bent. This makes the user manual for the system potentially misleading because it only explains the default functions of these features.
In the situation that I mentioned above, new users were put in an extremely challenging situation because the system was built in such a defined way. Even the smallest misstep in terms of formatting would lead to unexpected results because the relationship between content and the style sheet was made so restrictive. For example, when you added a paragraph below a list inside a figure element, that paragraph was moved above the list in publications. As best I can tell, the reason was that figure elements had been made into flexboxes where lists and titles had been specified as subsequent final elements inside them. By itself, the results were functional and even beautiful in the same way as a jewel. Unfortunately, they were also just as unyielding and fragile.
Internal documentation
Since such procedures are inherently customer-specific, only your own documentation is available to the users. If no such internal documentation exists for them, new users who were not onboarded by their predecessors must infer the correct procedures independently. When these solutions involve an unconventional application of predefined features, there is also a risk of these features being misapplied by simply following related standard conventions. Such implementations can affect the correct ways to use the related features, after all.
More information on the importance of internal documentation and the ways to do so in DoX CMS is available here.
In the case that I have used as an example there was no internal documentation on the proper procedures. However, the previous users did show the new users how to use their solution as part of the basic workflow. The remaining challenge was understanding the background factors and thus, accunting for them when making changes to how content was written.
Summary
Different features occupy different positions on the continuum from defined to completely open-ended. Defined features do what they promise to do but attempts to apply them in other ways can break them. More open-ended features are more flexible, and you can use them to redirect more defined features. The less innate functionality they have, though, the more effort building one requires.
New functions require both some means of targeting and a thus targeted functionality. When you mix features, each must provide at least one of these, and some solution must be supplied for both. For example, element classes are a targeting method with absolutely no associated functionality. Style sheets, on the other hand, expand the functionality of the system within the boundaries of CSS and available identifiers.
You can also use targeting methods to prepare content for use by other systems. This lets these external systems add their functionalities to such marked content without a need for extra steps.
This lets you build functions in DoX CMS, such as a method to single-source recurring parts within a publication even when they change based on their subject. The solution that I proposed modifies the functionality of specified tags with the help of an element class and a style sheet, for use with content references (conref).
Of course, there are limitations to putting such solutions together. All implementations must account for the default functionalities of the involved features and ensure that the fresh solutions are compatible with the required normal use of these features. An implementation which is too complex relative to its benefits is also generally not recommended. Since all such solutions differ from standard usage, new users will find no instructions on them from the user manual. Instead, you need internal documentation which explains to them the proper conventions and the reasons behind them.