Blog posts by Hoang Tran

Connecting a remote EPiServer database to an EPiSever CMS, or enable a CMS to use multiple databases

Wed, 28 Oct 2015 10:41:00 GMT

Recently I worked on a project with a special need, that is to merge two similar EPiServer CMS 6R2 sites into one CMS. Legacy content are mostly read-only. We could have many solutions to deliver this requirements, some of commons solutions I could think of such as:

Merge the code bases into one and migrate content so that we have one database that contains content of both sites.
Merge the code base, and connect a database to other database using an open source project remote page provider , which is a WCF service based solution.

And there is a third option I could think of, it could sounds crazy that is to connect a database to another database using page provider, but connecting it directly using SQL connection, not through any service layer.

Actually I would create a new, small database for the new CMS, then connecting old databases into that CMS using SQL page provider. We will have a Search engine to index content of all the databases, used to support listing, querying, filtering, sorting, paging data across databases. We should index only data that we intended to search to keep the index size small and fast.

Here the points that I could argue about this solution, compared to other solutions

Advantages:

The new CMS site would start based on a small database, it would be faster to start then other solutions, in which each legacy database has million of pages. Working with new data in new CMS will be also quicker, because it operates on a small database. Legacy content in old databases are read only most the time, and they are only accessed to only if they are specifically referenced to.

And accessing old content using SQL connection is faster than using any service layer.

We avoided a long, painful and error prone migration process, specially with a database with million of pages, images, documents referencing each other in a complex way. Migration should always be the last option, and it seems impossible with this size of data.

We avoided having to keep the legacy CMS sites running, wasting resources in case we use WCF remote page provider.

Old content is accessed in new CMS through page provider concept, which is a well supported by EPiSever CMS so all data operations works well ( as it's supposed to :) ). The old content will have same ID in new system, but with a provider name tag in its PageReference. New content can reference old content normally, permanent link feature works well, and our search engine will be used extensively for listing, querying, filtering, sorting, paging data across databases. This search engine will enable editors feels that all data is still in one place.

Disadvantages:

A page provider that can provider EPiSever pages from a remote EPiServer database it not readily available, and it could be impossible if EPiSever architecture doesn't allow it.

Hanlding files and images from remote database and VPP also could be a challenge.

Since we access data directly in database, if some how old CMS site is turned on and old data is updated, we could have trouble in synchronizing data. Actually we can handle this quite easy by connecting remote event mechanism between old CMS and new CMS sites.Or we can develop a small service in new CMS to clear the cache when old site updates data in database.

All of these merging solutions will have to handle friendly URL rewriting or redirect for old content.

OK, so far it sounds good right ? We have to do a proof of concept so that we know it could work. I have successfully created a Page Provider that uses SQL connection to read pages from a remote EPiServer database, and also a VirtualPathProvider that can read files from remote database. I could introduce the direction of the solution in this blog, because I believe it could be useful in some situations such as:

We merge similar sites into one such as my project requirements

We have a huge existing site, with millions of old content that are very difficult to clean up, remove or backup, and it slows :). We could start with a new, small database to work with, and connecting old database into the new CMS to still be able to access old content.

We can build a master CMS site, that can manage content of many other "child" CMS sites. And the use of this ? I'm not sure yet, but maybe someone will like this :)

Or we could build a system in which importance, fast growing model reside in separate databases for performance reason. And all of these databases are standard EPiServer ones we we won't have to worry about upgradability.

Here are some importance details of my solution:

EPiServer internally use a page provider called LocalPageProvider, which uses many of data access classes to build up pages from local database tables. So my thought is, is it possible to re-use those data access classes, and just injecting a remote database connection string to them, so that they can fetch pages from a remote database ?

I can see that this question is not officially supported by EPiServer, architecture-wise, or at least from what I know, but I found a way to hack this :)

All data access classes written by EPiServer use the same base class, and this base class, DataAccessBase use a static object called DatabaseFactory to provide connection string setting for most of the database access calls. I did a simple work around, I wrote a composite DatabaseFactory object, returning local or remote connection string based on a global context variable, injected this into DatabaseAccess class. After that I created a page provider, inheriting from LocalPageProvider, like this:

You can see that we set a context data, this is locally per thread or per request, then call the base class to do the database access work. And our CompositeSqlDatabaseFactory will switch connection string based on this context data. But ofcourse we have to "massage" values from remote database to appropriate values before returning the page, this includes page type ID, page type name, page reference (adding the provider tag name), page LinkURL. This works well in a multi thread scenario, it won't affect how EPiServer accessing local database, and we have reused a lot of data access code written by EPiServer :)

There is one catch here though, most links in EPiServer database are stored in permanent link format, which basically a Guid. EPiServer CMS frequently have the need to resolve a Guid into a PageReference, and usually it has to scan all PageProvider for the resolving work, and this is could be the place for performance bottleneck, when we connect a large database into a small database, the site will become slower because of this scanning. But, we can cache all the Guid that are not existed in our SQL page provider and this could preserve my asumptions about the performance improvement with this solution.

