When Structure101g reads in a data file, it creates an internal structural data model. As well as containing the concrete items explicitly declared in the data file, this model also needs to work with four different types of virtual item:
All four are (at least theoretically) present in all Structure101g models. The semantics of these virtual items are pre-defined - you cannot change them. However, you can influence the icons used to represent these virtual types, and the textual names used for the types in any outputters (e.g. Export features).
The root type, as you would expect, corresponds to the single node (per model) at the root of the internal (hierarchical) data structure.
The notion of folders in Structure101g has already been hinted at. Basically, a Structure101g folder can be thought of as a virtual container item, the existence of which can be automatically inferred from the fully qualified names of the modules. In some (especially file-based) domains, the word "folder" may be a perfectly good term to describe this notion. In others, it may make more sense to map the notion of folder to some other term more relevant to that domain (e.g. "namespace", "package, ...).
The module type refers to the superset of item types that may occur at the module (outermost item) level.
Finally, as its name suggests, the bundle type refers to some arbitrary collection of more than one thing. These can arise in Structure101g architecture diagrams, where a user manually edits a cell pattern to apply to multiple items.
All metadata files should include at least a minimalist declaration as follows.
<virtual-types>
<virtual-type nature="root"/>
<virtual-type nature="folder"/>
<virtual-type nature="module"/>
<virtual-type nature="bundle"/>
</virtual-types>
With this declaration in place, the flavor pack should include icon files called root.gif, folder.gif, module.gif and bundle.gif.
The following is identical except that it specifies a different icon to use for the root.
<virtual-types>
<virtual-type nature="root" icon="myrooticon.jpg"/>
<virtual-type nature="folder"/>
<virtual-type nature="module"/>
<virtual-type nature="bundle"/>
</virtual-types>
Where appropriate, it is good practice to define the terminology mappings. For example, if we were modeling logical Java, the following declaration would be more intuitive.
<virtual-types>
<virtual-type nature="root"/>
<virtual-type nature="folder" name="package"/>
<virtual-type nature="module" name="class"/>
<virtual-type nature="bundle"/>
</virtual-types>
Note that these changes mean that Structure101g will now expect icon files package.gif and class.gif (rather than folder.gif and module.gif). Again, this default can be overriden with an explicit icon assignment.
<virtual-type nature="folder" name="package" icon="mypackage.jpg"/>
Typically, where only a single module-type is defined (e.g. htmlfile), it will make most sense to re-use this type name in the module nature declaration.
<virtual-type nature="module" name="htmlfile"/>
Where multiple module-types are defined, you should specify something that captures the commonality of the specific types. For example, if we specified module-types "hfile" and "cfile" for a C domain, we might specify the following for the virtual module declaration.
<virtual-type nature="module" name="file" icon="file.gif" />
Understanding root and folders
As indicated above, folders are automatically inferred from the fully-qualified names of modules.
For example, given 2 modules a.b.c and a.b.d (and a separator char of '.'), Structure101g would infer that there is an implict folder a that contains an implict folder b that contains the 2 modules c and d.
In this particular case, Structure101g would further infer that folder a is structurally not very interesting, because it only contains a single (virtual) child. It would therefore optimize this hierarchy (for viewing purposes) by collapsing a and b into a single folder node a.b.
Conversely, this collapsing would not take place if say there were an additional module called a.e.
The notion of structurally interesting also impacts the choice of which node to display as the effective root. This is defined as the first node down in the tree that has more than a single child. In the first example, the effective root would be the folder a.b, while in the second it would be the folder a.
Whenever the effective root is a folder, the actual root node (though present in the internal data model) is never visible to end users. Pursuing the above example, this would cease to be the case if we added e.g. a new module called f.g.