OpenAPI, Swagger, Taxonomy Localization - This week in Orchard (12/06/2020)
This week we prepared with two new demos: the Taxonomy Localization and the Orchard Core OpenAPI Code Generation Tools based on NSwag! But before doing that, let's see the latest changes that will be added to the RC2 release of Orchard Core that is now really just a few days ahead!
Orchard Core updates
Refactor Blog recipe to have fewer required fields
You may found that creating blog posts in Orchard Core using the Blog recipe could be not very user friendly. When you create a new blog post, you have to provide tags and select the category for the posts, however, you will also need to add a banner image for it. These are all required fields, without these, you cannot publish your post. But from now these fields are optional and the Markdown editor is just below the Title and the Permalink, so you don't need to scroll down to start typing your new exciting post!
Add ConfirmationEmailSubject to RegisterUserTask
When you are dealing with workflows you can find a task called Register User. This is about register a user from a form field, meaning that the activity is getting the request body as a form to get an IFormCollection and try to get the UserName and Email values from that. If everything goes fine, the task will register the user and if you edit the activity, you will find some more stuff to set up! Here you can say to send a confirmation email to the user with a given subject and you can also use a template for the confirmation email if you want!
How to contribute to the Orchard Core documentation?
Have you ever thought about contributing to the Orchard Core documentation, but you cannot find a line about how to do that? Well, here comes the good news! From now, you will find a new guide in the documentation that tells you everything that you need to know to add your great getting started guides, tutorials, and everything to the documentation! Thank you for doing that!
Change content API permissions
You want anonymous users to be able to view your site, view your page/content item and it would just show what the layout is or the view is. But you might not want anonymous users to retrieve the full content item JSON payload, because it might shows some properties and metadata that you don't want to expose. For that, you could use the custom permission called GetApiContent that you can assign to specific roles and this is not assigned to anonymous users by default.
Now, this permission was renamed to AccessContentApi and protects all /api/content methods. If you don't want a user to see all the fields, just don't grant access to the APIs at all, hence the GetApiContent permission is not required as a separate one. This will also protect POST that currently returns the full content. And one more thing: the GetApiContent was already added to the Authenticated role. Now it's removed from that role as being authenticated should not grant access to all fields.
Prevent array duplication when merging existing content
When you do Merge using JSON.Net it will just merge the different arrays. In some cases, it's not what you want. If you want an array to be replaced (for example an array of tags) then it will just add a new tag to that array and not replacing the array with a new array.
On the POST operation of the API, you just want to replace the value and the PATCH operation should be the one that merges different arrays in this case. So, the Content ApiController needs to use ArrayHandling.Replace when updating existing content, or array values are duplicated. Here you can see the changed code and here comes the UpdateJsonMergeSettings: private static readonly JsonMergeSettings UpdateJsonMergeSettings = new JsonMergeSettings { MergeArrayHandling = MergeArrayHandling.Replace };
Demos
Taxonomy Localization
Have you ever wondered how to localize your taxonomy terms in Orchard Core? Well, it could be hard to do it for the first time, but if you are watching the following recording you can get some tips and tricks to reach your goal faster!
Orchard Core OpenAPI Code Generation Tools based on NSwag
Head to GitHub and clone the master branch of the ThisNetWorks.OrchardCore.OpenApi repository. Make sure that the ThisNetWorks.OrchardCore.OpenApi.Sample project is your starting project then just simply build and run the solution. When setting up your site don't forget to use the Open API Sample recipe to enable the needed modules and theme.
If you navigate to https://localhost:44300/swagger, you will see the endpoints that are available in Orchard Core and a sample controller named Foo that comes from the ThisNetWorks.OrchardCore.OpenApi.SampleModule module. Here you can make queries on them and now we will also get schemas that are generated using the NSwag toolchain! Let's check for example the BlogPostItemDto!
Now we can use those! The samples folder contains a console client that you can use to try the endpoints. You can simply open the solution with Visual Studio (ThisNetWorks.OrchardCore.OpenApi.ConsoleClient.sln) and fire up the ThisNetWorks.OrchardCore.OpenApi.ConsoleClient project.
This is about calling the endpoints by using a static HttpClient. Open the Program.cs file and check the first few lines of the Main method here. You could see that we are getting a content item by the 4qnhdhv3z54xk4fg4tdfke76c9 and we get the content of the content item in the FooTextItemDto object. The content item with the mentioned ID is a content item of the Foo text content type, which has got one Text Field attached, named Foo Field. Our client modifies the text of this field and making a POST request to send the updated data to Orchard Core. Now if you read back from the API you will get the updated content item with the new text in the Foo Field. But there is a lot more than that! You can see that you can get the RecentBlogPosts Lucene query and use the response data, or do other Lucene queries (like give me all the blog posts) and so on. If you are interested in it, there is also a TypeScript client (tsClient.ts) which has the same kind of classes and can be used directly from TypeScript.
Of course, before doing that, you have to do the authentication, get the token, and so on. For that, you have to enable the OpenID module and configure it. It also comes with the recipe by default. The back-end, the Swagger is using Authorization Code Flow, and the console client is using Client Credentials Flow. The client app has a specific API role because it's relevant to just give very limited and specific access to the system.
And that's not all of it! If you need more details about the project, don't forget to check the recording on YouTube!
News from the community
Orchard Nuggets: How to access services from another tenant in Orchard Core?
Do you run a multi-tenant Orchard Core site? Have you ever wondered how you can cross tenant boundaries? We show you the code! Check out our latest Orchard Nugget post for more!
Check out the other posts for more such bite-sized Orchard tips and let us know if you'd have another question!
Updated Dojo library
We've updated the famous Dojo Library to Orchard Core! Orchard Dojo is a portable package of coding and training guidelines, development utilities. Check out our updated library and start learning today!
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!