OK, next challenge is about the VPP, when I tried to dig deep into the code to find out if it is possible or not, and I was really happy to find out that VirtualPathVersioningProvider uses IObjectStore concept, and we could inject a remote database connection string into an IObjectStore, then inject it into a virtual path provider inheriting from VirtualPathVersioningProvider. But, I was disapppointed in the end, all the classes that are used for file versioning system use the injected IObjectStore correctly, except the VirtualPathVersioningProvider class, it always use the default, local database IObjectStore :| ! I think this is a bug in the implementation. I have to overcome this with some reflection code, but in the end, it works beautifully.

I hope can make this concepts work on CMS version 8+, and maybe have time to explore a scenario in which we have a multisite CMS, with each site in on a separate database also.

Thanks for reading. I'm working for a client so I can't share my code, I think you understand that :).

Applying ajaxify plugin to an existing website, wrong script exec order fixed, example on EPiServer 8 Alloy.

Fri, 02 Oct 2015 09:59:00 GMT

For anyone that have not heard about Ajaxify plugin before, please go here, it's a small plugin that transform links on your website into ajax request, keeping part of your site static, and replace new content from response of ajax request into other part.

I presented a most simple scenario in using this plugin in an image below:

In above scenario, links within the content area will be transformed by ajaxify plugin, clicking on a link will initiate an ajax request to server, and fetching full new HTML page from server.

This plugin handle URL changes and browser history correctly using History.js, and it also execute all the scripts inside the content area only, not script in header or footer, in ajax response again.

If we have a site with very clean coding style, all the scripts should be at the bottom of the site, no script links or script blocks should be inside the content area, it would be perfect. But the topic I presented here is about how to apply this plugin on an existing, probably legacy site, in which you might have plenty of script links or script blocks within the content area.

I discovered an issue with ajaxify plugin when applied it on an existing site, when executing the scripts within content area from ajax response, the scripts order is messed up, script blocks is always executed first, in correct order, but script links will be executed after the script blocks, event the script links appear before script blocks. By script execution order I mean the order they appeared in HTML from top to bottom. All browsers when loading an HTML page normally (not by ajax) will always execute scripts in order they appear in HTML, from top to bottom, and they may download the script links in parallel or get from cache .

For example I have following scripts inside my content area:

<script src="/Static/js/BigExternalJavascripts.js" type="text/javascript"></script>
<script src="/Static/js/SmallExternalJavascripts.js" type="text/javascript"></script>
<script type="text/javascript">
            (function () {
                var localVariable = "script block 1 executed";
                console.log(localVariable);
            })();
            </script>
<!-- some HTML -->
<script type="text/javascript">
            (function () {
                var localVariable = "script block 2 executed";
                console.log(localVariable);
            })();
            </script>

"BigExternalJavascripts.js" is 870KB, "SmallExternalJavascripts.js" is just 1 KB, both of them just
do very simple task, log a message "X external script is executed", X is big or small

When the page is loaded normally, our debug console will show this:

"Big external script executed"
"Small external script executed"
"script block 1 executed"
"script block 2 executed"

When new content is applied from ajax response, our debug console will show this:

"script block 1 executed"
"script block 2 executed"
"Small external script executed"
"Big external script executed"

While this maybe not a trouble for many sites, it could be trouble to some. I developed a function to fix this script loading order, assume that $scripts are all the scripts element inside content area:

//function to load scripts in correct execution order
  var scriptLoader = function ($scripts) {

      //==============Add the scripts back to the document, keeping execution order =============
      // scriptTree is a list of script elements (script blocks or external scripts).
      // For script blocks they are always executed according to order they are appended to the document.
      // For external scripts, they are executed according to order they are appended if they have async=false.
      // If we want some script blocks to execute after an external script, we add those blocks to a child array of
      // an external script, and wait after the external script "onload", then appending the blocks.
      var scriptTree = [],
                preScriptIsExternal;

      $scripts.each(function () {
          var $script = $(this), scriptText = $script.text(), scriptNode = document.createElement('script');

          if ($script.attr('src')) {
              //external script, add src attr to new script element defined above
              scriptNode.src = $script.attr('src');

              //if external script doesn't have async attribute, has to set this attr specifically to false
              //to preserve the execution order, same with order we append the external scripts to
              //document object later
              if (!$script.attr('async')) {
                  scriptNode.async = false;
              }
              else {
                  scriptNode.async = true;
              }
          } else {
              //a script block, add the content to the new script element
              scriptNode.appendChild(document.createTextNode(scriptText));
          }

          if (!preScriptIsExternal || scriptNode.src) {
              //If the previous script is NOT an external script then add current script (external or block) directly to the tree.
              //If the previous script is an external script, current script must be an external script to add it directly to the tree.
              scriptTree.push({ node: scriptNode, hasSrc: !!scriptNode.src });
          } else {
              //If the previous script is external and current script is block, then add the block to child array of previous script
              scriptTree[scriptTree.length - 1].inlines = scriptTree[scriptTree.length - 1].inlines || [];
              scriptTree[scriptTree.length - 1].inlines.push(scriptNode);
          }
          if (scriptNode.src) {
              preScriptIsExternal = true;
          }
      });

      $(scriptTree).each(function (index, value) {
          if (!value.hasSrc) {
              contentNode.appendChild(value.node);
          } else {
              if (value.inlines) {
                  var childScripts = value.inlines;
                  value.node.onload = function () {
                      $(childScripts).each(function (i, v) {
                          contentNode.appendChild(v);
                      });
                  }
              };
              contentNode.appendChild(value.node);
          }
      });
  };

