Structure Tagging and Alternate Text in PDFs

📌 Overview

The Mako SDK has APIs to tag elements according to their purpose. Known as structure tags, they are not displayed in the document, but are used by assistive technology such as screen readers for the visually impaired to present the page content with a synthetic voice. Tags establish logical reading order and provide a means of indicating document structure and element type, adding alternative text to non-text elements or substitute text for elements in the PDF document.

This blog article on tagging elements in a PDF may be of interest.

📗 Instructions

Here we describe how to use Mako to tag a paragraph, an image and add alternate text to the image.

🪜 Steps

Set the tagged PDF property using IDOMMetadata - This is necessary so that a viewer is aware that tags are present in the document.
Create the IStructure - This will be used to tag the content
Create a paragraph structure element and tag the relevant glyphs node - You can also tag a group node to tag all the nodes within the group.
Tag an image and add to it alternate text - Alternate text is voiced by a screen reader, providing a description of the image content.

⌨️ Sample Code

Here is an example implementation of the above steps Also included in the Mako SDK within the simpleexamples project is pdfuacreation.cpp (also .cs and .java) which contains additional examples of structure tagging, such as tables.

C#

  // Get or create the metadata
  IDOMMetadata metadata = assembly.getJobMetadata();
  if (metadata == null)
  {
        metadata = IDOMMetadata.create(factory);
  }
  // And add the Marked property - set tagged pdf property
  metadata.setProperty(IDOMMetadata.eType.ePDFInfo, "Marked", new PValue(true));

  assembly.setJobMetadata(metadata);

 // Create the Structure which will be used to tag the content
 IStructure structure = IStructure.create(jawsMako);
 document.setStructure(structure);

 IStructureElement documentElement = IStructureElement.create(jawsMako, "Document");
 documentElement.setTitle("Example Title");
 structure.appendElement(documentElement);

  // Create the paragraph structure element
 IStructureElement paragraphElement = IStructureElement.create(jawsMako, "P");
 documentElement.appendElement(structure, paragraphElement);

 IDOMGlyphs glyphsnode = node.getContentGlyphs();
 if (glyphsnode != null)
     structure.tagNode(paragraphElement, page, glyphsnode);

 CEDLVectIDOMNode pathNodes = fixedPage.findChildrenOfType(eDOMNodeType.eDOMPathNode);

 foreach (var node in pathNodes.toArray())
 {
     IDOMPathNode pathNode = IDOMPathNode.fromRCObject(node);
     IDOMBrush brush = pathNode.getFill();

     if (brush != null && brush.getBrushType() == IDOMBrush.eBrushType.eImage)
     {
         IDOMImageBrush imageBrush = IDOMImageBrush.fromRCObject(brush);
         if (imageBrush != null)
         {
             IStructureElement imageElement = IStructureElement.create(jawsMako, "Figure");
             imageElement.setAlternate("Example of Alternate text");
             imageElement.setLanguage("en");
             IPDFDictionary attributes = IPDFDictionary.create(jawsMako);
             attributes.put("BBox", createPdfBBoxForNode(fixedPage, node));
             attributes.put("O", IPDFName.create(jawsMako, "Layout"));
             attributes.put("Placement", IPDFName.create(jawsMako, "Block"));
             imageElement.setAttributes(attributes);
             documentElement.appendElement(structure, imageElement);
             structure.tagNode(imageElement, page, node);
         }
     }
 }

☑️ Conclusion

The Mako SDK provides powerful APIs for enhancing PDF accessibility through structure tagging and alternate text. By following the outlined steps, users can effectively tag elements such as paragraphs and images, ensuring that assistive technologies can accurately interpret and present the document's content. The sample code demonstrates the practical implementation of these features, contributing to a more inclusive digital experience.

📚 Additional Resources

If you need additional help, see our API documentation for detailed information on class/method usage, or raise a support ticket via our customer portal.