The OpenSquiggly Paradigm
Introduction
In previous chapters we’ve discussed practical and pragmatic operational descriptions of how to use OpenSquiggly.
In this chapter, we delve into the less tangible, theortical aspects of the OpenSquiggly paradigm. OpenSquiggly is driven by a unified theory of content organization. This paradigm provides a highly flexible framework for organizing content that can accommodate a large variety of real world scenarios.
As we have emphasized previously, OpenSquiggly is heavily informed by the target market it hopes to serve, namely, software development teams, and by the perceived use cases needed by those users. However, at its heart, OpenSquiggly is more than that. In this chapter we discuss the theory of the OpenSquiggly paradigm.
Pages as the Primary Unit of Content
All content viewed with OpenSquiggly is done through the use of pages.
Each page contains a list of table of content entries (TocEntries) and a list of snippets. The manner by which the TocEntries and snippets are retrieved and/or generated is determined by the type of the page. In some cases, the TocEntries and snippets are physical entities, stored and retrieved in the database, but in other cases, they are virtual entities that are dynamically generated.
There are three types of pages:
- Regular Topic Pages
- Mapped Topic Pages (most of the time referred to simply as “Mapped Pages”)
- Virtual Pages
Regular Topic Pages
Regular topic pages are physical entities that are stored as records in the TopicPages collection in the database. These topic pages contain a list of TocEntries that refer to other pages, and a list of snippets that comprise the content of the page.
Snippets are self-contained, generally small, pieces of content that can be placed on a page. When a page is rendered, the system reads all the snippets that belong to the page, and renders them vertically down the page surface from top to bottom.
In the case of regular topic pages, both the list of TocEntries and the list of snippets are physically stored as entities in the database.
The page structure in OpenSquiggly is not strictly hierarchical as one might be familiar with in an operating system file system. Pages can be referred to by multiple pages, and therefore existing at multiple points within the user’s navigator.
Back references to pages are stored in the page’s ReferencedBy array.
Mapped Topic Pages
Mapped topic pages are also physical entities that are also stored as records in the TopicPages collection.
Mapped pages reference a Mount Point and a starting path within that mount point.
Unlike regular topic pages, the user does not have direct control over the table of contents entries for mapped pages. Instead the table of contents for the page are dynamically generated by reading the items with the directory of the mount point using the starting path as the folder.
The list of snippets is also generated dynamically for mapped pages. When the system request’s the snippets for a mapped page, the system reads the contents of the file at the mount point and the starting path, and returns a single text snippet containing that file’s contents.
Because mapped pages are physical entities, they, like regular topic pages, contain back references to the pages that reference them.
Virtual Pages
Virtual pages are non-physical entities that are not stored in the database’s TopicPages collection. They are dynamically-generated on demand when the user requests to view that page.
Virtual pages are very similar to mapped pages. As with mapped pages, virtual pages have an associated mount point and start path. As such, like mapped pages, the table of contents and list of snippets are generated dynamically by reading the directory list and file content of the file located within the mount point at the specified path.
There’s one other subtle difference between mapped pages and virtual pages regarding page title. Mapped pages have their own page title which is stored in the record in the database. Therefore the title of a mapped page might not be the same as the title of the page to which it refers. Relative pages however always get their title from the external content (either the file or folder name).
Summary of Page Types and Characteristics
| Page Type | Title | TocEntries | Has Back References | List of Snippets |
|---|---|---|---|---|
| Regular Topic Page | User Assigned | User Controlled | Yes | User Controlled |
| Mapped Page, RelativePath = folder | User Assigned | Read folder items from Mount Point @ RelativePath | Yes | Return single snippet “This is a directory” |
| Mapped Page, RelativePath = file | User Assigned | Return an empty list | Yes | Return single snippet containing file contents of Mount Point @ RelativePath |
| Virtual Page, RelativePath = folder | From Folder Name | Read folder items from Mount Point @ RelativePath | No | Return single snippet “This is a directory” |
| Virtual Page, RelativePath = file | From File Name | Return an empty list | No | Return single snippet containing file contents of Mount Point @ RelativePath |
Example
