Show Orchard case study: Migrating an Orchard 1 DotNest site to Orchard Core

If you're looking to migrate an Orchard 1 website along with its content items to Orchard Core, whether on DotNest or any other Orchard Core website, the DotNest Core SDK and Orchard 1 Recipe Migration feature make the process straightforward. The Show Orchard website is a practical example of this, what we just migrated to Orchard Core.

This is a post by Márk Bartha, software engineer at Lombiq.

Introduction

Show Orchard is an Orchard CMS showcase, displaying only the best Orchard Core and Orchard 1.x powered sites from around the web. It was started by Ryan Drew Burnett, now maintained by Lombiq Technologies. When we took over the project, we already implemented it on DotNest, but at that time it was an Orchard 1 site. Since DotNest fully supports Orchard Core, it was time to migrate it. However, since a lot has changed since Orchard 1, it required us to rethink a few widgets here and there, and also we had to take care of the existing content items.

Do you want to jump right into the code? You're lucky since the Media Theme-based theme of Show Orchard is open-source and available here!

Preparations

Creating a DotNest site is most efficiently done by utilizing the DotNest Core SDK. The SDK is an actual Orchard Core website that comes equipped with a preset of features and themes that are already available on DotNest. It also activates the Media Theme feature, a tool used for hosting your theme assets and templates conveniently in the Media Library. There’s also a handy utility known as the Media Theme Deployer that takes your Liquid templates from the Views folder and assets from the wwwroot folder, packaging them into a Media Theme recipe ready for import on DotNest. We used a fork of this SDK repository for our own DotNest sites and started to develop the theme as if it were a typical Orchard Core site, always mindful of the limitations.

Content types and UI components

The websites and their data (e.g., URL, developer name and contact, image, category) are stored using the Website content type. The AutoroutePart is attached for the friendly URL, and the HtmlBodyPart is included for the optional interview with the developer. The configuration of this content type, including the category taxonomy, aligns with the Orchard 1 version of the content type.

The header and the footer are implemented directly in the Layout.liquid file for simplicity. This approach has been effective, as it hasn’t required editing for years; if it did, we would have used a widget.

The menu is implemented utilizing the Menu feature and is displayed with the Menu shape. There is a specialized Categories menu that requires additional implementation. This menu lists all the terms from the Category taxonomy, each linking to a page displaying the corresponding content items. To accomplish this, we created a new menu item content type (the stereotype being MenuItem). We then used a Query to retrieve the Category taxonomy in the menu item's shape override, displaying the term items' display link.

The Queries feature proved invaluable for other components as well. For instance, the stepper on the Website content item detail pages and the listing of related Website items both leverage this feature to fetch the necessary content items.

Automated styling compilation

The original styling of the Show Orchard site was outdated. It was built on an old version of Bootstrap, utilized LESS for styling, and the classes didn’t follow our favored BEM conventions. To modernize and enhance the styling, we shifted to Bootstrap 5 and adopted Sass for styling. Lombiq’s Orchard Base Theme served as the foundation for the theme, offering helpful shapes, including the GoogleTag shape designed specifically for Google Analytics integration. Compilation of the assets was efficiently handled by Lombiq's Node.js Extensions utility.

Migrating Orchard 1 content items to Orchard Core

The Orchard 1 Recipe Migration feature in the Helpful Extensions module proved to be extremely useful for this task. It’s a feature that adds a page to your Orchard Core website where you can import an Orchard 1 recipe, converting it into an Orchard Core recipe. However, there were a few challenges encountered. We had to create IOrchardContentConverter and IOrchardExportConverter implementations to address specific data needs. These providers are designed to extend the recipe converter logic with custom logic, either per imported content or after the whole export, to carry out additional tasks.

For us, it was essential to ensure the Category taxonomy terms were imported accurately, and their IDs were correctly assigned to the Category taxonomy fields. We also faced a task with the exported Media; in Orchard 1, Image and other content types represented a media item and had their ID referenced in Media Fields. In Orchard Core, it’s directly associated with a relative path to the media file. To address this, we used an IOrchardExportConverter to map the legacy IDs to the media paths and assign them to the new media fields. We decided against including the actual images with the media recipe step in the recipe, as it would result in a massive file size and a potential timeout. Uploading them manually to the appropriate Media Library folder wasn't a significant issue.

Conclusion

Though the Show Orchard website is simplistic in its design, migrating data and re-implementing various elements presented its own set of challenges. Nonetheless, we are pleased to announce that the site is now seamlessly operating on DotNest Core. Our next step is to transition all of our remaining DotNest sites to Core as well.

If you're considering migrating your Orchard 1 website to DotNest Core, this is an excellent time. Should you have any questions or encounter challenges don’t hesitate to reach out to us. We're always ready to bring our expertise to your unique project needs. Get in touch with us today, and let's start making your Orchard Core website even better!

No Comments

Add a Comment