Retrieve HTML Sections - Fluid Topics - 3.8

Integrate Fluid Topics API

Product
Fluid Topics
FT_Version
3.8
Category
Technical Notes

To retrieve the HTML content of a "section", you can use the Get an HTML Section Content web service:
/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 and dita:topicPath for DITA content.
  • filter is any metadata key-value couple that differentiates the section. Use as many metadata as needed to define unique content.

Example:

https://myportal.fluidtopics.net/api/khub/section/html?ft:baseId=12345&version=3.0&docType=Reference%20Guide
Note: To learn more about the way to use the metadata to filter content in the web service scope, consult our Deep Links to Official Content section.
A section can be:
  • a short structured publication (book or article, usually a knowledge-base-like entry)
  • a topic and all its children

Just like the deep link web services, the Get an HTML Section Content web service performs a search using all the query parameters as filters, then takes the top result to define the returned section (either a map or a topic). As in the HTML export, 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 an HTML Section Content 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

A common use case would be the inline-help scenario. From a third-party integration, an integrator wants to point to content already available in Fluid Topics, and display it in context to its end-users, for instance in a popup.

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 the step_1 content in a HTML section, you can use the following call to the API:
https://your.fluidtopics.com/OleanDor/api/khub/section/html?step=1
It 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 the HTML section is retrieved, it is displayed in a popup to guide users in their part replacement task:
Step 1 is embedded in a popup

The same is done for the other steps of the Maintenande Guide.
Step 2 and its children embedded in a popup

Step 3 is embedded in a popup

Step 4 is embedded in a popup