Link lists and references are an important concept in Scrivito. Technically, there are link, linklist, reference, and referencelist attribute types next to other attribute types such as string, html, date, etc. You can add as many of these attributes as needed to any object class so that the instances of such an object class, the CMS objects, are equipped with these link lists or references, respectively.

A link list may contain any number of links. As with links contained in the body or in an html attribute of a CMS object, these links may point to CMS objects or external content. However, they are not rendered automatically when the page or page component represented by the CMS object is rendered. Link lists serve a special purpose, their semantics is given to them by an application-specific use case. Thus, code must be written to make a link list work as it is supposed to.

Link lists are link containers. They are suitable for implementing use cases in which a page or page component needs to handle external resources, or present any number of links to the visitor. If, for example, an article page is to render a list of links pointing to other topically related articles, this list is best represented as a linklist attribute. This is a flexible solution for maintaining external links or a combination of external and internal links.

Assuming that there is a dedicated ArticlePage object class containing a related_topics link list attribute, its view could render the links it contains as follows:

<ul>
  <% @obj.related_topics.each do |link| %>
    <li>
      <%= link_to(link.display_title, scrivito_path(link)) %>
    </li>
  <% end %>
</ul>

Every link in a linklist attribute is represented as a Link object with several methods, e.g. title, url, or destination_object, supporting even sophisticated use cases around linking. For details, please refer to the corresponding API documentation.

As opposed to links, references are meant to merely point to other CMS objects, without carrying the semantics of links with them. While the contents of a reference attribute is a single CMS object, a referencelist attribute contains an array of any number of target objects. This is handy for providing access to all kinds of internal resources relevant to the CMS object being rendered.

For rendering an avatar, for example, its location can be defined by means of a reference attribute, e.g. author_avatar_image, pointing to the image:

<%= scrivito_image_tag @obj, :author_avatar_image %>

Instead of a reference type attribute, you can also use a link or linklist attribute.

When changing a link or linklist attribute of an existing CMS object, this object needs to be updated to persist the new attribute value. In fact, this holds true for all changes to any type of attribute. When creating a CMS object, the attribute values passed to it are stored automatically, of course. Examples:

As can be seen above, a link list is represented as an array of links, a reference list as an arrays of CMS objects.

For the purpose of generating sorted navigation lists, the pages subordinate to a page (the child pages) can be sorted using a custom referencelist attribute named child_order (see Making Navigations Sortable for details):

Since every link list is an array of links, you can extend them, manipulate their items individually, sort them, etc. Don't forget to update the CMS object containing the link list afterwards: