PageSeeder objects

PageSeeder primitives are specialized into objects by attributes (@type or @role), or context (group, document, etc.). Of these two components, the primitives are very stable

  • The implementation has barely changed in 20 years,
  • The original design was based on W3C XLink and earlier standards.

This is not the case for the PageSeeder objects. As the computing environment, particularly the Web, has evolved, so have the objects. It is the flexibility of the primitives -to-objects specialization that validates the link-based architecture.

PageSeeder implementations that have been in continual use since the year 2000 support this argument. Groups with thousands of documents and comments are currently running on the latest PageSeeder version without ever needing the original data to be restructured. 

URI objects

URIs are specialized by their type (i.e. media type), which represents objects such as:

  • PSML (PageSeeder Markup Language) documents – which has a type of ‘application/vnd.pagaseeder.psml+xml
    • replaces the predecessor to PSML, known as Standard format – which had a type of 'text/xml'.
  • Folder – type is ‘folder
  • Or objects of other types, such as:
    • images – when type is image/*
    • videos – when type is video/*
    • documents – when type is PDF documents, docx files, etc.
  • URL external to the PageSeeder server. 

uri_objects.png

Documents and folders

PSML documents

These are documents created using the PSML format. Because this format is native to PageSeeder, PSML documents can be edited, versioned, validated, linked to, annotated and so on.

Some of this functionality is available to other formats but no other document type has the complete support of PSML.

Binary files

For files such as images and PDF documents, PageSeeder can support custom metadata fields. For an example of this capability, see – How to use metadata to substitute lo-res with hi-res images.

Folders

For common applications, the folder object provides hierarchical or typed grouping for documents or files. It is further specialized when used to share documents.

Locator objects

Locator objects are specialized by context:

  • Group Locator
    • Default
  • Document Locators
    • Default
    • Fragments
  • Sections are containers for fragments

locator_objects.png

Locators and fragments

All documents have a default locator

#default

Folders do not have a default locator

In practice, fragments are immutable

Fragment is synonymous with Locator in the context of a document editing and for linking

Sections and fragments

In PSML documents:

  • Sections are predefined containers for fragments set in the original document or the document template
  • Section fragments are related to a section
  • Section fragments generally inherit properties of the section and are positioned in relation to the section

Other type of documents only have document fragments. There is no concept of sections for non-PSML document.

All document fragments have semantics such as Labels.

Sections and fragments: example 1

In the example below, document is a video and the fragments are created to for each particular points in time inside the video.

Note

Any time resolution could be used, PageSeeder only requires a unique identifier. It would also be possible to use more precise times, ranges or include coordinates in the video frame at that instant.

fragments_example_1.png

Sections and fragments: example 2

In this example, the document used is in PSML format.

Sections are fragment containers, they correspond directly to the sections found in the physical form of the document, that is the XML file in the file system. PageSeeder refers to this file to determine the existence and ordering of the sections because sections do not have a natural ordering.

In this case, section '#title' appears before '#metadata' and '#content'.

Warning!

The original file determines the sections in a document, but they could possibly be replaced when the document is uploaded. If the section IDs in the uploaded document do not match, existing data for the removed sections may be lost. Any related fragment will be hidden from view but will remain stored in the database.

Section fragments are locators conceptually attached to a section. The order of fragments related to a section is stored in the PageSeeder database and may not be their numerical order.

fragments_example_2.png

XLink objects

XLinks are specialized by both their role and their status.

The most common types of XLinks are:

  • Comments
  • Edits
  • Notes
  • Version
  • Workflow
  • XRefs

Other types used for:

  • Archived XLinks
  • Attachments & uploads
  • Deleted content

xlink_objects.png

Comments and discussion

Comments can be attached via a Locator to

  • A group (on the general discussion URI)
  • A document
  • A document fragment

Comments can also be attached to another comment. A sequence of comments is a discussion. A discussion can be changed into a task by setting a status to a comment. Discussions are linear and ordered chronologically.

The title generally remains unchanged.

comments.png

Tasks

A task is a discussion where at least one comment has a status

A task update is a comment which has a status, assignment, priority or due date in a task.

Tasks can be attached to documents or be general, just like any discussion. In fact, a discussion is turned into a task by simply specifying a status.

Each subsequent comment can change the task status, priority or reassign

  • The role of the member affects who can do what

tasks.png

Document edits

Documents edits only apply to Locators within a PageSeeder PSML document. All edits have content.

A sequence of edits is the edit history. This can be used to track changes.

The content of new edits replace previous ones, the content of a fragment is that of the last edit in the sequence.

History of changes is preserved by the edit sequence. Changes can be computed by comparing individual edits.

edits.png

Edit notes

Edit notes are attached to specific document edits. They are used for document review and audit.

Versions

Document versions are attached to a document via its default Locator

Each document version retains the state of document so that the document version can be exported or published.

Workflows

A workflow is a special type of task that uses document status values (e.g. Initiated, In Progress, Complete, Approved, Terminated).

There can only be one Workflow per document and the status of the document is the workflow status.

It can have a current priority, due date and assigned to like other tasks and can use comment labels.

Workflows can be created on multiple documents at the same time but they are independent from each other.

XRefs

XRefs (cross references) link two document fragments.

They are directed and they can be bidirectional so that each end of the link know of each other.

They are persistent. Because links operate between Locators, they will remain even if the documents move or are archived.

Other XLink types

  • Archived XLinks
    • When XLinks are no longer needed or relevant, they are archived instead of being deleted
  • File XLinks are created every time a document is:
    • Uploaded
    • Created
    • Attached
  • When a fragment is removed, a special XLink type is used to hide it from view.

Group objects

Groups are specialized by their flags and their name.

groups.png

Projects

A Project is a logical container for groups and an important configuration point, it defines:

  • Labels
  • Templates
  • Configuration
  • Project properties
  • Document types

Subprojects

Projects can also be organized into a hierarchy using subprojects. This is usually done when groups need to be organized in a more complex structure for semantic reasons.

Groups

A Group is used as working space

It inherit the following from it parent project:

  • Labels
  • Template
  • Configuration

But it can also defines its own:

  • Properties
  • Documents, tasks and comments

Subgroups

A group can have one or more subgroups but they are NOT hierarchical. Any group can be made a subgroup of another group (called the supergroup) and they are not organized in a hierarchy.

The only effect is that members of a subgroup will appear as members of the supergroup and have permission/notification settings as if they were direct members.

For example if there are 3 groups:

  • glossary
  • book1
  • book2

and glossary has subgroups with the following settings:

  • book1: Notification = Inherit, Role = Reviewer
  • book2: Notification = Inherit, Role = Reviewer

This means that the members of book1 will have access to glossary as reviewers and with notification the same as in book1. The same is true for members of book2.

This example is taken from an online demo which can be accessed here .

Next...

With primitives and objects in mind, let see how to turn a set of Requirements into a PageSeeder model.

Created on , last edited on