Maintaining CMS Object Classes with Migrations

Maintaining CMS Object Classes with Migrations

This article refers to Scrivito SDK versions up to 0.50. From version 0.60 onwards, object classes are maintained solely as Ruby models. The CMS is no longer aware of object classes, leaving it to the Ruby models to specify their attributes.

As a side benefit, migrations for maintaining object classes in the CMS are not required. Simply have the models generated, then equip them with the desired attributes.

Some of the generators the SDK provides create migration files like the ones given here as examples. For details regarding the Scrivito SDK Migrations API, please refer to the Ruby SDK documentation on object classes.

Creating an object class

In the following example, we will define an object class named ContentPage. This object class should have a title attribute that holds the page title, and a body attribute for storing the HTML page content. After creating this object class, all objects based on it have these attributes, and individual values can be assigned to them.

$ rails g scrivito:migration create_content_page 

This creates a file, scrivito/migrate/*_create_content_page.rb. Open the file in your text editor and replace the example code with the actual migration code:

Running this migration with rake scrivito:migrate creates the object class in the rtc working copy. Finally, publish this working copy using rake scrivito:migrate:publish.

Adding an attribute to an object class

In this example, the name of the attribute to be added to an object class is new_html, and its type is html. Attributes are local to individual object classes, i.e. all object classes can have their own new_html attribute of any type. The new attribute will be added to ContentPage only.

$ rails g scrivito:migration add_new_html_to_content_page

Open the generated migration file in your text editor and replace the example code in the up method with the actual migration code.

After running this migration, the object class has got the new attribute. Finally, publish the rtc working copy.

Removing an attribute from an object class

This removes the attribute named my_obsolete_attribute from the ContentPage object class. Since attributes are local to an object class, the attribute will only be removed from the specified object class.

Renaming an attribute

Renaming an attribute consists of three steps:

  1. Add the attribute using a new attribute name.
  2. Copy all attribute values from the old attribute of every object of the object class to the new attribute.
  3. Remove the old attribute.


$ rails g scrivito:migration rename_content_page_description_to_summary

This example assumes that you already have a description attribute in the ContentPage object class. It adds the new summary attribute to the object class, then copies description from every content page to the new summary attribute. To do so, the migration uses the search engine facility to iterate over all these pages.

The order clause ensures that we get a deterministic search result over multiple subsequently executed searches if we have more than batch_size pages in the CMS.

Changing the type of an attribute

Changing the type of an attribute consists of the following steps:

  1. Collect the current attribute values, and migrate them on-the-fly in memory.
  2. Change the type of the attribute.
  3. Store the collected data back to the attribute.

As an example, we want to change the type of the source attribute in ImageWidgets from linklist to reference.

Creating a CMS object

$ rails g scrivito:migration create_products_page

If an object class such as ContentPage already exists, you can create objects based on this class from within your migrations.

_path and _obj_class are mandatory fields. Other attributes such as title in the example above may be specified as well.

Deleting an object

$ rails g scrivito:migration delete_obsolete_products_page

Changing the object class of an object

Suppose you want to introduce a new object class and need to assign it to already existing objects. In the example below, the object with the path /websites/en/contentpage presently has the ContentPage object class. Since the object now needs to function differently, as a special navigation group node, an appropriate new object class, NavigationGroup in this case, needs to be assigned to it: