Upload a DITA Map Attachment - Fluid Topics - 3.7

Manage Map Attachments in Fluid Topics

Product
Fluid Topics
FT_Version
3.7
Category
Technical Notes

From Fluid Topics v3.4.46, ADMIN and KHUB_ADMIN users can attach files or URLs to a DITA map when publishing it.

To attach content to a DITA map, upload, through the DITA source, a ZIP archive which contains the following elements:

  • A DITA map
  • The referred-to DITA topics
  • All resources to attach

To attach a file to a DITA map, add the document references using topicref tags in the DITA map as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd">
<map title="my_map_title">
<title>My Map Title</title>
<topicref href="topic_1.dita"/>
<topicref href="topic_2.dita"/>
<topicref navtitle="Document 1" href="document_1.mp4" type="ft:attachment" processing-role="resource-only"/>
</map>

Where:

  • navtitle expects the title to display in the Reader page.
  • type="ft:attachment" allows Fluid Topics to know that this reference is a map attachment.
  • href expects the absolute path to the attached file in the project ZIP archive.
  • processing-role="resource-only" avoids displaying this topic reference in the final table of contents.

If ft:url is added in the othermeta tag of a topic reference, users are redirected to the given URL when selecting the attachment title in the Reader page.

To attach a URL to a DITA map, add the following reference to the DITA map:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd">
<map title="my_map_title">
<title>My Map Title</title>
<topicref href="topic_1.dita"/>
<topicref href="topic_2.dita"/>
<topicref navtitle="Link to an external online resource" type="ft:attachment" processing-role="resource-only">
<topicmeta>
<othermeta name="ft:url" content="https://target_url.com"/>
</topicmeta>
</topicref>
</map>

The following DITA map is an exhaustive example of the types of attachments which can be added to a DITA map:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd">
<map title="Pufferfish">
<title>Pufferfish</title>
<topicref href="pufferfish-definition.dita"/>
<topicref href="pufferfish-natural-defenses.dita"/>
<topicref navtitle="Pufferfish Story" href="Pufferfish-story.pdf" type="ft:attachment" processing-role="resource-only"/>
<topicref navtitle="Pufferfish Video" href="Pufferfish-video.mp4" type="ft:attachment" processing-role="resource-only"/>
<topicref navtitle="My little pufferfish" href="pufferfish.png" type="ft:attachment" processing-role="resource-only">
<topicmeta>
<othermeta name="ft:url" content="https://www.pufferfish.com/B91tozyQs9Mx.png"/>
</topicmeta>
</topicref>
<topicref navtitle="Pufferfish Love Explains..., on Live Science" type="ft:attachment" processing-role="resource-only">
<topicmeta>
<othermeta name="ft:url" content="https://www.livescience.com/40132-underwater-mystery-circles.html"/>
</topicmeta>
</topicref>
</map>

Once uploaded successfully, the map attachments of the Pufferfish publication can be seen in the Attachments tab of the Reader page.

Map attachments on a DITA document

Note that the attachment titles do not appear in the Table of Contents of the publication:

Map attachments do not pollute the ToC

Type icons help users to identify the content they are dealing with. For instance, when redirecting users to a PNG image available online, it can be helpful to associate the PNG mime type and icon to the file in Fluid Topics. To do so, add the file name with the .png extension in the href attribute. This way, Fluid Topics associates the PNG icon to the link in the Reader page, and users know at a glance what content to expect.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd">
<map title="my_map_title">
<title>My Map Title</title>
<topicref href="topic_1.dita"/>
<topicref href="topic_2.dita"/>
<topicref navtitle="Document 2" href="document_2.png" type="ft:attachment" processing-role="resource-only">
<topicmeta>
<othermeta name="ft:url" content="https://target_url.com"/>
</topicmeta>
</topicref>
</map>

In the previous example, it corresponds to the following lines:

...
<topicref navtitle="My little pufferfish" href="pufferfish.png" type="ft:attachment" processing-role="resource-only">
<topicmeta>
<othermeta name="ft:url" content="https://www.pufferfish.com/B91tozyQs9Mx.png"/>
</topicmeta>
</topicref>
...

In Fluid Topics, it results in the following display, showing that My little pufferfish is both an external link and a PNG image:

A URL attachment with a PNG mime type

If the same file with the same name is attached to multiple publications in the DITA map, it will be the same entity in Fluid topics.