content.md

Extracting the content of a publication

⚠️ The described feature is still experimental and the implementation incomplete.

Many high-level features require access to the raw content (text, media, etc.) of a publication, such as:

• Text-to-speech
• Accessibility reader
• Basic search
• Full-text search indexing
• Image or audio indexes

The ContentService provides a way to iterate through a publication's content, extracted as semantic elements.

First, request the publication's Content, starting from a given Locator. If the locator is missing, the Content will be extracted from the beginning of the publication.

val content = publication.content(startLocator)
if (content == null) {
    // Abort as the content cannot be extracted
}

Extracting the raw text content

Getting the whole raw text of a publication is such a common use case that a helper is available on Content:

val wholeText = content.text()

This is an expensive operation, proceed with caution and cache the result if you need to reuse it.

Iterating through the content

The individual Content elements can be iterated through with a regular for loop:

for (element in content) {
    // Process element
}

Alternatively, you can get the whole list of elements with content.elements(), or use the lower level APIs to iterate the content manually:

val iterator = content.iterator()
while (iterator.hasNext()) {
    val element = iterator.next()
}

Some Content implementations support bidirectional iterations. To iterate backwards, use:

while (iterator.hasPrevious()) {
    val element = iterator.hasPrevious()
}

Processing the elements

The Content iterator yields Content.Element objects representing a single semantic portion of the publication, such as a heading, a paragraph or an embedded image.

Every element has a locator property targeting it in the publication. You can use the locator, for example, to navigate to the element or to draw a Decoration on top of it.

navigator.go(element.locator)

Types of elements

Depending on the actual implementation of Content.Element, more properties are available to access the actual data. The toolkit ships with a number of default implementations for common types of elements.

Embedded media

The Content.EmbeddedElement interface is implemented by any element referencing an external resource. It contains an embeddedLink property you can use to get the actual content of the resource.

if (element is Content.EmbeddedElement) {
    val bytes = publication
        .get(element.embeddedLink)
        .read().getOrThrow()
}

Here are the default available implementations:

• Content.AudioElement - audio clips
• Content.VideoElement - video clips
• Content.ImageElement - bitmap images, with the additional property:
  • caption: String? - figure caption, when available

Text

Textual elements

The Content.TextualElement interface is implemented by any element which can be represented as human-readable text. This is useful when you want to extract the text content of a publication without caring for each individual type of elements.

val wholeText = publication.content()
    .elements()
    .filterIsInstance<Content.TextualElement>()
    .mapNotNull { it.text }
    .joinToString(separator = "\n")

Text elements

Actual text elements are instances of Content.TextElement, which represent a single block of text such as a heading, a paragraph or a list item. It is comprised of a role and a list of segments.

The role is the nature of the text element in the document. For example a heading, body, footnote or a quote. It can be used to reconstruct part of the structure of the original document.

A text element is composed of individual segments with their own locator and attributes. They are useful to associate attributes with a portion of a text element. For example, given the HTML paragraph:

<p>It is pronounced <span lang="fr">croissant</span>.</p>

The following TextElement will be produced:

TextElement(
    segments = listOf(
        Segment(text = "It is pronounced "),
        Segment(text = "croissant", attributes = mapOf(LANGUAGE to "fr")),
        Segment(text = ".")
    )
)

If you are not interested in the segment attributes, you can also use element.text to get the concatenated raw text.

Element attributes

All types of Content.Element can have associated attributes. Custom ContentService implementations can use this as an extensibility point.

Use cases

An index of all images embedded in the publication

This example extracts all the embedded images in the publication and displays them in a Jetpack Compose list. Clicking on an image jumps to its location in the publication.

data class Item(
    val locator: Locator,
    val text: String?,
    val bitmap: ImageBitmap?
)

var images by remember {
    mutableStateOf<List<Item>>(emptyList())
}

LaunchedEffect(publication) {
    publication.content()?.let { content ->
        images = content.elements()
            .filterIsInstance<Content.ImageElement>()
            .map { element ->
                Item(
                    locator = element.locator,
                    text = element.caption,
                    bitmap = publication.get(element.embeddedLink)
                        .readAsBitmap().getOrNull()?.asImageBitmap()
                )
            }
    }
}

LazyColumn {
    items(images) { item ->
        if (item.bitmap != null) {
            Column(
                modifier = Modifier.clickable {
                    navigator.go(item.locator)
                }
            ) {
                Image(bitmap = item.bitmap, contentDescription = item.text)
                Text(item.caption ?: "No caption")
            }
        }
    }
}

References

• Content Iterator proposal