Previous
4.1.5 Document variant properties
4.1.5.1 Versions
A document consists of versioned and non-versioned data. Versioned data means that each time the document is saved (and some of the versioned aspects of the document changed), a new version will be stored, so that the older state of the data can still be viewed afterwards.
It hence provides a history of who made what changes at what time. It also allows to work on newer versions of a document while an older version stays the live version, as explained in version state.
4.1.5.2 Versioned Content
The versioned content of a document consists of the following:
- the document name
- the parts
- the fields
- the links
So if any changes are made to any of these, and the document is stored, a new version is created.
4.1.5.2.1 Version ID
Each version has an ID, which is simply a numeric sequence number: the first version has number 1, the next number 2, and so on.
4.1.5.2.2 Document Name
The name of a document is required (it cannot be empty). The name is not required to be unique. Thus there can be multiple documents with the same name. The ID of the document is its unique identification.
The name is usually rendered as the title of the document.
4.1.5.2.3 Parts
A part contains arbitrary binary data. "Binary data" simply means that it can be any sort of information, such as plain text, XML or HTML, an image, a PDF or OpenOffice document.
In contrast with many repositories or file systems, a Daisy document can contain multiple parts. This allows to store different types of data in one document (e.g. text and an image), and makes these parts separately retrievable.
For example, one could have a document with a part containing an abstract and a part containing the main text. It is then very easy and efficient to show a page with the abstracts of a set of document.
As another example, a document for an image could contain a part with the rendered image (e.g. as PNG), a part with a thumbnail image and a part with the source image file (e.g. a PhotoShop or SVG file).
The parts that can be added to a document are controlled by its document type.
Each part:
- is associated with a
- has some binary data. There are no specific restrictions on the size of the data, Daisy handles everything using streams.
- has a mime-type, describing the sort of data stored in it.
- optionally has a file name, this file name can be used as default file name when the content of the part is saved (downloaded) in a file.
4.1.5.2.4 Fields
Fields contain simple information of a certain data type (string, date, decimal, ...). Depending on how you look at it, fields could be metadata about the data stored in the parts, or can be data by themselves.
One of the data types supported for fields is link, which allows the
field to contain a link to another Daisy document. Link-type fields are useful
for defining structured links (associations) between documents. For example, you
could have documents describing wines, and other documents describing regions.
Using a link-type field you can connect a wine to a region. By having this
association in a field, it is easy to perform searches such as all wines
associated with a certain region. The
Fields can be multi-valued. The order of the values in a multi-value field is maintained. The same value can appear more than once.
A field can be hierarchical, meaning that its value represents a hierarchical path. A field can be multi-value and hierarchical at the same time.
The fields that can be added to a certain document are specified by its document type.
Each field:
- is associated with a
- has a value.
4.1.5.2.5 Links
A document can contain links in the content of parts (for example, an <a> element in HTML) or in link-type fields. Next to this a document can have a number of so-called out-of-line links. These are links stored separately from the content. Each link consists of a title and a target (some URL). These links are usually rendered at the bottom of a page in as a bulleted list.
Out-of-line links are useful in case you want to link to related documents (or any URL) and either don't want or can't (e.g. in case of non-HTML content) link to them from the content of a part.
4.1.5.2.6 Version state & the live version
Each version can have a state indicating whether it is a draft version (i.e.
you started editing the document but are not finished yet, in other words the
changes should not yet be published), or a publishable version. The most recent
version having the state 'publish' becomes the live version. The live
version is the version that is typically shown by default to the user. It is
also the version whose data is indexed in the full-text index, and whose
properties are used by default when querying. The
4.1.5.3 Non-versioned properties
4.1.5.3.1 Document type
Each document is associated with a document type, describing the parts and
fields the document can contain. See
4.1.5.3.2 Collections and collection membership
Collections are sets of documents. A document can belong to zero, one or more collections, thus collections can overlap. A collection is simply a way to combine some documents in order to do something with them or treat them in some special way. In other words, they are a sort of built-in (always present) metadata to identify a set of documents.
Collections themselves can be created or deleted only by Administrators (in
the Daisy Wiki, this is done in the administration interface). Deleting a
collection does not delete the documents in it. You can limit who can put
documents in a collection by
4.1.5.3.3 Custom fields
Custom fields are arbitrary name-value pairs assigned to a document. The name and value are both strings. In contrast with the earlier-mentioned fields that are part of the document type, these fields are non-versioned. This makes it possible to stick tags to documents without causing a new version to be created, and without formally defining a field type.
4.1.5.3.4 Private
A document marked as private can only be read (and written) by its owner.
While the global access control system of Daisy makes it easy to centrally handle access control for sets of documents, sometimes it could be useful to simply say "I want nobody else to see this (for now)". This can be done by enabling the private flag. The document will then not be accessible for others, and also won't turn up in search results done by others. The private flag can be set on or off at any time, by the owner or by an Administrator.
There is however one big exception: Administrators can always access all documents, and thus will be able to read your "private" documents. The content is not encrypted.
4.1.5.3.5 Retired
If a document variant is no longer needed, because its content is outdated, replaced by others, or whatever, you can mark the document variant as retired. This makes the document variant virtually deleted. It won't show up in search results anymore.
The retired flag can be set on or off at any time, retiring is not a one-time operation.
4.1.5.3.6 Lock
A lock can be taken on a document variant to make sure nobody else edits the document variant while you're working on it.
Daisy automatically performs so-called optimistic locking, this means that if person A starts editing the document, and then person B starts editing the document, and then person A saves the document, and then person B tries to save the document, this last operation will fail because the document has changed since the time person B loaded it. This mechanism is always enabled, it is not needed to take an explicit lock.
A lock can then be taken to make others aware that you are editing the document. A lock can be of two types: an exclusive lock or a warn lock. An exclusive lock is pretty much as its name implies: it is a lock exclusively for the user who requested it, and avoids that any one else will be able to save the document until you release the lock. A warn lock isn't really a lock, it is just an informational mechanism to let others know that someone else also started to edit the document, but it doesn't enforce anything. Anyone else can still at any time save the document or replace the lock with their own.
A lock can optionally have a certain duration, if the duration is expired, the lock is automatically removed.
For example, the Daisy Wiki application by default uses exclusive locks with a duration of 15 minutes, and automatically extends them as longs as the user continues editing.
A lock can be removed either by the person who created it, or by an Administrator.
4.1.5.3.7 Last Modified and Last Modifier
Each time a document is saved, the user performing the save operation is stored as the last modifier, and the date and time of the save operation as the "last modified" timestamp. This will often fall together with the Created/Creator fields of the last version, but not necessarily so: if only non-versioned properties are changed, no new version will be created.