Data Model

Introduction

HOOPS Publish enables the creation of interactive documents featuring distinct data and view layers.

For example, data can be stored within a data table, which can later be bound to widgets such as a scroll table or a list box.

Moreover, the relationship between distinct data tables can define dynamic behavior within a PDF, updating the content displayed in a widget whenever a specific event (such as a mouse-click selection) occurs elsewhere in the document.

The subsequent sections provide a more detailed explanation of how this functionality operates.

Creating a Data Table

A Data Table is a tabular data structure that stores an array of pointers to strings of type A3DUTF8Char.

struct {
    A3DInt32      uNbRow;
    A3DInt32      uNbCol;
    A3DUTF8Char** m_ppcTexts;
} A3DPDFDataTableData;

It can be utilized to store content intended for display in various field or high-level widget types, such as text fields, list boxes, buttons, scroll tables, and more.

To display the following items in a list box, define a table with five rows:

../../_images/defining_data_table.png

The content displayed in a particular widget can change depending on the selection made in another widget. In this example, the information shown in the “Required Parts” list box is updated based on the item selected in the “Procedure Steps” list box.

../../_images/table_relationships.png

In this case, Table 2 is used to define all the content that could potentially be displayed in the “Required Parts” list box.

Setting a Relationship Between Tables

In the previous example, clicking on an item in the “Procedure Steps” widget dynamically populates the data in the “Required Parts” list box.

To define this, a relationship table must be established:

struct {
    A3DPDFDataTableData* pTable1;
    A3DPDFDataTableData* pTable2;
    A3DInt32             m_iSizeMap;
    A3DPDFMapIndexData*  m_pMapIndexes;
} A3DPDFDataRelationshipData;

This table will establish a relationship (a data mapping) between Table 1 and Table 2, specifying what content from Table 2 will be displayed whenever an item in Table 1 is selected:

../../_images/table_relationships_b.png

Binding a Data Table

Once the data tables have been created, they need to be bound to widgets that are used to display their content. This is achieved using the BindToTable functionality, which can be applied to:

  • TextField

  • ScrollTable

  • ListBox

  • DropDownList

  • ViewCarousel

  • DataFilter

  • 3DNodeScene

  • 3DViewList

Binding columns

The columns of the widgets need to be associated with columns of the bound data table. This association is accomplished by providing a map of columns in the binding function call. Specific columns can be designated in a data table to associate actions with the selection of a row. These columns are not displayed in the widget. These action columns must be bound to the widgets using the A3DPDFWidgetBindColumnsActions() function.

Defining a Widget Behavior on Interaction

Finally, a behavior type must be defined to describe how widgets will be updated when an item is selected in another source widget.

In the following example, the data in the Required Parts listbox will be updated after a Procedure Step is selected.

Isolated

Highlighted

isolated

highlighted

Three types of behavior can be defined: Isolate, Highlight and Selected.

Setting the behavior is done by calling A3DPDFWidgetSetTargetBehaviour(). See the function description for more information. The following example chooses the “isolate” behavior:

A3DPDFWidgetSetTargetBehaviour(pListBox_ProcedureStep, pListBox_Requiredpart, kA3DPDFDataIsolate);

Setting up highlight properties

On PDF files generated with the datamodel API, customers can configure properties for highlighting behavior within 3D scenes. With this, customers need to write some JavaScript at the document level (typically on the UI widgets on a page) to set the highlight properties.

The JavaScript code snippet looks like this:

getHighlightManagerFor3DAnnot().setHighlightMode(_TS3D_HIGHLIGHTMODE.ISOLATE);

getHighlightManagerFor3DAnnot can accept a page index and a 3D Annotation Index:

getHighlightManagerFor3DAnnot(pageIndex, annotIndex)  // to specify the page index and 3d annot index on the page

If not set, it defaults to first page and annot indices.

Another version of the function is provided to accept the generated UUID for the 3D annot:

getHighlightManagerFor3DAnnotWithId(annotuuid)

Following properties are supported by using set methods:

  • setHighlightColor(r,g,b): Highlight color in Red/Green/Blue component, each channel in [0.0;1.0] space. Default is red.

  • setLevelOpacity(dLevelOpacity): Percentage of opacity applied in transparency mode, in [0.0;1.0] (defaults to 0.2).

  • setIsBlinking(bIsBlinking): When true the highlighted nodes are blinking.

  • setBlinkNumber(iBlinkNumber): Number of times the nodes are blinking (default: 3).

  • setBlinkPeriod(iBlinkPeriod): Duration of blink in ms (default: 300) .

  • setHighlightMode(eHighlightMode): Set highlight modes with following values:

    • _TS3D_HIGHLIGHTMODE.ISOLATENODES

    • _TS3D_HIGHLIGHTMODE.COLORNODES_AND_TRANSPARENCY

    • _TS3D_HIGHLIGHTMODE.ISOLATENODES_COLORFACES_AND_TRANSPARENCY

    • _TS3D_HIGHLIGHTMODE.COLORNODES

  • setEnableAutoFit(bEnableAutoFit): When true, automatically fits the scene to the highlighted nodes.

Miscellaneous

For a working example of how interaction between 3D annotations and the documents can be set up, please see the DemoDataModel sample (only available for HOOPS Publish Advanced customers).