Thursday, April 5, 2012

Working with Structured Documents

When working with a structured document, you can choose to navigate the document using the tree of elements. Or, if it is more convenient, you can work with the document as if it does not have structure. That is, you can work with paragraphs in the main flow exactly as you would in unstructured FrameMaker.

Is there a downside to this approach? The answer is, it depends. If you are cutting and pasting or otherwise adding content, working outside the element structure may lead you to make changes that leave the structure invalid. But if you are simply inspecting the document or you are working with content that is not part of the element structure (e.g.. marker content), feel free to do whatever is easiest.

Selecting an Entire Element

Selecting elements is tricky business. You will find helpful information in the FDK Programmer's Guide. I happen to have the one for version 6 on hand. In that version, you should refer to pages 366-7.

The key idea is to create an ElementRange that refers to the appropriate selection and then set the document's element selection to be that range. The following function sets the specified document's element selection to be the element passed in.

Element ranges have a beginning and an end. They consist of parent, child, and offset information. 

The parent element is the containing element for both the beginning and end of the range. The starting child is the element itself. The ending child is the element's next sibling element. As the whole element is being selected, both offsets are zero.

//Selects the specified element in the specified document
function setElementSelection(doc, element) {
        var eRange = new ElementRange;
        eRange.beg.parent = element.ParentElement;
        eRange.beg.child = element;
        eRange.beg.offset = 0;
        eRange.end.parent = element.ParentElement;
        eRange.end.child = element.NextSiblingElement;
        eRange.end.offset = 0;
        doc.ElementSelection = eRange;