Controls: show



[log in] or [register] to leave a comment for this document.

Go to: all documents

Options: show



[home] [about] [help]


[profiles] [forum]


Organizing Content

14-Nov-2012 [18]

• It's all about lists

Part of Documentation


Muster Wiki is all about lists. Particularly lists called Topics.

There are two kinds of lists.

  • Container lists (Topics and Resource Folders) are put together by website Custodians. These, particularly Topics, are interesting lists because they're put together by people for a purpose. The items in such lists can be a collection of related items, or they can be put in a particular order to tell a story, or lead people through a complex topic.
  • System lists on the other hand, one for each record type, are not all that interesting, but are available for administration and searching. These include content record types -- documents, blog posts, pictures, document files, document extracts, external links, widgets -- and container record types -- topics and folders. Blogs as containers are a special case, as they organize themselves, although blog posts can be added to topics as well. Also there's a database list to search all items (other than pictures and blogs, but including blog posts), and a library list to search all external resources (other than pictures). Treetops and folder treetops give the top-most topic and folder containers, respectively, so these lists are useful as overviews for website readers.


To make the most of this system, here are a few guidelines (but not hard and fast rules) that seem to be helpful:

  • All content records should be assigned to at least one topic or folder (blog entries are automatically assigned to their blog)
  • All topic and folder records should be either a treetop or should be assigned to at least one topic or folder as appropriate (topic to topic, folder to topic or folder)
  • Records can (and often should) be assigned to more than one topic or folder. This helps to clarify the place of the record in the scheme of things.
  • Records should usually be assigned to no more than four or five containers (more usually means a fuzzy understanding of the topics involved)
  • Organize all resource records (pictures, document files, document extracts, external links, widgets) into resource folders
  • Add external resources to topics through resource folders. For example organize pictures into picture albums, and then add those thematic albums to topics
  • Allow topics to evolve. It's not that hard to move things around

A topic assigned to a topic is a sub-topic. A folder assigned to a topic or folder is a sub-folder.

Put some thought into your topic treetops, the highest level of topics. This list represents the abstract overview of what you're trying to do, and should mean something to your readers. But let this evolve as well.

When a record is assigned to multiple containers, it's not actually copied. It's the same record everywhere, so that a change to that record shows up everywhere.

Adding Records to Containers

Adding records to topics

To make a topic a treetop, check its treetop property in edit mode.

For editing records, see Creating and Maintaining Content.

To add any record to a Topic, click on that record's Containers tab in admin view. In a separate browser tab, navigate to the container of choice for the record, and copy its record number. Go back to the edit record browser tab, paste the target container's record number into the field beside the Add button, and hit Add.

Just after creating a record is usually a good time to add it to a topic or folder.


Copy the record number of the record you want to add to a container. Navigate to that container, go into admin view, click on the Contents tab, paste the subject record number into the field beside the Add button, and hit Add.

In other words, you can add the topic to the record or the record to the topic (only one or the other, both is not required).

Adding records to folders

Adding records to folders is exactly the same as adding records to topics.

Adding Attachments

Adding attachments is very similar to adding contents. Find the record number you want to attach. Navigate to the record it is being attached to. Go into admin view. Click on the Attachments tab. Paste the record number into the field beside the Add button. Hit the Add button.

Records that have attachments automatically show an Attachments tab in display view.

The specific usage and meanings of attachments is an editorial policy matter for each website. Attachments are usually used to provide access to background or related documents.

Removing Items from Lists

To remove an item from a list, go the the administrative view of the list (admin mode - the Contents, Containers, or Attachments tab as appropriate), check the items you want to remove, and click on the Remove button.

Removing items never deletes them.

Ordering Lists

All container (content) and attachment lists are ordered by Title Ascending by default. The default order of content (but not attachments) of each topic or folder can be changed by editing the Sort by selections of the container record (in edit mode). Defaults can be set to order content by Title or Date, and Ascending or Descending.

Specific ordering preempts default ordering. To specifically order items, go to the Contents tab of the container for which you want to order content. Then fill in the Order column with numbers indicating the order in which you want the items to be sorted. Then hit the Save button.

