Custom Settings, Short Codes - This week in Orchard (05/06/2020)

Gábor Domonkos's avatar
Documentation, This week in Orchard

This week we are going to see some code and code samples that could be good to know when developing your Orchard Core application. But we are not just doing that! We will also show you a nice demo about how to create custom settings in Orchard Core just using the admin UI without typing a line of code! Let's start our journey!

Orchard Core updates

Adding branding assess to docs

You can find a new page in the documentation called Orchard Core Branding where you can find graphics assets for Orchard Core's branding.

The Orchard Core Branding page in the Orchard Core Documentation

Allow classes by default with the HTML sanitizer

Last week we saw the new HtmlSanitizerService in Orchard Core that is responsible for sanitizing the HTML code. Now when you are adding Orchard CMS to your application by calling the AddOrchardCms extension method, it will call the AddHtmlSanitizer extension method that will set up the HtmlSanitizerOptions. And it will add the class as an allowed HTML attribute to the sanitizer.

Allowing the class attribute by default when sanitizing HTML

Change [media] short code to [image]

Two weeks ago we mentioned one of the newest features of Orchard Core called short codes. This feature is about letting you evaluate some HTML blocks and replace short codes. Right now we have only one, that looks for everything that has the text between [media] and [/media] and then takes whatever is inside. Ensure its a valid URL and sanitize the output of this thing just in case it would contain some ref to a JavaScript or anything that could look like a script and returns the result. And the result will be an IMG HTML tag with an src attribute.

But we should consider renaming the [media] short code to [image] because it generates an IMG tag. So, the community decided to rename the [media] short code to [image]. Maybe tomorrow your media might be another file, a video or whatever, so, why call it media, it can be anything. Later maybe you will add other short codes that would be used to render different tags, figures, image sets, or whatever. Check the ImageShortCode.cs file for the full implementation.

The new ImageShortCode is to replace the MediaShortCode

Add IServiceProvider to shape Creating Created contexts

The ShapeCreatedContext didn't have a ServiceProvider as the ShapeDisplayContext do. This means services resolved through an IShapeTableProvider with OnCreated either need to be resolved through the constructor, which causes disposed exceptions, and scope capturing, or by directly accessing the ShellScope.Services.

But what does it mean in practice? Let's say you inherit from the ShapeFactoryEvents abstract class that implements the IShapeFactoryEvents interface and you want to add some additional logic after your shape has been created. In our case, we would like to show a new notification when a shape has been created. For that somehow we need to resolve the INotifier and the IHtmlLocalizer. To achieve our goal we can just simply get the ServiceProvider from the ShapeCreatedContext and implement the business logic.

Accessing the ServiceProvider from the ShapeCreatedContext

Update Fluid and YesSql dependencies

Now you can track objects that have been saved and then modified again after a flush in YesSql. In Fluid everything is a decimal now and not a double because when you do 10 - 0.9 you want to see 9.1 and not 9.000009.

Fluid now using decimal instead of double


Custom Settings

You may know that you can create custom settings on Orchard Core by writing some code: implement the class to store the properties, add a SectionDisplayDriver to it, then pass your class using a ViewModel to a Razor page. You may also need to implement the INavigationProvider interface to be able to reach your setting in the admin UI from a new option on the menu. But you can also create custom settings without the need of writing any line of code in a very easy way. Do you want to know how?

First, we set up the site using the Blog recipe, but you can choose any of the built-in ones, you just make sure that the Custom Settings feature is enabled. Now, navigate to the admin UI of Orchard Core and select Content -> Content Definition -> Content Types and create a new content type. Let's call it Company Brand. This setting is about storing some related information about a company. The company will have a name and a logo. For that, we will attach a Text Field and a Media Field to our content type. You have to do two things to make this content type a custom setting:

  • Disable Creatable, Listable, Draftable and Securable metadata as they don't apply.
  • Set the stereotype of the content type to CustomSettings.

The content definition of the Company Brand content type

And that's all! Congratulations, you created a custom setting in Orchard Core without writing any code! If you don't believe that, head to Configuration -> Settings where now you can already see a new option called Company Brand. If you click on it, the CMS will show you the editor of your content type just as you set it up when you defined the content definition of your type.

Company Brand settings page

Now you can work with this custom setting as you would work with the ones that you create using code. Don't forget, the documentation of Orchard Core contains a great section about custom settings. If you prefer videos, you can also check out how to create custom settings just using the admin UI on YouTube!

News from the community

Check your language in the Setup screen of Orchard Core

With the next public release so close, please check that your language looks perfect in the Setup screen. Some culture files are only missing a few strings:

  • Greek (1)
  • Japanese (3)
  • Persian (1)
  • Polish (3)
  • Russian (3)
  • Spanish (1)
  • Turkish (8)

If you speak one of the listed languages, just fire up a new Orchard Core site and select your language using the picker in the top-right corner of the screen. If you find any incorrect translation or some weird string, just leave a comment below!

The setup screen in Turkish

Orchard Core workshops

The contributors of Orchard Core will hold some unique online workshops in the coming months, between May and September 2020. So even with Orchard Harvest postponed due to the coronavirus pandemic we'll get some new learning events.

Lombiq's developers will also give two workshops, on using Orchard from the admin UI and on developing a module.

Are you looking to get up to speed with Orchard? Check out the workshops' details on the Orchard Core homepage!

Orchard Dojo Newsletter

Now we have 146 subscribers of the Lombiq's Orchard Dojo Newsletter! We have started this newsletter to inform the community around Orchard with the latest news about the platform. By subscribing to this newsletter, you will get an e-mail whenever a new post published to Orchard Dojo, including This week in Orchard of course.

Do you know of other Orchard enthusiasts who you think would like to read our weekly articles? Tell them to subscribe here!

If you are interested in more news around Orchard and the details of the topics above, don't forget to check out the recording of this week's Orchard meeting!

No Comments

Add a Comment