Upload an Ftmap 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.5.7, ADMIN and KHUB_ADMIN users can attach files or URLs to an Ftmap when uploading the Ftmap through the FTML source.

To attach files to an Ftmap, prepare a ZIP archive with following elements:

  • The referred-to HTML or Markdown topics
  • All files to attach
  • An Ftmap with each file between <ft:attachment> tags as follows:

<ft:map xmlns:ft="http://ref.fluidtopics.com/v3/ft#" ft:lang="en-US" ft:originID="ftmap_id" ft:title="My Map Title"
ft:editorialType="book">
<ft:toc>
<ft:node ft:originID="first_topic" href="topics/topic_1.html" ft:title="My Topic 1" type="topic">
<ft:node ft:originID="origin_id" href="topics/topic_2.html" ft:title="My Topic 2" type="topic">
</ft:node>
</ft:node>
</ft:toc>
<ft:attachments>
<ft:attachment>
<ft:originID>document_1</ft:originID>
<ft:filePath>document_1.png</ft:filePath>
<ft:filename>my_file.png</ft:filename>
<ft:displayName>Document 1</ft:displayName>
<ft:mimeType>image/png</ft:mimeType>
</ft:attachment>
</ft:attachments>
</ft:map>

Where:

  • ft:attachment expects all the information related to an attachment
  • ft:originID is the ID given to the file to attach. Make sure that the originID is unique within ALL the Ftmap attachments.
  • ft:filePath expects the relative or absolute path to the attached file in the project ZIP archive. This parameter is mandatory.
  • ft:filename expects the filename of the document to download from the Viewer page.
  • ft:displayName expects the title to display in the Reader page.
  • ft:mimeType is the MIME type corresponding to the content of the attachment. It is used to override the attachment type calculated by Fluid Topics.

To attach a URL to an Ftmap, add the following reference to the Ftmap:

<ft:map xmlns:ft="http://ref.fluidtopics.com/v3/ft#" ft:lang="en-US" ft:originID="ftmap_id" ft:title="My Map Title"
<ft:toc>
<ft:node ft:originID="first_topic" href="topics/topic_1.html" ft:title="My Topic 1" type="topic">
<ft:node ft:originID="origin_id" href="topics/topic_2.html" ft:title="My Topic 2" type="topic">
</ft:node>
</ft:node>
</ft:toc>
<ft:attachments>
<ft:attachment>
<ft:originID>$ATTACHMENT_ORIGIN_ID</ft:originID>
<ft:url>$URL_TO_ATTACH</ft:url>
<ft:displayName>My Link</ft:displayName>
<ft:mimeType>$MIMETYPE_OF_THE_URL_TARGET</ft:mimeType>
</ft:attachment>
</ft:attachments>
</ft:map>

Where:

  • ft:attachment expects all the information related to an attachment
  • ft:originID is the ID given to the file to attach. Make sure that the ft:originID is unique within ALL the Ftmap attachments.
  • ft:url is the URL to attach to the Ftmap. This parameter is mandatory.
  • ft:displayName expects the title to display in the Reader page.
  • ft:mimeType is the MIME type corresponding to the content of the attachment. It is used to display the type icon of the attachment.

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

<ft:map xmlns:ft="http://ref.fluidtopics.com/v3/ft#" ft:lang="en-US" ft:originID="ftmap_id" ft:title="Time Machine User Guide"
ft:editorialType="book">
<ft:rights accessLevel="restricted">
<ft:groups>
<ft:group>Expert</ft:group>
</ft:groups>
</ft:rights>
<ft:metas>
<ft:meta key="Status" type="stringTree">Market-Ready</ft:meta>
<ft:meta key="Version" type="string">2.0</ft:meta>
<ft:meta key="audience" type="string">Expert</ft:meta>
</ft:metas>
<ft:toc>
<ft:node ft:originID="first_topic" href="topics/intro_to_time_machines.html" ft:title="Introduction to Time Machines" type="topic">
<ft:node ft:originID="origin_id" href="topics/how_to_time_travel.html" ft:title="How to Time Travel" type="topic">
</ft:node>
</ft:node>
</ft:toc>
<ft:attachments>
<ft:attachment>
<ft:originID>drawing</ft:originID>
<ft:filePath>attachments/drawing.png</ft:filePath>
<ft:filename>time_machine_drawing.png</ft:filename>
<ft:displayName>Time Machine Drawing</ft:displayName>
<ft:mimeType>image/png</ft:mimeType>
</ft:attachment>
<ft:attachment>
<ft:originID>spare_parts</ft:originID>
<ft:filePath>attachments/Spare_Part_Price_List.pdf</ft:filePath>
<ft:filename>time_machine_spare_part_prices.pdf</ft:filename>
<ft:displayName>Spare Part Price List</ft:displayName>
<ft:mimeType>application/pdf</ft:mimeType>
</ft:attachment>
<ft:attachment>
<ft:originID>mounting_scheme</ft:originID>
<ft:url>https://timemachines.com/time-machine.jpg</ft:url>
<ft:displayName>Time Machine Mounting Scheme</ft:displayName>
<ft:mimeType>image/jpeg</ft:mimeType>
</ft:attachment>
</ft:attachments>
</ft:map>

Once uploaded successfully, the map attachments of the Time Machine User Guide document can be seen in the Attachments tab of the Reader page.

Documents attached to FTML content

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

Map attachments do not appear in the table of contents

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 MIME type in the <ft:mimeType> tag. 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.

...
<ft:attachment>
<ft:originID>drawing</ft:originID>
<ft:url>$URL_TO_ATTACH</ft:url>
<ft:displayName>My Link</ft:displayName>
<ft:mimeType>$MIMETYPE_OF_THE_URL_TARGET</ft:mimeType>
</ft:attachment>
...

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

...
<ft:attachment>
<ft:originID>mounting_scheme</ft:originID>
<ft:url>https://timemachines.com/time-machine</ft:url>
<ft:displayName>Time Machine Mounting Scheme</ft:displayName>
<ft:mimeType>image/jpeg</ft:mimeType>
</ft:attachment>
...

In Fluid Topics, it results in the following display, showing that Time Machine Mounting Scheme is both an external link and a JPG image:

An external link to the JPEG content as a map attachment

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.