OK, let's go and use our new ajaxify code in a brand new EPiServer CMS 8 Alloy website. By default, ajaxify use this selector to know where is the content area "'#content,article:first,.article:first,.post:first", so let's wrap the body part of Alloy site inside a <div id="content">, with my example scripts :)

And add all the needed scripts to our bundle

Then we are all done ? Almost, a first bug :), we have to modify ajaxify to trim new line chars from returned HTML

Then it worked as expected, the header and footer part of the site stay static ! Well, but we see that the menu in header has changed when new content come, how can it be ? Well, ajaxify is kind enough to find out our menu on the site, set the link whose href equal to new URL to be active. Here is the selector for the menu '#menu,#nav,nav:first,.nav:first' , and Alloy menu satisfied this selector, yeah!

If you browse to a video page on Alloy site "Alloy Track", we see that the page doesn't work, because there is a new script in header part supposed to be loaded then the new video page load, and ajaxify only execute scripts inside content area only !

I have improved this, if you add this comment  infront of any <script> element on your site, then those scripts, together with scripts inside content area, will be executed, in correct order !

Now the video page works like charm. This also enable many other scenarios to work, for example, there is a script in header needed to load for every page view, to load some random content to show (well, it's the Ads :-) ) . Applying this comment  in front of that script will make it works beautifully. In fact, applying this comment to any script element, everywhere on your HTML will make that script element to be executed again when new content is loaded. This also means that you can apply ajaxify plugin into your website with minimal modification of existing scripts on your site.

Here is the link to my example code: https://github.com/hoang-tranminh/AjaxifyWeb/ . Please let me know if you find any bugs, or you could use my modified ajaxify plugin in your projecs :) Thanks.

User get logged out after a new web application version is deployed to Azure Cloud

Thu, 01 Oct 2015 08:52:00 GMT

Recently I came across an Azure based web application project, and the team is having a strange bug that their end users always get logged out after every time they deploy a new version of the system on Azure cloud.

The application works perfect in the could with many front end servers, which are loaded balanced, and the team thought that they have followed guidelines how to build an web application to be hosted on Azure like not using session, applied distributed cache, used message service bus.

After some investigation we found out that we have not added a machine key to our web.config file for our application! This make all session cookie and authentication cookie of end users became invalid when we deployed a new version of the application, because these cookies are encrypted with the machine key and every time we deploy, we got new virtual machines and they have new machine keys.

I used to work in system that the load balancer was configured in non-sticky, round-robin (or preditive) mode, with real hardware servers. With platform like this, without adding a machine key to our config file, or making all the servers have same machine key in another way, the application will failed in the first deploy and we would recognize this mistake sooner :)

Azure cloud load balancer use sticky mode so the application works smoothly for end users during their sessions, and if Azure also create virtual machines inside a distribution set with same machine key automatically then it would be nice :)

The compiler failed with error code -1073741502 on an EPiServer web site

Wed, 09 Sep 2015 18:24:00 GMT

We have a client website in EPiSever CMS 6 R2 that have run smoothly for a long time, and after a recent release, sometime we got a call from editor saying that some tools, specially admin tools suddenly throw this strange error: The compiler failed with error code -1073741502

And some other tools or CMS function still run well. We got a workaround by restarting the application pool, this issue seem gone temporary. And from this error it really hard to know where to debug.

One strange thing is that this error happened random with different tools, even the tools that we don't make any code changes to it for months. And this problem usually appear in the morning, after a night of non-usage.

We have google a lot and found many comments, we tried to re-install dotNet framework 4.5.1 on servers, re-registered ASP.Net with IIS, deployed many old code versions to test, clean AS.NET temporary folder, changed app pool identity to Local Service etc. but this problem still occurs.

There one related link mentioned about the app pool user/identity use over a maximum allowed heap memory, we started to think this is a memory leak problem, because it seems to happen over some hours.

And looking careafully at our error log, we found an error that happened quite many time, there is a schedule job that automatically generate thumbnails for image, and it failed (throw an exception) with an image uploaded recently with special character in its name ! Further debug we found out that in this job the image file stream was not disposed properly when there's an exception.

