Nav Widgets

In PISE, the Proofscape Integrated Study Environment, the three Content Types of Charts, Notes, and Docs are viewed in panels described by the corresponding names: chart panels, notes panels, and doc panels.

The notes you write in annotations and Sphinx pages are loaded, naturally, in notes panels. But among the main purposes of such notes is to talk about what’s happening in the other two content types: charts and docs. Therefore you need ways to load, control, point to, talk about, highlight, and navigate chart and doc panels, from notes panels. This is exactly what navigation or “nav” widgets are for.

Accordingly, there are two types of nav widgets: chart widgets to control chart panels, and doc widgets to control doc panels.

Appearance

Nav widgets appear like “links” in the page: clickable text, that does something when you click it. Thus, they are an inline widget, meaning they appear within the flow of a paragraph.

In terms of The four widget components, nav widgets always require a LABEL, which becomes the clickable text that represents them.

Navigation groups

As you will find in the specs for chart and doc widgets, each nav widget accepts a DATA field called group, where you can define the widget’s navigation group:

A navigation group, or “nav group” for short, is a set of navigation widgets, all of which navigate one and the same panel.

Navigation groups let you group nav widgets together and make them navigate a single, shared panel. As demonstrated in Part 7: Navigation Groups of the Authors’ Tutorial, you can use this to divide up the widgets within a single page into separate groups, or to put widgets belonging to different pages into a single, multi-page group.

The group field

• Type: When defining the group field in a nav widget’s DATA component,’ you may pass either a string, or an integer. If you pass an integer, it is converted internally into a string. Thus, integers are accepted purely as a shorthand, allowing you to type, say, 2 instead of "2".

• Format: If you choose to pass a string (instead of an integer), then you can take advantage of a two-part format:

  Listing 70 Format of the group field

  [DOTS]NAME
  

  in which you can set both the NAMESPACE and the NAME (see below). The leading DOTS, if any, bring you up to higher namespaces, while the NAME part literally sets the NAME.

• Default: If you do not define the group field, then its value is set to the empty string, which puts the widget in The default group for the page.

The Group ID

Each navigation group is uniquely determined by a four-part ID, called the Group ID:

Listing 71 The format of a navigation group ID

TYPE:SUBTYPE:NAMESPACE:NAME

Of these four parts, the TYPE and SUBTYPE are beyond your control, while the NAMESPACE and NAME are determined by what you set in the widget’s group field (or do not set, if you choose to leave it undefined). The four parts are explained below.

Important

The Group ID is something that’s used internally by PISE, and you do not work with it directly; but you do need to understand it, so that you can tell whether two widgets are in the same group or not.

TYPE

The type is simply equal to the name of the widget type: chart for chart widgets, doc for doc widgets.

This ensures that widgets of different types never try to control the same panel.

SUBTYPE

• For chart widgets, the SUBTYPE is the empty string.

• For doc widgets, the SUBTYPE is equal to the docId of the document the widget points to.

This ensures that doc widgets pointing to different documents can never belong to the same group. This makes sense, because they obviously cannot use the same panel, which only hosts one document.

The reason chart widgets do not have a subtype, is because chart panels work differently than doc panels. Whereas a doc panel hosts one and only one document, a chart panel can host any, changing combination of deductions.

NAMESPACE

The NAMESPACE becomes relevant when you want widgets on different pages to belong to a common group. It is equal to the libpath of one of the following entities:

• The page to which the widget belongs (this is the default NAMESPACE), or

• The module in which that page is defined, or

• Any ancestor module of that one, up to and including the root module of the repo.

Thus, for a widget having absolute libpath

test.foo.bar.dir.mod._page.w1

the possible namespaces would be:

test.foo.bar.dir.mod._page
test.foo.bar.dir.mod
test.foo.bar.dir
test.foo.bar

You can set the NAMESPACE by including leading dots in your group field, as indicated in Listing 70. Each leading dot moves up to one higher namespace, while using no dots leaves you in the default namespace, i.e. that of the page to which the widget belongs.

Thus, continuing with the above example,

Table 13 Examples of group determining NAMESPACE and NAME

group	NAMESPACE	NAME
foo	test.foo.bar.dir.mod._page	foo
.foo	test.foo.bar.dir.mod	foo
..	test.foo.bar.dir	(empty string)

NAME

The NAME in the Group ID is set equal to the NAME part you set in the group field, as shown in Listing 70. See the examples in Table 13.

The default group

To which nav group does a nav widget belong if we don’t define its group field at all?

We can answer this question from our understanding of The Group ID.

As noted above, the default value for group is the empty string. In terms of the Group ID, this means NAMESPACE takes on its default value, which is the libpath of the page to which the widget belongs, while NAME is equal to the empty string.

Thus, all widgets which:

• have empty (undefined) group, and

• belong to the same page, and

• are of the same type and subtype

automatically belong to a single group, which we call the default group of the page, for the given type and subtype.

Note that no widget belonging to any other page can ever belong to this group, since no page’s namespace is accessible from any other page.

Widget Specs

• Chart Widgets
  • Format
  • Fields
  • Special data types
• Doc Widgets
  • Format
  • Fields