Documents
The Concept of a Document
Everyone knows what a document is. You hold it in your hand, read it, print it... But beware, in Liquid Site the concept of a document is a little bit different from what you're probably used to.
A document in Liquid Site is little more than a set of document property values. That is, the content of a document is whatever values it sets for the document properties defined in the section. In a way, a document can be compared to a filled-out form, though some of the fields will probably contain longer texts.
Most documents in this model will have a number of smaller property values, and then finally one property value containing the full text of the document. But the document model also lends itself to storing plain data or list entries, such as items in a todo-list, products in a web shop or similar.
Editing Documents
Documents are created and edited in the Administration Application by choosing the "Add" or "Edit" buttons respectively. Both eventually lead to the same document editing form, except for minor differences. In the figure below the document being edited has the same properties as in figure 2 in the previous section.
Figure 1. Editing a document. The document properties from the section show up as normal fields in the form, in this case the "Title", "Author" and "Text" fields. The editing form also allows attaching files to the document and changing the document name and parent section.
Just as the sections, the document editing forms contain a Name field. It identifies the document inside the section and can be used to retrieve the document from web pages. When mapping documents to a web site with a Translator, the document name will be used as a folder name inside the URLs. It is desireable to choose document names that are meaningful and convey information about their content, but they should also be relatively short and written using only the English alphabet and numbers. As a rule of thumb, documents should be named with all lower-case letters.
Other fields that are always available when editing documents are the parent section, the attached files, and the revision comment. By changing the Section, a document can be moved around in the content tree. Doing so may break pages and/or URLs depending on the structure so it should be used with care. The Files field allows attaching files to the document, which further described below. Finally, a revision Comment must be specified when modifying a document, as for all other objects.
When editing documents, fields for all the document properties from the parent section are also displayed. These fields are displayed with the title and description from the section, and the actual input control depends on the type of the document property. In the figure above, the controls for plain text and tagged text are shown.
Attaching Files & Images
Documents can have any number of files or images attached. This makes it possible to embed links and images in the document texts in an easy way. It also means that these resources can be managed together with the document in terms of permissions, location in the content tree, etc.
The attached files are stored separately from the document but the document editing form contains a simple way to attach new files. The figure below shows the part of the document editing form that allows attaching new files. Note that the file must first be selected (using the "Browse.." button) before the "Add" button can be used.
Figure 2. Attaching a file to a document. The previously attached files are shown along with their size and MIME types. To add a new file, it should first be selected with the "Browse..." button and then added with the "Add" button.
Attached files are seen in the content view under the document, as if it was a folder containing the files. When using a Translator the files are present in the virtual document folder, making it possible to link to them using their names directly without any path. See the figure below for an example of how attached files can look in the content tree.
Figure 3. Attached files in the content tree. The files are attached to a document, showing the document as the parent object to the files.