Fix this thumbnail schedule job really fixed our problem ! Yay ! Hope this will help someone, someday :)

Linked dropdownlists custom property in EPiServer CMS 8 using Dojo widget, with EPiServer reststore, client module initilizer

Wed, 09 Sep 2015 13:13:00 GMT

Target readers: EPiServer developer that is new to EPiServer CMS 8, or new to developing custom property in EPiServer CMS with Dojo widgets. Or if you would like to know how to use a EPiServer reststore inside your widget, or to know a little bit further what is happening around your Dojo widget inside EPierver CMS edit mode, for example how EPiServer pass setting values to your custom property Dojo widget from server side, how EPiServer interact with your widget when saving/loading data.

Problem definition: I would like to create a custom property which will show two dropdownlists in EPiServer edit mode, selected value from first dropdown will change the values available for second dropdown without reloading current editing page. And selected values from first and second dropdown will be saved to database. This is useful when you have a list of countries to select first, then the second list will show its cities.

In my solution, the first dropdown will list all available categories in an Alloy EPiServer CMS 8 site, e.g "cat1", "cat1/sub11","cat2","cat2/sub21" etc. After an editor has selected a category from first list, the second dropdown will list all pages that belong to selected category, except the current editing page.

Technically on a high level, the solution include an EPiServer custom property definition on server side, a Dojo widget with some special API to work nicely with EPiSever edit mode, two EPiServer reststore to provide values for category and page dropdowns. All stuff are packed in a module project.

The code: now the real stuff. Let's define a library project named MultipleDropdownProperty, and call our project "multipledropdownproperty" module. We add reference to EPiServer.CMS.Core Nudget package to this project as below:

Next we should have an object to represent selected options from first and second dropdown list, the MultipleDropdownChoices and ChoiceModel class

    /// <summary>
    /// Object to represent selected options of two dropdowns
    /// </summary>
    public class MultipleDropdownChoices
    {
        public ChoiceModel Choice1 { get; set; }

        public ChoiceModel Choice2 { get; set; }
    }

    /// <summary>
    /// Represent an option in a dropdown
    /// </summary>
    public class ChoiceModel
    {
        public string Name { get; set; }
        public string Id { get; set; }
    }

After this we should define a custom property on server side, that expose MultipleDropdownChoices as its data type. We inherited from LongString property type and only do some minimal customization so that it expose MultipleDropdownChoices as data type to application code but inside it serialize MultipleDropdownChoices object to string to save to database. You can go here to know more about EPiServer custom property

 
[PropertyDefinitionTypePlugIn(
        DisplayName="Multiple dropdown", 
        Description="Show multiple dropdowns, values in second dropdown are dependent on selected values in first dropdown.")]
    public class MultipleDropDownProperty: PropertyLongString
    {
        /// <summary>
        /// Return MultipleDropdownChoices type to application code
        /// </summary>
        public override Type PropertyValueType
        {
            get
            {
                return typeof(MultipleDropdownChoices);
            }
        }

        /// <summary>
        /// Internally, we use Json to serialize & deserialize MultipleDropdownChoices value object to & from string
        /// </summary>
        public override object Value
        {
            get
            {
                var value = base.Value as string;
                if (value == null)
                {
                    return null;
                }
                return JsonConvert.DeserializeObject<MultipleDropdownChoices>(value);
            }
            set
            {
                if (value is MultipleDropdownChoices)
                {
                    base.Value = JsonConvert.SerializeObject(value);
                }
                else
                {
                    base.Value = value;
                }
            }
        }

        public override object SaveData(PropertyDataCollection properties)
        {
            //return a string object so that EPi can save it to database
            return LongString;
        }
    }

After this we should create a EditorDescriptor, which is used to tell EPiServer CMS that which Dojo widget will be used to edit our property in EPiServer CMS edit mode, it also used to send custom initialization parameters to our Dojo widget

[EditorDescriptorRegistration(
        EditorDescriptorBehavior= EditorDescriptorBehavior.Default, 
        TargetType= typeof(MultipleDropdownChoices),
        UIHint="Dropdowns")]
    public class MultipleDropdownEditorDescriptor: EditorDescriptor
    {
        public MultipleDropdownEditorDescriptor()
        {
            ClientEditingClass = "multipledropdownproperty.scripts.editor";
        }
   }

       protected override void SetEditorConfiguration(EPiServer.Shell.ObjectEditing.ExtendedMetadata metadata)
        {
            //we send some custom initialization parameters to our Dojo widget here!
            EditorConfiguration["choice1StoreName"] = "multipledropdownproperty.firstchoicedropdownreststore";
            EditorConfiguration["choice2StoreName"] = "multipledropdownproperty.secondchoicedropdownreststore";
            base.SetEditorConfiguration(metadata);
        }

