DITAVAL

Set up DITA topics to use DITAVAL

See how you can setup DITA topics to use DITAval and apply conditional attributes to elements.

You can make elements in a DITA document conditional by applying condition attributes to the elements. You then define, in a DITAVAL file, the elements to exclude or include in the output based on the condition attributes.

Before you create documents with conditional content, you need to first plan the criteria for the output. For example, say that a document has content that is conditionally targeted at administrators and end users. In the document, you apply condition attributes based on the target audience of the content (see Applying condition attributes to elements). You then create a DITAVAL file in which you specify the elements to include and exclude based on the attribute value defined in the document. See Creating a DITAVAL file to create conditional output.

Applying condition attributes to elements

To allow FrameMaker to conditionally process elements in a DITA document, you need to specify the elements to include or exclude for the output. In the document, you apply one or more of the following conditional attributes to the elements that you need to conditionally process:

audience:

Example: administrators, authors, or end users.

platform:

Example: Windows, MAC, or Linux

product:

Example: FrameMaker, RoboHelp, or Captivate.

otherprops:

Use this attribute to define any other property that you need to use to enable conditional processing for the document. A few examples:

delivery: Example: Print, PDF, or Web
model: hatchback or sedan

You can apply multiple attributes to an element. For example, you can apply @audience="administrator" and @platform="windows" to an element. You can also add multiple values (each separated by a space) to a single attribute. For example, you can set @platform="windows linux" for content targeted at both Windows and Linux.

Important: The attributes listed above are recommended for use when working with DITAVAL to single-source content. However, you are not restricted to only using these attributes. You can use any attribute defined for the selected element in a document.

To apply condition attributes to an element

Select an element in the Structure View of the document.
Open the Attributes panel (Element > Edit Attributes).

Update one or more of the following attributes:
- audience
- platform
- product
- otherprops
Specify the above condition for each of the element in the document that needs to be processed conditionally.

After you apply the attributes to the specific elements in the document, you conditionally output the content in your document depending on how you set up your DITAVAL file.

Creating a DITAVAL file to create conditional output

After setting up your content using condition attributes (audience, platform, product, and otherprops) to define the elements that FrameMaker conditionally processes for output, you need to create a DITAVAL file. In a DITAVAL file, you define, based on an <attribute name> - <value> pair, the conditional processing of your document. For example, you can specify that content targeted at administrators must exclude from the output content targeted at end users or authors.

To create a DITAVAL file:

Open the New XML dialog (File > New > XML).
In the Structured Applications section, select DITA_<version>_DITAVAL and click OK.

The top element of a DITAVAL file is the <val> element.

To define conditions, you need to create <prop> elements.
Add one or more <prop> elements:

Double-click the <prop> element in the Element panel (View > Panels > Element Catalog).

Or press Ctrl+1 to display the Smart Catalog and choose prop and press Enter.

The Attributes for New Element dialog is displayed.
Attributes for New Element dialog
In the Attributes for New Element dialog, specify the following attributes:

@action

Choose to include or exclude the specified attribute (@att, below) from the output.

@att

The condition attribute name applied to the element in your document.

Enter the attribute name exactly as it is defined in the document element.

@val

The condition attribute (@att) value as defined in the element.

Enter the value exactly as you specify it for the attribute in the element.

For example, say that you apply the @audience attribute to an element for conditional output and you set the value as admin. You need to enter audience in the @attr field for the prop element in the DITAVAL file. Also, you need to enter admin in the @val field. To exclude the element with the audience attribute set to admin, specify the @action as exclude.
Click Insert Element and save the DITAVAL file.
Save the document with the .ditaval extension.

Generate conditional output

Know how you can generate conditional output for DITA topics in FrameMaker.

This section covers, with a sample use case, the steps to generate a PDF output containing conditional content.

Note: The sample used in this section includes content only in paragraph (p) tags. You can, however, create conditional output from any DITA element in a document.

Create a DITA topic with four paragraph (<p>) elements:
1. Content ONLY for administrators.
  
  Set the @audience attribute to admin.
2. Content ONLY for authors.
  
  Set the @audience attribute to author.
3. Content for administrators and authors
  
  Set the @audience attribute to admin author.
4. Content for end users and authors.
  
  Set the @audience attribute to end_user author.
Save the document.
Create DITAVAL file with four prop elements:
1. @attr: audience
  
  @val: admin
  
  @action: include
2. @attr:audience
  
  @val:author
  
  @action: exclude
3. @attr:audience
  
  @val:end_user
  
  @action: exclude
The above DITAVAL will output all content targeted at administrators.
Create a DITA map and include the above document and save the DITA map as a PDF (File > Save As PDF).
In the Save Document dialog, check the Prompt For DitaVal File option and click Save.

The Choose DitaVal File dialog appears.
Select the DITAVAL file created in step 4 and click Choose.

The Apply As Condition option will output the entire contents. However, the contents that is marked as excluded in the DITAVAL file is output with a strike-through. You choose this option for document review. For example, use this option to indicate to a reviewer the contents that is marked as excluded.
In the PDF Setup dialog, click Set.

The output PDF file includes and excludes content based on the attributes that are set up in the document and the corresponding DITAVAL file.