You don't have to order all items. Specifically ordered items will be sorted above un-ordered items, and the un-ordered items will be sorted according to the default order.

Follow a similar process for ordering attachments.

Duplicate numbers are acceptable. This can be used as a way of sorting groups of items. Items that have identical order numbers will be sorted within that order number by the default order.

By default, the order number entered appears as a prefix to the title of the ordered item. If you want alternate text to be prefixed to the title instead, add that text to the Order Text field (for example i,ii,iii instead of 1,2,3). You can also use the Order Text field to indicate a name for a group, if a number of items are given the same order number.

You can also place a line above or below a particular item by checking the appropriate box for that item, as a further visual aid to readers.

To move an item in a numbered list, change its number to the position that you want to move the item to (even if that number is therefore duplicated). Hit Save. Then hit Auto Renumber. This will regenerate existing order numbers such that they will begin with 1 and increment by 1 for the entire list (but only of numbered items), thus resolving the order number duplication caused by moving the record. Finally, examine if the newly moved record is in the correct position in relation to the duplicated record number that it was moved to. If not, just swap the order numbers of the two items that were duplicated before auto-renumbering. (This will make sense when you actually try it).

Annotating Lists

Container lists can be annotated specifically for that container. Similarly attachment lists can be annotated specifically for the record to which the list is attached. Annotations appear above the Title in list items, and at the bottom of the Navigation block above a full page view of the item. Annotations are prefixed by the system with the text "Guide:".

Once a record is removed from a list, the annotation for that item for that list is lost.

To annotate list items, go to the administrative view of the list you wish to annotate (in admin view: Contents tab of containers, or Attachments tab of any record). Click on (next to "switch to") narrative view. Fill in any Narrative fields for list items you wish to annotate (max about 260 characters). Hit Save.

Cover Pages

The default display view of container records is the Contents page, namely the list of items that have been allocated to it.

However if you fill in the Cover page field of the container record, then in display view a Cover page tab appears automatically before the Contents tab. Think of this as a description of the contents stapled to the front of a file folder. The Cover page can be as simple or elaborate as you wish - it is a wiki markup field. Generally we have found that relatively short cover pages are most effective for most situations.

The Home Page

The Home Page is a special case. It takes a designated Topic record with (optional) Document or Topic content items, and transfers the data to the home page as described in Configuring the Home Page and Sidebars.

Selecting Layouts for Lists

Container records allow content item layouts to be set in their Default Layout field. Currently, the choices are Planks, Large icons, and Gallery. Essentially Planks are 1-across, Gallery is 2-across, and Large icons are 3-across. Large icons show less information than the other two.

The layout is set for all content items of a container, and there is no over-ride for individual content records.

If the content records have Picture icons set, then those pictures are displayed at the size appropriate to the layout ("small" for Large icons, "smallest" for Planks, and "medium" for Gallery).

Gallery layout is often ideal for photo albums (folder records with nothing but picture contents). Large icons layout is often ideal for lists that will appear on the home page, as they look like a tiled menu.

Bulk Processing - Toolbars for Administrators

Administrators have a toolbar available to them that allows for bulk processing of additions and moves of content records from one place to another, and removals of items from containers.

The toolbar is made available by clicking on actions near the top left of all lists (only visible with the appropriate permissions). System lists have Add and Publish options, whereas container lists additionally have Remove and Move options. Move means to both Add items to the target container and Remove items from the current container.

When the toolbar is selected, checkboxes appear beside all visible items in the current list. Items that are checked by the administrator are those that are acted upon based on the action button chosen. For Add and Move the Administrator must enter the record number of the target container in the input field beside the button for the operation selected.

From the Reader's Viewpoint

The reader sees the result of all this organizing work in the "Part of" lists that form part of the heading of every record in the database. By observing this list, the user can see where the record has been "filed", and therefore gets a good idea of the semantics of the current record, as well as options for further exploration. Attachments, Cover pages, and Annotations provide additional contextual information to the reader.