We should set ClientEditingClass property to our Dojo widget class name, this class name follow physical folder structure to our Dojo widget's JS file. We should put all JS, and CSS files of our modules under "ClientResources" folder, we can customize structure below this folder. Let's create a JS file file "editor.js" for our Dojo widget and put it under "ClientResources/MultipleDropDown/Scripts" folder as image below.

We can add an default Alloy site to our solution, called "Sample" site, when we deploy our custom property module to this Sample site, we can copy DLL of our module to Sample site bin folder (or add reference to our module to Sample site), and copy content under "ClientResources" folder of our module to "ClientResources" folder of Sample site (we can use a post build command line to do this, such as :xcopy /r /y /s "$(SolutionDir)MultipleDropdownProperty\ClientResources\*.*" "$(SolutionDir)SampleSite\ClientResources\" )

To make Dojo framework inside EPiServer CMS edit mode know where to look for JS, CSS files of our module, we have to edit module.config file of Sample site as below:

 <module>
    <assemblies>
      <add assembly="SampleSite" />
      <!-- This adds the MultipleDropdownProperty assembly to the "default module" -->
      <add assembly="MultipleDropdownProperty" />
    </assemblies>
    <clientResources>
        <add name="epi-cms.widgets.base" path="Styles/Styles.css" resourceType="Style"/>
    </clientResources>
    <dojo>
        <paths>
          <add name="alloy" path="Scripts" />
          <!-- Add a mapping from module name "multipledropdownproperty" to "MultipleDropDown" sub folder of ~/ClientResources/ folder -->
          <add name="multipledropdownproperty" path="MultipleDropDown" />
        </paths>
    </dojo>
 </module>

We mapped module name "multipledropdownproperty" to a "MultipleDropDown" subfolder of "ClientResources" folder so from a class name "multipledropdownproperty.scripts.editor", Dojo can see the first part is module name, find "MultipleDropDown" folder, second part is sub folder "Scripts" under "MultipleDropDown", and "editor" is the name our Dojo widget JS file.

We have to add our custom property to a page type, as below:

 public class ArticlePage : StandardPage
    {
        [UIHint("Dropdowns")]
        [BackingType(typeof(MultipleDropDownProperty))]
        [Display(Name ="Page with a specific category", Description ="After select a category in first dropdown, we can select a page with that category in second dropdown")]
        public virtual MultipleDropdownChoices DropDowns { get; set; }
    }

The UIHint attribute value must match that on EditorDscriptor class. Now let's try to add some content to out Dojo widget file "editor.js":

define([
"dojo/_base/declare",
"dojo/on",
"dojo/store/Memory",
"dijit/_WidgetBase",
"dijit/_TemplatedMixin",
"dijit/_WidgetsInTemplateMixin",
"dijit/form/FilteringSelect",
"epi-cms/_ContentContextMixin",
 "epi/dependency"
], function (
    declare,
    on,
    Memory,
    _WidgetBase,
    _TemplatedMixin,
    _WidgetsInTemplateMixin,
    FilteringSelect,
    _ContentContextMixin,
    dependency
    ) {
    return declare("multipledropdownproperty.scripts.editor",
        [_WidgetBase, _TemplatedMixin, _WidgetsInTemplateMixin, _ContentContextMixin], {
           
            value: null,  //required for EPiServer CMS
            templateString: "Hello world!",
            constructor: function (params) {
                //"params" contained all settings sent from class MultipleDropdownEditorDescriptor at server side
                //"params" will be mixed in after this constructor is call and before postMixInProperties is called
            },
            postMixInProperties: function () {
                //called after constructor and after parameters are mixed in current widget instance
                //before DOM nodes are created

                //call the base implementation
                this.inherited(arguments);
            },
            postCreate: function () {
                //widgets has been render but not sub widgets in container node, 
                //not attached to DOM yet
               
                //call the base implementation
                this.inherited(arguments);
            },
            startup: function () {
                //all child widgets are created

                //call the base implementation
                this.inherited(arguments);
            },
            onChange: function (value) { }, //required for EPiServer CMS
            onBlur: function (e) { },      //required for EPiServer CMS
            onFocus: function (value) { }, //required for EPiServer CMS
           
            //custom setter for value attribute
            _setValueAttr: function (value) {
                //call the base so that can base widget can raise observable events.
                this._set("value", value);
            },
            //custom getter for value attribute
            _getValueAttr: function () {
                return this.value;
            },
            //returns wether our module is valid or not, required for EPiServer CMS
            isValid: function () {
                return true;
            }
        });
});

Above script is just the skeleton for our Dojo widget, let's look at different parts in this skeleton code quickly:

If you read this link you would understand define keyword used to define our module, using declare keyword to create a class named "multipledropdownproperty.scripts.editor" and it requires other modules like "dojo/on", "dojo/store/Memory" etc..We will explore more referenced module along the way.
if you read _WidgetBase, write Dojo widget, you would understand "dijit/_WidgetBase", "dijit/_TemplatedMixin", "dijit/_WidgetsInTemplateMixin" module references. You will learn widget life cycle methods (constructor, postMixInProperties, postCreate, startup methods), mixin concept, learn about custom getter and setter for attribute, using templateString attribute to render our widget.
You also can see that all setting values sent from server to our Dojo widget are available in "params" argument in constructor of the widget, this params also contain exising value, if any, of this property loaded from database. We usually do not do anything with this params argument in constructor because later it will be mixed in our widget, before postMinInProperties method is called.
Inside our Dojo widget, there are some API that is needed to make EPiServer CMS (the CMS) edit mode understand and work with our widget:

"value" attribute: our Dojo widget is used to edit value of a property in CMS edit mode, so CMS get and set this property value through "value" attribute of the widget. But CMS always access this attribute through standard "get" and "set" methods of Dojo widget, so we can define custom getter & setter methods to customize they way CMS access this value.
"onchange" event: this is also required by the CMS, used to notify CMS that our property value has changed
"onFocus" and "onBlur" events: required by the CMS, if our widget composed by more than one input fields (we have two dropdownlist). onFocus notify CMS that we start editing our property, and onBlur notify CMS that we complete editing our property. You can read source code of ""epi-cms/contentediting/SideBySideEditorWrapper" module to understand how CMS works with these events of our widget.

OK, now let's add some editing functionalities into our Dojo widget. First we have to define how to render our widget, using templateString atrribute (supported by "dijit/_TemplatedMixin" module), we can add following attributes to our widget

 
 
 templateString: "<div class=\"dijitReset dijitInputField dijitInputContainer dijitInline epi-resourceInputContainer\">" +
                              "<div><span class=\"dropdownLabel\">${choices1Label}: <span>" +
                                  "<input class=\"dropdown\" data-dojo-type=\"dijit/form/FilteringSelect\" data-dojo-attach-point=\"choices1\">" +
                              "</div>" +
                              "<div><span class=\"dropdownLabel\">${choices2Label}: <span>" +
                                  "<input  class=\"dropdown\" data-dojo-type=\"dijit/form/FilteringSelect\" data-dojo-attach-point=\"choices2\">" +
                              "</div>" +
                          "</div>",
choices1Label: "Categories:", //label for first drop down
 choices2Label: "Pages:", //label for second drop down

Above template uses two Dojo filteringSelect, so we reference "dijit/form/FilteringSelect" module, to pre-load this module, avoid error "parser returned unfilled promise (probably waiting for module auto-load), unsupported by _WidgetsInTemplateMixin. Must pre-load all supporting widgets before instantiation." We have also variable substitution in our template ${choices1Label}, so we have to define two more attributes choices1Label, choices2Label for our widget

We have two Dojo filteringSelect now, let's bind some data to them, we can create two EPiServer reststore, one to retrieve all categories in the system, one to get all pages with a specified category, and excluding editing page. You should read this to understand the API of JsonRest and Memory store of Dojo, EPiServer reststore is a JsonRest wrapped with some more functions like Observable and Throttle. We shall create two base classes as below:

  
    public abstract class FirstDropDownChoicesStoreBase : RestControllerBase
    {
        public virtual RestResult Get(int? id)
        {
            return base.Rest(GetChoices(id));
        }

        /// <summary>
        /// Should return all the choices for first drop down. 
        /// </summary>
        /// <returns></returns>
        public abstract IEnumerable<Choicemodel> GetChoices(int? id);

        public virtual RestResult Put(ChoiceModel entity)
        {
            throw new NotSupportedException();
        }

        public virtual RestResult Post(ChoiceModel entity)
        {
            throw new NotSupportedException();
        }

        public virtual RestResult Delete(int id)
        {
            return null;
        }
    }

    public abstract class SecondDropDownChoicesStoreBase : RestControllerBase
    {
        public virtual RestResult Get(string selectedFirstChoiceId, string currentContentId)
        {
            if (selectedFirstChoiceId != null &amp;&amp; currentContentId != null)
                return base.Rest(GetChoices(selectedFirstChoiceId, currentContentId));
            else
                return base.Rest(new List<choicemodel>());
        }

        /// <summary>
        /// Should return all the choices based on selected value of first drop down and current editing content 
        /// </summary>
        /// <returns></returns>
        public abstract IEnumerable<Choicemodel> GetChoices(string selectedFirstChoiceId, string currentContentId);

        public virtual RestResult Put(ChoiceModel entity)
        {
            throw new NotSupportedException();
        }

        public virtual RestResult Post(ChoiceModel entity)
        {
            throw new NotSupportedException();
        }

        public virtual RestResult Delete(int id)
        {
            return null;
        }
    }

Implementations of these base classes are also quite straight forward:

[RestStore("firstchoicedropdownreststore")]
    public class FirstChoiceDropdownRestStore : FirstDropDownChoicesStoreBase
    {
        private readonly CategoryRepository _categoryRepository;
        public FirstChoiceDropdownRestStore(CategoryRepository categoryRepository)
        {
            _categoryRepository = categoryRepository;
        }

        /// <summary>
        /// Build a list of categories, like "cat1","cat1/sub11","cat2","cat2/sub21"
        /// </summary>
        /// <param name="items"></param>
        /// <param name="parent"></param>
        /// <param name="prefix"></param>
        private void BuildCategoryTree(List<ChoiceModel> items, Category parent, string prefix)
        {
            var newPrefix = (prefix ==string.Empty ? string.Empty: (prefix + "/")) + parent.Name;
            items.Add(new ChoiceModel() { Name = newPrefix, Id = parent.ID.ToString() });
            
            foreach (var cat in parent.Categories)
            {
                if (cat.Available && cat.Selectable)
                    BuildCategoryTree(items, cat, newPrefix);
            }
        }

        public override IEnumerable<ChoiceModel> GetChoices(int? id)
        {
            var choicesList = new List<ChoiceModel>();
            foreach (var cat in _categoryRepository.GetRoot().Categories)
            {
                BuildCategoryTree(choicesList, cat, string.Empty);
            }
            return choicesList;
        }
    }

[RestStore("secondchoicedropdownreststore")]
    public class SecondChoiceDropdownRestStore: SecondDropDownChoicesStoreBase
    {
        private CategoryRepository _categoryRepository;
        private ContentSearchHandler _contentSearchHandler;
        private TemplateResolver _templateResolver;
        public SecondChoiceDropdownRestStore(CategoryRepository categoryRepository, 
            ContentSearchHandler contentSearchHandler,
            TemplateResolver templateResolver)
        {
            _categoryRepository = categoryRepository;
            _contentSearchHandler = contentSearchHandler;
            _templateResolver = templateResolver;
        }

       
        public override IEnumerable<ChoiceModel> GetChoices(string selectedFirstChoiceId, string currentContentId)
        {
            var catId = -1;
            Category cat = null;
            var currentContent = ContentReference.EmptyReference;
            if (int.TryParse(selectedFirstChoiceId, out catId))
            {
                cat = _categoryRepository.Get(catId);
            }

            if (catId == -1 || cat == null)
            {
                return new List<ChoiceModel>();
            }

            ContentReference.TryParse(currentContentId, out currentContent);

            var resultList = new List<ChoiceModel>();

            var searchHanler = ServiceLocator.Current.GetInstance<SearchHandler>();

            var query = new CategoryQuery(LuceneOperator.OR);
            query.Items.Add(cat.ID.ToString());

            var results = searchHanler.GetSearchResults(query, 1, int.MaxValue);
            resultList.AddRange(results.IndexResponseItems.SelectMany(CreateHitModel));

            if (currentContent != ContentReference.EmptyReference)
                resultList.RemoveAll(i => i.Id == currentContent.ID.ToString());

            return resultList;
        }

        private IEnumerable<ChoiceModel> CreateHitModel(IndexResponseItem responseItem)
        {
            var content = _contentSearchHandler.GetContent<IContent>(responseItem);
            if (content != null && HasTemplate(content) && IsPublished(content as IVersionable))
            {
                yield return CreatePageHit(content);
            }
        }

        private bool HasTemplate(IContent content)
        {
            return _templateResolver.HasTemplate(content, TemplateTypeCategories.Page);
        }

        private bool IsPublished(IVersionable content)
        {
            if (content == null)
                return true;
            return content.Status.HasFlag(VersionStatus.Published);
        }

        private ChoiceModel CreatePageHit(IContent content)
        {
            return new ChoiceModel
            {
                Name = content.Name,
                Id = content.ContentLink.ID.ToString()
            };
        }
    }

We use CategoryRepository, SearchHandler, CategoryQuery, ContentSearchHandler classes to do our job in above implementation, the code should be self-explanatory. We have two reststore on server side now, how to make them to be available on the client side for our widget to use ? we should use a client initialization module for our module and register our stores there, like below:

define([
// Dojo
    "dojo",
    "dojo/_base/declare",
//CMS
    "epi/_Module",
    "epi/dependency",
    "epi/routes"
], function (
// Dojo
    dojo,
    declare,
//CMS
    _Module,
    dependency,
    routes
) {

    return declare("multipledropdownproperty.scripts.moduleinitializer", [_Module], {
        // summary: Module initializer for the MultipleDropdownProperty module.

        initialize: function () {

            this.inherited(arguments);

            var registry = this.resolveDependency("epi.storeregistry");

            //Register the stores
            var firstStore = registry.create("multipledropdownproperty.firstchoicedropdownreststore", this._getRestPath("firstchoicedropdownreststore"));
            
            var secondStore = registry.create("multipledropdownproperty.secondchoicedropdownreststore", this._getRestPath("secondchoicedropdownreststore"));
        },

        _getRestPath: function (name) {

            //we use the default module area named "app" of EPiServer Shell module
            return routes.getRestPath({ moduleArea: "app", storeName: name });
        }
    });
});

We put this ModuleInitializer.js in same folder with editor.js, then we have to modify module.config this time to tell CMS to load this initilizer after the default CMS module, we also create a simple CSS file for our module under "ClientResources/MultipleDropDown/Styles/styles.css" and register this in module.config. Final module.config look like:

<?xml version="1.0" encoding="utf-8"?>
<module>
    <assemblies>
      <add assembly="SampleSite" />
      <!-- This adds the MultipleDropdownProperty assembly to the "default module" -->
      <add assembly="MultipleDropdownProperty" />
    </assemblies>
    <clientResources>
      <add name="epi-cms.widgets.base" path="Styles/Styles.css" resourceType="Style"/>
      <add name="multipledropdownpropertystyle" path="MultipleDropDown/styles/styles.css" resourceType="Style"/>
    </clientResources>
    <dojo>
        <paths>
          <add name="alloy" path="Scripts" />
          <!-- Add a mapping from module name "multipledropdownproperty" to "MultipleDropDown" sub folder of ~/ClientResources/ folder -->
          <add name="multipledropdownproperty" path="MultipleDropDown" />
        </paths>
    </dojo>
  <clientModule initializer="multipledropdownproperty.scripts.moduleinitializer">
    <moduleDependencies>
      <add dependency="CMS" type="RunAfter" />
    </moduleDependencies>
    <requiredResources>
      <add name="multipledropdownpropertystyle" />
    </requiredResources>
  </clientModule>
</module>

Now we get references to the stores in our widget and start using them in our Dojo widget:

postMixInProperties: function () {
                //called after constructor and after parameters are mixed in current widget instance
                //before DOM nodes are created

                //call the base implementation
                this.inherited(arguments);

                //get setting values from server
                if (this.params.choice1StoreName) {
                    this.choices1StoreName = this.params.choice1StoreName;
                    var registry = dependency.resolve("epi.storeregistry");
                    this.choices1Store = registry.get(this.choices1StoreName);
                }
                if (this.params.choice2StoreName) {
                    this.choices2StoreName = this.params.choice2StoreName;
                    var registry = dependency.resolve("epi.storeregistry");
                    this.choices2Store = registry.get(this.choices2StoreName);
                }
            },

In postCreate method, the dropdowns are available so we actually bind the stores to the dropdowns:

postCreate: function () {
                //widgets has been render but not attached to DOM yet

                this.choices1.store = this.choices1Store;
                var widget = this;
                
                //we query all items of the store from server side (probably take some time)
                //then data bind the first dropdown,
                this.choices1.store.query().then(function () {

                    //data bind the first dropdown
                    widget.choices1.startup();
                    var currentValue = widget.value;

                    if (currentValue.choice1.id && widget.choices1) {
                        widget.choices1.set('value', currentValue.choice1.id);

                        if (currentValue.choice2.id && widget.choices2) {
                            //query data for second dropdown based on first selection, then bind this data to second dropdown
                            widget._setupStoreForSecondDropdown(currentValue.choice1.id, currentValue.choice2.id);
                        }
                    }
                });
               
                //call the base implementation
                this.inherited(arguments);
            },
 _setupStoreForSecondDropdown: function (selectedFirstChoiceId, selectedId) {
                var data = [];
                var widget = this;
                var firstItem = null;
                var firstChoiceId = selectedFirstChoiceId;
                var sId = selectedId;

                //query data for second dropdown based on first selection, then bind this data to second dropdown
                this.choices2Store.query({ selectedFirstChoiceId: firstChoiceId, currentContentId: this._currentContext.id }).then(function (results) {
                    results.forEach(function (item, i) {
                        data.push(item);
                        if (i == 0) firstItem = item;
                    });

                    if (firstItem != null) {

                        //after querying to get items from server side, put them in a
                        //memory store to bind to second dropdown
                        var store2 = new Memory({ data: data });
                        widget.choices2.store = store2;
                        widget.choices2.startup();

                        var id = sId ? sId : firstItem.id;

                        //set first item or selected item from param to be selected!
                        if (!widget.choices2.get('value')) {
                            widget.choices2.set('value', id);
                        }
                    } else {
                        //if found no items from server for 2nd dropdown
                        widget._secondDropdownChanged();
                    }
                });
            },

When we mixin "_ContentContextMixin " module into our widget, we can access the current editing content in our widget like this this._currentContext.id

We have more code in Dojo widget to handle focus, blur, raise onChange event. You can download the full source code of this project here: https://github.com/hoang-tranminh/MultipleDropdownProperty. You can login to edit mode by account "hoang/Abc123456" when running my project.

We can extend this example using PropertySettings to send setting value to our Dojo widget, to support on page editing etc. Thanks for reading.