Blog

Introduction: Dependency Injection in Orchard CMS

Sat, 03 Nov 2018 13:49:26 GMT

Before we start talking about Orchard Framework implementation of dependency injection, and how we can use and extend it, you can start with this link to understand the ASP.Net MVC dependency injection.

Orchard DI was built on top of Autofac library (Which known as one of the best DI libraries for .Net framework), also Orchard framework layer will simplify the manipulation of injectable dependencies, in many aspects as creating, suppressing and scoping.

Register New Dependency

Orchard has automatic discovery and registration mechanism for dependencies, so if you want to register new one, simply make it implement "IDependency" interface like the following:

Public interface IServiceDependency : IDependency {
}

Public class ServiceDependency : IServiceDependency {
}

Now, "ServiceDepenency" is injectable.

Control Dependency Lifetime Scope

One of the main advantages of using dependency injection pattern, is how it make controling the lifetime of dependencies very simple, combining that with the automation of registration in Orchard will make our life easier than ever.

Orchard has four predefined scopes to be used in our registrations, every one of them has a specific interface to be implemented, this way we will tell Orchard how to register our dependencies, as following:

IDependency: Base interface for services that are instantiated per unit of work (i.e. web request).
ISingletonDependency: Base interface for services that are instantiated per shell/tenant.
IUnitOfWorkDependency: Base interface for services that may *only* be instantiated in a unit of work, this interface is used to guarantee they are not accidentally referenced by a singleton dependency.
ITransientDependency: Base interface for services that are instantiated per usage.

Feature Based Dependencies

What you should do to bind a dependency to a specific feature? then, simply if the feature being disabled, then all its bound dependencyies will not going to be registered from the beginning, this also can be done simply by what Orchard offers.

To bind a dependency to specific feature, you can decorate it by "OrchardFeatureAttribute" attribute, like:

[OrchardFeature("CustomFeature")]
Public class ServiceDependency : IServiceDependency {
}

Now, "ServiceDependency" will be bound to feature called "CustomFeature", so we can have multiple implementations of "IServiceDependency" interface with the ability to switch between them easily by enabling or disabling their parent feature.

Suppressing Dependencies

Sometimes, we need to override one of the dependencies without disabling its feature, here you will need to decorate your dependency by "OrchardSuppressDependency" attribute, which take the full qualified name of the original dependency as a parameter, like:

[OrchardFeature("OtherCustomFeature")]
[OrchardSuppressDependency("CustomFeature.Services.ServiceDependency")]
Public class OtherServiceDependency : IServiceDependency {
}

Now, if "OtherCustomFeature" feature is enabled, "OtherServiceDependency" will be registered as an implementation of "IServiceDependency", instead of "ServiceDependency".

Manual Dependency Registration

Although, automatic dependency registration with lifetime scope controling is very useful, but in some cases you will need to manually registering your dependencies, to take full control of the registration.

Since Orchard DI is based on Autofac, then you can use one of Autofac features (which supported by Orchard) to do this.

With the usage of "Modules" Autofac feature (Please refer to this link for more information), in addition to Orchard automatic discovery and registration mechanism which includes Modules also, you can gain more space to configure your registrations and doing some magical things with them, inside "Module" implementation you will find the following skeleton:

public class CustomModule : Module {
    protected override void Load(ContainerBuilder builder) {
        // Add registrations to the container
    }

    protected override void AttachToComponentRegistration(IComponentRegistry componentRegistry, IComponentRegistration registration) {
        // Attach module-specific functionality to a component registration.
    }
    
    protected virtual void AttachToRegistrationSource(IComponentRegistry componentRegistry, IRegistrationSource registrationSource) {
        // Perform module-specific processing on a registration source.
    }
}

How To: Image Watermark Filter

Mon, 11 Dec 2017 00:46:13 GMT

Orchard CMS has very impressive feature called "Orchard.MediaProcessing", which give us the ability to manibulate media files at runtime through predefined set of filters, to create multiple versions of same media file without the need to upload it multiple times, currently, Orchard comes with two prebuilt filters (Resize and Format), and as always, like other Orchard features, you can extend the list of filters to include any type of manibulation filters as you need using the extensibility hooks.

In this post, we will learn how to add a new filter, which frequently asked by the community, aims to add image or text watermark to site images, in next steps we will explian most important parts of the code, while you can download the nuget package from attachments section below (Compatible with Orchard 1.10 and later), or you can browse the full source code of the module on Github.

"ImageProcessor" Library

The default library for all Orchard predefined image processing filters is "ImageResizer", that although it is a great library, but it does not has a good watermark plugin to use in our case, so the choice was to use "ImageProcessor" library instead.

The main reason of using "ImageProcessor" library, that it can apply the watermark image and text using streams without the need to save the image in file system to be able to process it like other libraries, so you can manibulate the context stream directly inside the filter provider even if the file stream is coming from external source (Refer to this documentation for more information).

