Migrating from Ripple 1.x

Background

Ripple 2 is a complete rewrite of both the design system and the Nuxt modules used to create SDP sites with it. It is a breaking change with the processes used to create sites and functionality used in Ripple 1. This was required due to the following reasons:

• Latest versions of Vue and Nuxt 3 introducing breaking changes
• Deprecation of IE11 support allowing us to support modern browser features
• Opportunity to adopt best practices such as Typescript and modern CSS
• Build up of technical and design debt
• Improvements to the design allowing better theming and accessibility

Due to breaking changes between versions 2 and 3 of both Vue and Nuxt there is no automated way to upgrade Ripple components and sites. Custom functionality built on Ripple 1 will need to be rewritten to use Ripple 2 API’s and design.

Migrating your site

If your site is supported by the SDP team for upgrades, the initial site upgrade will be handled by the SDP team. The process will be as follows:

• a new empty V2 branch will be created in the site repository
• a fresh install of Ripple 2 will be added to the site
• all required environment variables will be added to the project to connect the site to the Tide content backend
• the V2 branch will be setup to be served from behind the Section.io CDN

The migration of the following will be out of scope for sites without an MoU for SDP support:

• Custom content types
• Custom user facing components
• Custom pages
• Extensive theme customisation outside of those documented in the theming guide

Migrating features from Ripple 1.x

Please review the following concepts before proceeding:

• Content types
• API mapping
• Dynamic components

Content types

Content types in Tide allow for defining custom fields that can be returned via the Drupal JSON API. Because SDP sites are headless, we need to tell Ripple how to render each custom content type on the front end.

In Ripple 1.x, each content type was added through the convention of adding a folder named tide and each content type as a subfolder. See Ripple 1 example. The mapping of the tide API response was done through tide.config.js. The JSON API response was returned in its entirety and mapping the Drupal fields to Ripple components was done through the Page component.

In Ripple 2.x we move the mapping of data to the Nuxt server layer. This allows us to only return the necessary data needed to the end user, reducing the JSON payload from Drupal.

For more information on creating new content types see the guide on creating content types

Dynamic components

Tide CMS makes use of Drupal paragraphs to structure content types to allow content creators flexibility when composing content. Creating new paragraph types that can be reused for the landing page content or across others is a common customisation task.

In Ripple 1, new paragraph support was added through custom mappings See Ripple 1

In Ripple 2, we need to add similar support - See Guide to creating dynamic components

Search listing pages

This feature is still in Beta, please see the feature proposal for more information.

Listing pages are pages that contain dynamic lists of links to other pages. These are typically used to generate index pages when there are large amounts of similar items. See https://www.vic.gov.au/grants, https://www.vic.gov.au/victorian-honour-roll-of-women for example.

In Ripple 1 there was no dedicated content type for creating listing pages and hence these pages were usually created as static pages in the frontend.

In Ripple 2 we intend to move to a standard content type that allows configuring the search experience from the backend. Please see the feature proposal for more info.