DotNest Core SDK

Overview

DotNest Core SDK is a local development environment for building Media Themes to be deployed to Orchard Core CMS sites running on DotNest, the Orchard Core SaaS. Media Themes are almost full-fledged Orchard themes that you can develop as any Orchard theme, but they'll still work on DotNest.

The base of the source code on the dev branch is the same Orchard Core version that is running on DotNest as well as all the hotfixes and mods we've applied to it. On top of that, all the open-source modules are added as NuGet packages, which gives you the ability to develop your theme and run your site locally in an environment quite close to the live DotNest site.

We at Lombiq also used this SDK for the following projects:

• The new Xero4PowerBI website (see case study).
• The new Ik wil een taart website (see case study).
• The new Show Orchard website when migrating it from Orchard 1 DotNest to DotNest Core (see case study and the theme's source code).

This project, along with DotNest, is developed by Lombiq Technologies Ltd. Commercial-grade support is available through Lombiq.

Getting started

Are you unfamiliar with Orchard Core theme development and Liquid templates, or even Orchard Core in general? Then we recommend you check out the Dojo Course 3 tutorial and the official docs on Liquid and templates in Orchard Core first. Otherwise, please continue below.

We have everything documented here, but if you prefer videos, check out our DotNest Core tutorials here.

1. Go to GitHub and fork the DotNest Core SDK repository or create an empty repository and push the SDK's dev branch to it. For simplicity, we'll refer to your repository as fork from now on and assume a simple branching strategy with only one additional branch for development, but your use-case can be more complex.
2. For clarity, rename the solution file to what you prefer, e.g. AwesomeProject.DotNestSites.sln.
3. Create a project for your theme, as you'd usually do, with the Orchard code generation template, manually, or by copying Sample.Theme from the SDK. The only thing important is that you'll need to add a NuGet package reference to Lombiq.Hosting.MediaTheme to it, and in its Manifest should declare Lombiq.Hosting.MediaTheme.Bridge as a dependency. See Sample.Theme for these.
4. Reference the theme project from the root web project, DotNest.Core.SDK.Web.
5. You're now good to continue with developing your theme and deploying it to your DotNest site. Continue with the below sections.

You can see an example of a fork of this project for the website Letters from Fiume, with a Media Theme here. This demonstrates how to have a Media Theme theme project with Liquid templates and CSS, and do local development with an export of the production site, also making use of Auto Setup.

Automatic sync for your fork with Git-hg Mirror

Optionally, you can set up a mirror on Git-hg Mirror to automatically (and continuously) synchronize every commit from the original repository to your fork. This gives you an easy way to always work with same code base as what is running on DotNest.

• The "Git clone URL" should be git+https://github.com/Lombiq/DotNest-Core-SDK.git.
• The "Hg clone URL" (don't worry about "Hg") should be a similar URL pointing to your fork with some authentication details to allow Git-hg Mirror to push to your repository. You can create an access token under your GitHub settings (select full repo access) and use it as follows: git+https://0123456789abcdef0123456789abcdef:[email protected]/AwesomeDeveloper/Awesome-Project.git.
• The "Mirroring direction" should be Git to Hg.
• You'll just need the default branch, so configure "Git ref selection regex for pushes" as refs/heads/dev.
• Make sure that you never commit anything to the branches coming from the original repository, otherwise the synchronization will fail.

Note that this project uses GitHub Actions for automated builds. If you don't need these, and especially if your fork will be auto-updated with Git-hg Mirror (which pushes to your repository multiple times a minute) then you shouldn't enable GitHub Actions for the repository (since then e.g. a build will run on each Git-hg Mirror push).

Working with the repository

• Whenever you create any branches, make sure that you prefix their names so they don't collide with the ones in the SDK. For example, if the project you're working is called Awesome Project, then your development branch should be created on top of dev and name it e.g. ap-dev.
• You might also want to change the default branch of your fork to your development branch.
• In case new commits are pushed to your fork from the original repository, check the changes (e.g. new modules might be added that you also need to add to your custom solution) and merge dev to your development branch.

Theme development

• General Orchard Core theme development rules apply but with Media Theme practices and Media Theme limitations. Keep those in mind.
• You can synchronize content from your site running on DotNest by exporting it and then importing it locally. That way, you can maintain a setup recipe locally that you keep up-to-date with the production site's data, even using Auto Setup. to set up the site when you run the app. Be sure to not use the recipe locally without some modifications:
  • Remove feature enable references for all Azure-related features unless you want to use e.g. Azure Blob Storage locally too.
  • Enable your theme project and set it as the site theme (instead of Media Theme).
• Deploy your theme to your site by following the corresponding docs of Media Theme.

The Piedone/DotNest-Sites project mentioned above also demonstrates all of these.

Help us make it better!

In case you come across an Orchard Core bug during development, don't keep it to yourself: Orchard Core bugs should be reported at the official Orchard Core GitHub repository.

There is a chance though that the problem you've discovered is already fixed since the latest release and we could add the necessary changes as a hotfix to DotNest (and the DotNest Core SDK) to improve it. You can tell us about it by opening an issue in the DotNest Core SDK GitHub repository. Thanks!