How To: Use a Third Party Plugin With Serenity

    Especially if you are using TypeScript, there are no special steps involved.

    In case of Saltaralle (which is being deprecated), you might have to write some import classes or use dynamic otherwise.

    But, if you want that component to work well among other Serenity editors in dialogs, you may try wrapping it into a Serenity widget.

    Here we’ll take Bootstrap MultiSelect plugin as a sample, and integrate it as an editor into Serenity, similar to LookupEditor.

    Here is the documentation and samples for this component:

    http://davidstutz.github.io/bootstrap-multiselect/

    First we should download its script and CSS files and place them in correct places under MyProject.Web/scripts/ and MyProject.Web/content folders.

    This component has a NuGet package but unfortunately it is not in a standard fashion (it doesn’t place files into your project folders), so we’ll have to download files manually.

    Download this script file and put it under MyProject.Web/Scripts:

    Download this CSS file and put it under MyProject.Web/Content:

    https://raw.githubusercontent.com/davidstutz/bootstrap-multiselect/master/dist/css/bootstrap-multiselect.css

    Including Script/Css Files in _LayoutHead.cshtml

    According to plugin documentation, we should include these files:

    Open _LayoutHead.cshtml under MyProject.Web/Views/Shared and include these files:

    2. @Html.Stylesheet("~/Content/bootstrap-multiselect.css")
    3. @Html.Stylesheet("~/Content/serenity/serenity.css")
    4. @Html.Stylesheet("~/Content/site/site.css")
    5. // ...
    6. @Html.Script("~/Scripts/bootstrap-multiselect.js")
    7. @Html.Script("~/Scripts/Site/Serene.Script.js")
    8. @Html.Script("~/Scripts/Site/Serene.Web.js")

    I’ll create it under MyProject.Web/Modules/Common/Widgets (first you need to create folder Widgets)

    Create file BSMultiSelectEditor.ts at this location:

    1. namespace MyProject {
    2.     @Serenity.Decorators.element("<select/>")
    3.     @Serenity.Decorators.registerClass(
    4.         [Serenity.IGetEditValue, Serenity.ISetEditValue])
    5.     export class BSMultiSelectEditor
    6.         extends Serenity.Widget<BSMultiSelectOptions>
    7.         implements Serenity.IGetEditValue, Serenity.ISetEditValue {
    9.         constructor(element: JQuery, opt: BSMultiSelectOptions) {
    10.             super(element, opt);
    11.         }
    12.         public setEditValue(source: any, 
    13.             property: Serenity.PropertyItem): void {
    14.         }
    16.         public getEditValue(property: Serenity.PropertyItem, 
    17.             target: any): void {
    19.     }
    21.     export interface BSMultiSelectOptions {
    22.         lookupKey: string;
    23.     }
    24. }

    Here we defined a new editor type, deriving from Widget. Our widget takes options of type BSMultiSelectOptions, which contains a lookupKey option, similar to a LookupEditor. It also implements IGetEditValue and ISetEditValue TypeScript interfaces (this is different than C# interfaces)

    @Serenity.Decorators.element("<select/>")

    With above line, we specified that our widget works on a SELECT element, as this bootstrap multiselect plugin requires a select element too.

    Above, we register our TypeScript class, with Saltaralle type system and specify that our widget implements custom value getter and setter methods, corresponding to getEditValue and setEditValue methods.

    Our constructor and getEditValue, setEditValue methods are yet empty. We’ll fill them in soon.

    Using Our New Editor

    Now, build your project and transform templates.

    Open CustomerRow.cs and locate Representatives property:

    1. [LookupEditor(typeof(EmployeeRow), Multiple = true), NotMapped]
    2. [LinkingSetRelation(typeof(CustomerRepresentativesRow), 
    3.     "CustomerId", "EmployeeId")]
    4. public List<Int32> Representatives
    5. {
    6.     get { return Fields.Representatives[this]; }
    7.     set { Fields.Representatives[this] = value; }
    8. }

    Here we see that Representatives uses a LookupEditor with multiple option true. We’ll replace it with our brand new editor:

    1. [BSMultiSelectEditor(LookupKey = "Northwind.Employee"), NotMapped]
    2. [LinkingSetRelation(typeof(CustomerRepresentativesRow), 
    3.     "CustomerId", "EmployeeId")]
    4. public List<Int32> Representatives
    5. {
    6.     get { return Fields.Representatives[this]; }
    7. }

    If you now build your project and open a Customer dialog, you’ll see an empty SELECT in place of Customer representatives field.

    Let’s first fill it with data:

    We first get a reference to lookup object specified by our lookupKey option.

    We enumerate all items in lookup and determine key and text properties of those items, using idField and textField properties.

    Now save file, and open Customer dialog again. You’ll see that this time options are filled.

    Bootstrap Multi Select Typings

    According to documentation we should now call “.multiselect()” jQuery extension on our select element.

    I would cast our SELECT element to <any> and call .multiselect on it, but i want to write a TypeScript .d.ts definition file to reuse multiselect with intellisense.

    So, under MyProject.Web/Scripts/typings/bsmultiselect folder, create a file, bsmultiselect.d.ts

    1. interface JQuery {
    3. }
    5. interface BSMultiSelectOptions {
    6.     multiple?: boolean;
    7.     includeSelectAllOption?: boolean;
    8.     selectAllText?: string;
    9.     selectAllValue?: string | number;
    10. }

    Here, i have extended JQuery interface which belongs to jQuery itself and is defined in jquery.d.ts. In TypeScript you can extend any interface with new methods, properties etc.

    I used plugin documentation to define BSMultiSelectOptions. The plugin actually has much more options, but for now i keep it short.

    Now i’ll go back to our constructor and initialize a multiselect plugin on it:

    1. export class BSMultiSelectEditor {
    2.     constructor(element: JQuery, opt: BSMultiSelectOptions) {
    3.         super(element, opt);
    5.         element.attr('multiple', 'multiple')
    7.         let lookup = Q.getLookup(this.options.lookupKey) as Q.Lookup<any>;
    8.         for (let item of lookup.get_items()) {
    9.             let key = item[lookup.get_idField()];
    10.             let text = item[lookup.get_textField()] || '';
    11.             Q.addOption(element, key, text);
    12.         }        
    14.         element
    15.             .attr('name', this.uniqueName + "[]")
    16.             .multiselect();

    Open CustomerDialog and you’ll see that Representatives has our bootstrap multi select editor.

    Handling GetEditValue and SetEditValue Method

    If we don’t handle these methods, Serenity won’t know how to read or set your editor value, so even if you select some representatives, next time you open the dialog, you’ll have empty selections.

    setEditValue is called when editor value needs to be setted. It takes a source object, which is usually your entity being loaded in a dialog.

    Property parameter is a PropertyItem object that contains details about the field being handled, e.g. our Representatives property. It’s name field contains field name, e.g. Representatives.

    Here we have to call multiselect(‘refresh’) after setting select value, as multiselect plugin can’t know when selections are changed.

    getEditValue is opposite. It should read edit value and set it in target entity.