Apply Filter

var result = new MemoryStream();

using (ImageFactory imageFactory = new ImageFactory(preserveExifData: true))
{
    imageFactory.Load(context.Media)
        .Overlay(new ImageLayer
        {
            Image = watermarkImage,
            Size = new Size(width, height),
            Opacity = opacity,
            Position = position
        })
        .Save(result);

    context.Media = result;
}

As you see, "ImageProcessor" watermark maniplulation is based on layers, so you can add any number of layers (Image or Text Layers), as in the previous code snippet, where we are maniplulating the "Media" stream directly through the "imageFactory" to add new "ImageLayer" with specific properties which should be defined by the user through the admin dashboard (You can try the attached module to see how it is working), also we can do the same to add "TextLayer".

Thoughts: On Orchard Core

Fri, 26 Aug 2016 09:19:19 GMT

Orchard CMS has a very spirited team, they keep trying to catch up with the latest trends, the first version of Orchard CMS was a very successful start, it was built on a strong foundation, which aims to achieve the goals of MVC architecture, and with the second version (until now, it is in Pre-Alpha stage), they applied a lot of learned lessons from previous version, to up the product to another level of dynamicity and efficiency.

If you try to experiment the current Pre-Alpha of Orchard CMS 2.0, you will notice that the main focus in this version is on two aspects, architecture (Decoupling and Abstraction) and performance (Database Structure), and this is what we will briefly talk about in this post (will be explained deeper in the upcoming posts).

Decoupling and Abstraction

The main purpose of MVC architecture is to boost the decoupling of the system components (isolates the application logic from the user interface layer and supports separation of concerns), ASP.NET is one of the best implementations of this architecture, and ASP.NET Core 1.0 is a huge step in loose-coupling development field, on the other side, Orchard is constantly evolving to keep track of changes and improvements, that reflected in Orchard 2 which is based on ASP.NET Core.

