Documentation

For Developers


1.   Installing uCondition

Initial installation

To install uCondition, simply open Nuget Tools or the Package Manager in Visual Studio.  Type:

Install-Package uCondition

This will install all the necessary files and dependencies required to run it.

If you are developing predicates in isolation from the web site, install the uCondition.Core project, which only contains the references necessary to create predicates.

Set up the data type

Log in to Umbraco, go to the developer section and create a datatype.  Select 'uCondition' in the property editor drop down.

Add the data type to any of your document types.

Global Conditions

If you go to the root of content, you will notice there is a new tab called "Global Conditions".  Here you can create global conditions that can be used in the uCondition datatype.

2.   What is a Condition to a developer?

A condition is a rule based on one or more predicates.  A predicate is something that can be either true or false.  The content editor creates the condition, but as a developer, you are responsible for creating predicates that can be used in that condition.  A predicate is implemented by inheriting the uCondition predicate base class.

When you inherit the predicate base class you give it a friendly name, a unique alias, an icon, a category and a list of editable properties that allow the content editor to configure your predicate.  The editable properties are key to making your predicate as reusable as possible.  For example, you may want to create a predicate that checks for a certain amount in the shopping basket.

3.   Create a simple predicate

We are going to show you how to create a simple predicate that can be used to check whether a customer has a minimum amount in their shopping basket.

1. In your Visual Studio project, create a class called 'HasAmountInShoppingBasket'.  

2. Inherit uCondition.Models.Predicate

public class HasAmountInShoppingBasket : uCondition.Models.Predicate
{

}

3. Add the following constructor code:

public HasAmountInBasket()
{
Name = "Has amount in shopping basket";
Alias = "HasXAmountInBasket";
Icon = "icon-shopping-basket-alt-2";
Category = "ECommerce";
Fields = new List<EditableProperty>
{
new EditableProperty("Amount", "amount", "Textstring")
};
}

On Predicate we have the following properties:

Name This is the display name that is shown in the CMS
Alias This uniquely identifies your condition.  We have namespaced the alias in the example.
Icon The icon class.  This is rendered in the 'Add Predicate' side bar.  More icon classes can be found in the Document Type editor
Category The category where the condition should be listed in the 'Add Predicate' side bar
Fields The fields that allow CMS users to configure your predicate.

4. Now we need to implement the Validate method.

public override bool Validate(IFieldValues fieldValues)
{
   var minBasketAmount = fieldValues.GetValue<decimal>("amount");
   //get the current basket and check the total amount
   var basketAmount = 49.99m;
   return basketAmount >= minBasketAmount;
}

5. Rebuilt your solution to see the new condition in uCondition.

public class HasAmountInShoppingBasket : uCondition.Models.Predicate
{
    public HasAmountInBasket()
    {
        Name = "Has amount in shopping basket";
        Alias = "HasXAmountInBasket";
        Icon = "icon-shopping-basket-alt-2";
        Category = "ECommerce";
        Fields = new List
        {
            new EditableProperty("Amount", "amount", "Textstring")
        };
    }

    public override bool Validate(IFieldValues fieldValues)
    {
        var minBasketAmount = fieldValues.GetValue<decimal>("amount");
        //get the current basket and check the total amount
        var basketAmount = 49.99m;
        return basketAmount >= minBasketAmount;
     }
}

4.   Editable Properties

Editable properties are a way for content editors to customise your predicate.  This can be an integer, string, or a more complicated piece of data.

Editable properties utilise Umbraco's datatype/property type system.  This means you can use native property types and even use your own custom property type.

When declaring a new EditableProperty in your Fields list, there are a few constructors available.  Here is an description for each parameter: 

Name The name of the property.  This is displayed to the user
Alias The alias of the property.  You will use this to access the value set by the CMS user
Control This is the name of the Datatype/Property Type that will allow the user to configure your condition.  This can be a Multi Content Picker, Radio Button List, Drop Down Values,or any other datatype you may want to use.
Value Type

This is used when rendering the value in the predicate in the backoffice.  This is an enum and tells uCondition how to render the value.

Here are the enum values:

Standard - this displays the raw value to the user

Is Boolean - this will render as true or false

Is PreValue - this will display the prevalue text.  By default, the prevalue ID is stored and displayed, but if you are using a drop down or radio button list, you will want to use this to display the prevalue text to the user.

Hidden - this will hide the value selected from the user.  You may want to use this if the property type value is json or any other data that may be too large to preview.

5.   Validate the condition

To test the condition, there is an extension method available for IPublishedContent.  Add a using for uCondition.Core.Extensions.

Code for a Razor View

@using uCondition.Core.Extensions

@inherits UmbracoTemplatePage

@* Test the condition*@

@CurrentPage.IsExpressionTrue("propertyAlias")

Code for a C# class

using uCondition.Core.Extensions;

namespace Your.Namespace

{

   public class SomethingController : SurfaceController

   {

        public ActionResult DoSomething()

        {

               if(CurrentPage.IsExpressionTrue("propertyAlias"))

               {

                     //do something

                }

         }

   }

}