Get HTML Sections - Fluid Topics - 3.10 - Technical Notes

Integrate Fluid Topics APIs

Product
Fluid Topics
Fluid Topics Version
3.10
Category
Technical Notes
Language
English
Target Audience
public

The Get the Content of an HTML Section web service retrieves the content of a section in HTML format:

/api/khub/section/html?context_id=1234&filter_1=value_1&...&filter_n=value_n

Where:

  • context_id depends on the content type. For instance, it can be ait:code for Author-it content, or dita:mapPath or dita:topicPath for DITA content.
  • filter is any metadata key that differentiates the section. Use as many metadata keys as needed to define unique content.

The following line shows an example of a Get the Content of an HTML Section web service call:

https://myportal.fluidtopics.net/api/khub/section/html?ft:baseId=12345&version=3.0&docType=Reference%20Guide

More information about using metadata within web service calls to target and filter content is available in Deep Links.

An HTML section can be:

  • a short, structured publication (book or article)
  • a topic and all its children

The Get the Content of an HTML Section web service performs a search using all the query parameters as filters. It then takes the top result to define the returned section (either a map or a topic). As when exporting content to HTML format, all cross-guide links are disabled. Also, internal links pointing outside of the section are disabled.

The following lines show an example of the Get the Content of an HTML Section web service implementation in JavaScript.

getTopic(meta, value) {
fetch('https://<host>/<tenantId>/api/khub/section/html?'+meta+'='+value, {
method: 'get',
headers: { 'Content-Type': 'text/html' }
})
.then(
response => response.text(),
error => console.log('failed to fetch html', error)
)
.then(
/* display the html wherever you want */
html => alert(html),
error => console.log('failed to fetch html', error)
)
}

Use Case

An integrator wants to display content available in Fluid Topics within a third-party integration. The following lines show the OleanDor Maintenance Guide FTML document that was published to Fluid Topics:

&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;ft:map ft:editorialType="book" ft:lang="en-US" ft:originID="maintenance"
ft:title="Maintenance Guide" xmlns:ft="http://ref.fluidtopics.com/v3/ft#">
&lt;ft:toc>
&lt;ft:node ft:title="Find the anomaly" href="step1.html" type="topics">
<ft:metas>
<ft:meta key="procedure" type="stringTree">annual checkup</ft:meta>
<ft:meta key="step" type="stringTree">1</ft:meta>
</ft:metas>
</ft:node>
<ft:node ft:originID="Replace" ft:title="Replace the piece">
<ft:metas>
<ft:meta key="procedure" type="stringTree">annual checkup</ft:meta>
<ft:meta key="step" type="stringTree">2</ft:meta>
</ft:metas>
<ft:node ft:title="Remove broken part" href="step2_1.html" type="topics">
<ft:metas>
<ft:meta key="procedure" type="stringTree">annual checkup</ft:meta>
<ft:meta key="step" type="stringTree">2.1</ft:meta>
</ft:metas>
</ft:node>
<ft:node ft:title="Put new one in" href="step2_2.html" type="topics">
<ft:metas>
<ft:meta key="procedure" type="stringTree">annual checkup</ft:meta>
<ft:meta key="step" type="stringTree">2.2</ft:meta>
</ft:metas>
</ft:node>
</ft:node>
<ft:node ft:title="Checking" href="step3.html" type="topics">
<ft:metas>
<ft:meta key="procedure" type="stringTree">annual checkup</ft:meta>
<ft:meta key="step" type="stringTree">3</ft:meta>
</ft:metas>
</ft:node>
</ft:toc>
</ft:map>

In the Maintenance Guide document, topics are organized as follows:

Maintenance Guide
├── step_1
├── step_2
│ ├── step_2_1
│ └── step_2_2
└─ step_3
└── step_4

To retrieve content about Step 1 in HTML format, the integrator sends the following API call:

https://my.fluidtopics.com/OleanDor/api/khub/section/html?step=1

The web service returns the following HTML content:

<section class="ft-section">
<div id="W6fcZEhu7AJpXc2UXUJx~w" class="ft-topic">
<h1 class="ft-topic-title ft-toc-level-1">Find the anomaly</h1>
<article class="ft-topic-body">
<div class="content-locale-en-US content-locale-en">
<div>
<p>
Possible problems
<br>
- Abnormal noise
<br>
- Random rotator stop
</p>
</div>
</div>
</article>
</div>
</section>

Once retrieved, the HTML section is displayed in a series of pop-ups to guide users through the steps of replacing a part as follows:

Section 2

Step 3

Step 4