To achieve the decoupling goal, Orchard 2 will not has a single framework file (which has all the API's, as Orchard 1), it is broken down to several files, and that will lead to get the following benefits:

Each of these modules will have a particular target.
You don't need to reference all these API's in your custom module, While you need only a few of them.
Improving site performance.
It will be very smooth to use any orchard module in a non-Orchard projects, since each framework module can be published as a standalone nuget package.
Most of framework modules have an abstraction layer, to be easy to surpass their implementation.

Database Structure

While Orchard 2 will maintain the same single content items table structure, it will have a huge update on how data indexed for search in the database layer, since data access layer in the next version of Orchard will be based on YesSql library (.NET document database using any RDBMS).

The following image will describe the new database structure compared to the old one:

As you see, the main difference between them, that in the old structure you can index your data per part, and store the part properties in it's connected record table, but the downside of this structure is that all part records for all the content items which the part is attached to them will be stored in the same table, but this will be changed with the new structure, with the usage of YesSql library, where you are free to add any number of indexing records as you need, either if all the properties are from the same content part, or a combined properties from multiple parts, then you can query your data based on these indexes.

Note

These are my thoughts on the next version of Orchard CMS, and this post will be updated periodically to reflect any new findings, since Orchard 2 is still in Pre-Alpha stage, it will have a lot of changes in the upcoming stages, and we eagerly await to see what's new.

How To: Add Custom "Dictionary Token"

Sun, 01 May 2016 11:39:00 GMT

We all definitely used the tokens feature of orchard before, which provide us a smart way to replace strings with custom data, orchard has the basic tokens built in out of the box (like: Content, Text, Url ... etc), with the ability to connect tokens in chains to be more useful with the ability to build more complex tokens.

In this post, we will take orchard tokens functonality to another level of dynamicity, by implementing new token called "Dictionary", to be able to support any type of objects, with dynamic chain building.

Implement New "ITokenProvider", called "DictionaryTokens"

Here, we will describe and evaluate our new dictionary tokens, like the following:

public class DictionaryTokens : ITokenProvider {
    public DictionaryTokens() {
        T = NullLocalizer.Instance;
    }

    public Localizer T { get; set; }

    public void Describe(DescribeContext context) {
        context.For("Dictionary", T("Dictionary"), T("Dictionary tokens"));
    }

    public void Evaluate(EvaluateContext context) {
        var dataContext = context.For<Dictionary<string, object>>("Dictionary");
        if (dataContext.Data != null) {
            foreach (var data in dataContext.Data) {
                if (data.Value is string) {
                    dataContext.Token(data.Key, d => (string)d[data.Key])
                        .Chain(data.Key, "Text", d => (string)d[data.Key]);
                }
                else if (data.Value is DateTime) {
                    dataContext.Token(data.Key, d => (DateTime)d[data.Key])
                        .Chain(data.Key, "Date", d => (DateTime)d[data.Key]);
                }
                else if (data.Value is IContent) {
                    dataContext.Token(data.Key, d => (IContent)d[data.Key])
                        .Chain(data.Key, "Content", d => (IContent)d[data.Key]);
                }
                else if (data.Value is IUser) {
                    dataContext.Token(data.Key, d => (IUser)d[data.Key])
                        .Chain(data.Key, "User", d => (IUser)d[data.Key]);
                }
                else if (data.Value is JObject) {
                    dataContext.Token(data.Key, d => d[data.Key])
                        .Chain(data.Key, "Dictionary", d => 
                            ((JObject)d[data.Key]).ToObject<Dictionary<string, object>>());
                }
                else {
                    dataContext.Token(data.Key, d => d[data.Key]);
                }
            }
        }
    }
}

This provider will take your dictionary as parameter, then check it's contents in the evaluation process, to link every property to the appropriate token chain, with support to chain itself if there is an object within the dictionary.

Let's Use It

We can use this new token like any other one, declare a dictionary and pass it to the tokenizer service with a key, as following:

var message = "Hi {Dictionary.User.FirstName} {Dictionary.User.lastName},<br/>" +
    "This message sent to {Dictionary.Email}:<br/>" +
    "<strong>{Dictionary.Subject}</strong><br/>" +
    "{Dictionary.Message}";
var messageDictionary = new Dictionary<string, object> {
    {"Subject", subject},
    {"Message", message},
    {"Email", email},
    {"User", new Dictionary<string, object> {
       {"FirstName", firstName},
       {"LastName", lastName}
    }
};
var tokenizedMessage = _tokenizer.Replace(
                           message, 
                           new Dictionary<string, object> { 
                               { "Dictionary", messageDictionary } 
                           }
                       );

If we run this code with the following dictionary data:

Subject: "Test Subject"
Message: "Test Message"
Email: "test@test.com"
User:
    FirstName: "testfirstname"
    LastName: "testlastname"

The output string will be:

Hi testfirstname testlastname,
This message sent to test@test.com:
Test Subject
Test Message

How To: Add "placeholder" attribute to Text Field in Dynamic Forms

Fri, 15 Apr 2016 12:24:00 GMT

Orchard CMS is built on a powerful architecture that provide us rich ways to extend it, and to add some missing features as needed.

"PlaceHolder" Attribute

HTML 5, has a very useful attribute called "placeholder", it is used to display a watermark text on the input field when it's empty, but text field and text area elements in dynamic forms module don't have this attribute out of the box, and we will learn how to add such attribute in this post.

Add New Editor Form "PlaceHolderForm"

First thing we will do, implement a new editor form for "placeholder" attribute, to be able to attach it to text field and text area editors, this form will have a single tokenized input field, to enter the attribute value, as following:

public class PlaceHolderForm : Component, IFormProvider {
    public void Describe(DescribeContext context) {
        context.Form("PlaceHolder", factory => {
            var shape = (dynamic)factory;
            var form = shape.Fieldset(
                Id: "PlaceHolder",
                _Value: shape.Textbox(
                    Id: "PlaceHolder",
                    Name: "PlaceHolder",
                    Title: "PlaceHolder",
                    Classes: new[] { "text", "medium", "tokenized" },
                    Description: T("The value of placeholder attribute.")));
            return form;
        });
    }
}

Implement New "TextFieldElementDriver"

Drivers in Orchard CMS used to transport data to a template for rendering, called "Shape", and we can implement multiple drivers for the same item to render more shapes from same data source in different zones.

Now, we will implement new driver for "TextField" element, called "TextFieldElementDriver", then override "OnBuildEditor" method to attach the form "PlaceHolderForm", which was created on the previous step to the output editor, and override "OnDisplaying" method to read attribute value from the element data property, then add a new attribute to the rendered element shape.

public class TextFieldElementDriver : FormsElementDriver<TextField> {
    private readonly ITokenizer _tokenizer;

    public TextFieldElementDriver(
        IFormsBasedElementServices formsServices, 
        ITokenizer tokenizer) : base(formsServices) {
        _tokenizer = tokenizer;
    }

    protected override EditorResult OnBuildEditor(
        TextField element, 
        ElementEditorContext context) {
        var placeholderEditor = BuildForm(context, "PlaceHolder");
        return Editor(context, placeholderEditor);
    }

    protected override void OnDisplaying(
        TextField element, 
        ElementDisplayingContext context) {
        context.ElementShape.ClientValidationAttributes.Add("placeholder", 
            _tokenizer.Replace(element.Data["PlaceHolder"], context.GetTokenData()));
    }
}

Then you can implement new driver for text area field to add the same attribute to it using same "PlaceHolder" form.

Note

You must have noticed that we used the "ElementShape.ClientValidationAttributes" instead of "ElementShape.Attributes", which is the right way to add attributes to shapes in orchard, but we are currently forced to use this workaround because there is an issue in orchard, and you can see issue #6812 for more information.