Shortcodes, Audit Trail - This week in Orchard (31/07/2020)
This week we show you two demos of the brand new upcoming features of Orchard Core! The first one is the Shortcodes feature, that allows text content editors to inject specialized content blocks using custom arguments, like images, twitter embeds, youtube videos, only with simple blocks like [video 123]. The Audit Trail module provides log records for creation, deletion of any Content Type, and events like user events, as you may see it Orchard 1.x. Heads up for a post full of demos!
Orchard Core updates
Add user deleted event
In the OrchardCore.Users.Handlers.IUserEventHandler there was no contract for the user deleted event. From now there is the new DeletedAsync method that is invoked if a user has been deleted. Check out the code in the UserStore.cs file, where you can see the invoking of the new method.
This new event is also accessible from your workflow type. If you create a new workflow type and click on the Add Event button, you will find the User Deleted event in the User category.
Admin CSS/Bootstrap regressions
Back in Bootstrap 3, col-lg means nothing, so we had some special CSS in the admin theme to make it mean something. In Bootstrap 4, the col-* now means something, because here you have auto-sizing columns. It's still not exactly ideal because there is a lot of variation for the sizes. You can see the new names here to make them more meaningful. These are the new classes in the TheAdmin.scss file.
Demos
Shortcodes
Sébastien Ros created a new open-source project called Shortcodes. This is a .NET library to parse and evaluate shortcodes. It allows text content editors to inject specialized content blocks using custom arguments, like images, twitter embeds, youtube videos, only with simple blocks like [video 123].
Shortcodes are essential to WordPress, and for the Orchard Core, we wanted a similar feature. The parser was written by hand as the syntax is simple and it needs to be efficient. Thanks to Dean Marcussen, this library will be integrated into Orchard Core soon. In this demo, we will see what we can do in Orchard Core using that library!
Let's say you installed your site using the Blog recipe. Make sure that the Shortcodes feature is enabled. When you are editing a content item with a WYSIWYG HTML editor (for example the HtmlBody Part of the Article content type or a content type with a MarkdownBody Part) you can get a little pop-up if you are clicking on the Insert Shortcode button near the Link button by default. The pop-up will contain a list of the available shortcodes. Let's try the one called bold now. As you may guess, this shortcode is about to make your text bold. Select it from the list and provide the text that you would like to appear as bold.
Note that here we used the [bold "bold text"] syntax when made the text bold. That works, because if you check the definition of the bold shortcode, you could see that we get the value of the text using the args.NamedOrDefault method. If we don't use the text named argument to pass the value of the content that we want to make bold, then it will just simply use the default one, meaning that it will use the content without any argument. So, if you are using the syntax [bold text="bold text"] you will get the same result.
But the bold shortcode is also supporting content arguments. It means shortcodes using opening and closing tags can access their inner content. If you would like to use content arguments you can do something like [bold]bold text[/bold]. It will work because if the value of the text is null we will just use the value of the content variable that is the text between the opening and closing tags.
Now let's see something else! If you navigate to Design in the admin UI, you will find a new option called Shortcode Templates! Let's see what a Shortcode Template is! Here you have the ability to actually write shortcodes in Liquid. Create a new one and call it Primary! This is about checking if your shortcode has something in the argument called text. If yes, we use the value of the text argument, if not, we are about to work with the content argument. The shortcode wraps the text in a span and adds the text-primary class to it. In this case, you can use this shortcode as you could see in the case of the shortcode called bold.
But you also have the option to override the shortcodes that are implemented from code. In that case, you just need to call your shortcode template bold, and that will replace the existing one that has been written in code.
If you would like to know more about shortcodes, don't forget to check out the demo on YouTube!
Audit Trail
Let's install your site using the Blog recipe. Then head to Configuration -> Features and enable the Audit Trail module. After you will see a new option in the menu of the admin UI called Audit Trail. The Audit Trail module provides log records for creation, deletion of any content type, and events like user events. So, let's do some content modification to see how you can use the Audit Trail feature!
Navigate to New -> Article and publish a new Article content item with some data. Now edit some data in your newly created article and hit Publish again! Now navigate to the Audit Trail option on the menu and see the new records in the table.
The audit trail table provides you with filtering and with pagination to be able to easily find the audit trail event that you are looking for. You can filter by
- a given date range,
- categories (All categories, Content Item, User),
- the user name of the user who caused the event to occur.
Every record of the table can have a view in the Summary column. A record with the Content Item category shows you the version of the content item at the moment of recording. If you click on the Version X link you can see the read-only editor of the content item filled with the values that the content item has at that version.
If you click on the display text of the content item you can edit the content item.
Here you will see four recorded events regarding the changes that we have just made in the case of our article.
- The first one is about showing you the fact that we created the first version of the Article content type with the display text My new article.
- The second is about telling you that you clicked on the Publish button, that means you published that article.
- After you will see a Saved event. If you publish a new version of the article, Orchard Core first saves a new version of it (it also creates a new draft version), then publishes it. You can also see that now we have two different kinds of versions of this article.
Now let's see what we have just changed in that article. To do that, click on the Details link of the Saved event. Here you can get more information about the given event. When you are checking the Detail view of a Content Item event you can see a table that contains the differences between the current version of the content item and the previous version of the content item in the Diff column. The values of the current content item will be shown in green, and the values of the previous content item will be shown here in red. You can show/hide this column using the Show diff switch.
If you turn the Show before/after switch on, you will see two new columns: Before and After. These are about to show you the values of the properties of the previous version of the content item and the values of the properties of the current version of the content item.
Here you can see we changed the Subtitle Text Field and the Html value of the HtmlBody Part of the article.
If you navigate back to the audit trail table and check out the first Published event of the article content item, you will also see a new link here called Restore. If you click on this link, Orchard Core will create a new draft instance of the selected content item version. You can also restore the removed content items too.
You can attach the AuditTrailPart content part to your content type that allows content editors to enter a comment to be saved into the audit trail event when saving a content item. This comment will be shown in the Comment column of the audit trail table.
If you navigate to Configuration -> Settings -> Audit Trail you will find a list that contains every event that can you record using the Audit Trail module. Here you can enable or disable the recording of the given events.
You can also enable client IP address logging. When you enable that, the client IP address will be recorded in audit trail event records.
If you click on the Set blacklisted content types button you will see a new modal window with all of the defined content types in your system. Here you can select the content types that you don't want to log using the Audit Trail. For example, if you don't want to log the changes of the Article content items, then you may put a tick of the checkbox of the Article content type.
The Trimming Settings is about to say how long you would like to keep the audit trail logs in the database. You can disable trimming if you would like to keep the records.
And that's not the whole demo! If you are interested in the upcoming Audit Trail feature of Orchard Core, head to YouTube and check out the recording!
News from the community
A new website using Orchard Core
Singapore is the third international country outside North America to introduce Starbucks to its discerning customers who readily embrace the Starbucks Experience. And they used Orchard Core to build the website for Starbucks Singapore!
If you are interested in more websites using Orchard and Orchard Core, don't forget to visit Show Orchard. Show Orchard is a website for showing representative Orchard CMS (and now Orchard Core) websites all around the internet. It was started by Ryan Drew Burnett, but since he doesn't work with Orchard anymore, as announced earlier it is now maintained by our team at Lombiq Technologies.
Orchard Core workshops
The contributors of Orchard Core will hold some unique online workshops in September 2020. So even with Orchard Harvest postponed due to the coronavirus pandemic we'll get some new learning events.
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 154 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!
Daniel Lidström said
In the code sample for the deleted event, what is the context variable in line 100 used for?
Zoltán Lehóczky said
It contains contextual information (well, just the currently deleted user in this case) that an event handler might need. As you can see, it's passed to the event handlers in the next line. Event handlers like this commonly receive a similar context object.
Daniel Lidström said
Thanks for clarifying!