Adding fields to DITA topics

[daudvyd]

Hi folks,

I'm trying to understand how to add fields to a DITA topic. My understand is that this is called "customizing" or "extending" and I've already read the relevant Oxygen XML documentation. I know I'm supposed to build upon the established DITA concept and also to define how the new field will be rendered. But, I'd really appreciate some more guidance because, right now, this seems pretty daunting.

When I create a new DITA task, I get a blank document with fields for title, short description, about this task, and the first item in a list of steps. Let's say I wanted to create a new type of DITA task that had a "prerequisites" field that should be rendered in the same font as the short description but would start with the text "Prerequisites:"--how would I do that? How about if it were also to be enclosed in a box with a solid black line and gray background?

Thank you,
-d. vyd

[alex_jitianu]

Hello,

it looks like what you need are some new document templates. Please note that in your case, at step 2, the new template should be saved in a specific framework's directory. The content of this template should contain the "prerequisites" element as well as any other desired structure:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="task_w4s_lg2_wfb">

    <title></title>

    <shortdesc></shortdesc>

    <taskbody>

        <prereq id="prereq_dll_mg2_wfb"></prereq>

        <context>

            <p></p>

        </context>

        <steps>

            <step>

                <cmd></cmd>

            </step>

        </steps>

    </taskbody>

</task>

By default, Oxygen renders a label before the prerequisites element that states: "Before you begin".

should be rendered in the same font as the short description but would start with the text "Prerequisites:"--how would I do that? How about if it were also to be enclosed in a box with a solid black line and gray background?

What you need is CSS level customization. The first thing you must do is to create a CSS file inside the framework to keep the rules you are about to create. Afterwards, to style the prerequisites element you write a CSS rule like this:

Code: Select all

*[class~="task/prereq"] {

  border: 1px solid black;

  background-color:gray;

}



*[class~='task/prereq']:before {

    content : "Prerequisites: " !important;

}

The CSS Inspector view is a valuable tool that you can use to see how the various elements are styled and to decide how you can change that styling.

Best regards,
Alex

[daudvyd]

Thanks Alex! A few follow-up questions:

1. The framework directory can be anywhere on my drive?
2. Does the framework directory need to be specified in Oxygen's settings somewhere?
3. The framework directory only needs the template and CSS file?
4. The CSS file needs instructions for rendering all the fields or just the new "prerequisite" field?

-d. vyd

[alex_jitianu]

Hello,

A DITA framework already exists so what you want to do is either change the existing one or extend it. I would say the recommended choice is to extend it because you will make switching to the next Oxygen version easier.

After you create the extension you need to do is to create a CSS that contains just the additional CSS rule needed to style the prerequisites element and add it to the framework. Do not associate a title with this CSS and it will be applied over the existing CSS.

For the template, you need to create a directory inside the framework directory and save the document template there. Afterwards, open the Document Type configuration dialog box for that specific framework, go to the Templates tab, and click the Plus button in the bottom-right corner to add your new directory to the list. It is recommended that the reference be made relative to the framework directory (for example, ${frameworkDir}/templates).

Best regards,
Alex