Blog posts by Duong Nguyen

Blog posts by Duong Nguyen2014-01-20T11:22:24.0000000Zhttps://world.optimizely.com/blogs/Duong-Nguyen/ Optimizely World Country-Region drop down lists in All properties modeI have gotten quite a few questions from both the forum and developer support regarding how to populate a drop down list depends on value of another drop down list in All Properties mode. In a recent blog post, my colleague Linus Ekström has mentioned a possible solution by using FormContainer to create a custom editor for the country/region block. In this post, I will present a working example using another approach which in my opinion is more lightweight and more conformal to the architecture behind the All Properties mode. <h1>All Properties mode overview</h1> In EPiServer 7, All Properties mode (formerly know as Form editing mode) is built upon the object editing framework which was designed to be highly extensible and customizable. <div> <a href="/link/31bd9d5288d34882993ac3ff5a722d7c.png"><img style="border: 0px currentcolor; display: inline; background-image: none;" title="ObjectEditing" src="/link/4a6be5084408445d8dc8ba5bba308fcc.png" alt="ObjectEditing" width="484" height="561" border="0" /></a> </div> The very core server side part of the Object Editing framework is the Metadata provider which inspect the edited object’s and return its metadata. We have different metadata providers for different kinds of object. For example, the annotation based metadata provider for plain C# objects or the content metadata provider for EPiServer’s content objects. All the metadata providers allow developers to extend the generated metadata by implementing metadata extenders. You might have been familiar with editor descriptors which basically are metadata extenders. On the client side, FormContainer is the central piece. It responsible for creating the entire UI from the retrieved metadata via the Widget Factory. The created structure consists of not only the editor widgets but also the layout containers. The FormContainer does not care how are the widgets arranged and how do they interact with each other. Those responsibilities are delegated to the layout containers. We have 2 types of layout containers: object container and group container. For a better imagination, please have a look at the following examples: <a href="/link/5cfe338a4cc746a580c0fcd6c9f24619.png"><img style="margin-right: auto; margin-left: auto; float: none; display: block; background-image: none;" title="containers1" src="/link/5184dadaf8b54a63a4040eb2955000a7.png" alt="containers1" width="448" height="224" border="0" /></a> Example 1: Layout containers for pages and shared blocks. Object container is the tab container and group containers are the tab pages <a href="/link/e38e7499e4f5489c8e99013da9b25643.png"><img style="margin-right: auto; margin-left: auto; float: none; display: block; background-image: none;" title="containers2" src="/link/ad9b3cc69fe1434e8eaf0e9a31515358.png" alt="containers2" width="450" height="210" border="0" /></a> Example 2: Layout containers for block properties (complex properties). Both object container and group containers are a simple flow container with a title bar. The key point here is that we can configure which container type to be used for both object level and group level. This can be done by changing some certain settings in a metadata extender. <h1>The country-region dropdown lists problem</h1> In this section, I will go through an example on how to re-populate the region drop down list according to the selected country. <a href="/link/3fe8f7fc3cda4475ae14373441f8f490.png"><img style="margin-right: auto; margin-left: auto; float: none; display: block; background-image: none;" title="country-region" src="/link/0fda58701959462b9bdd3f8c588020c4.png" alt="country-region" width="502" height="106" border="0" /></a> <h2>Location block</h2> Let’s start with a block type consists of 2 properties Country and Region. <pre class="language-csharp"><code>[ContentType(AvailableInEditMode=false)] public class LocationBlock : BlockData { public virtual string Country { get; set; } public virtual string Region { get; set; } } </code></pre> Note that we mark the content type as not available in edit mode since we will only use the block type for complex properties. <pre class="language-csharp"><code>[ContentType] public class TestPage : PageData { public virtual LocationBlock Location { get; set; } } </code></pre> In the edit mode we can see 2 text boxes. To tell EPiServer to use dropdown lists instead, we need create selection factories and assign them to the properties using the SelectOne attribute. <pre class="language-csharp"><code>class Country : ISelectItem { public string CountryCode { get; set; } public string Name { get; set; } public string Text { get { return Name; } } public object Value { get { return CountryCode; } } } class Region : ISelectItem { public string CountryCode { get; set; } public string RegionCode { get; set; } public string Name { get; set; } public string Text { get { return Name; } } public object Value { get { return String.Format("{0}-{1}", CountryCode, RegionCode); } } } class CountrySelectionFactory : ISelectionFactory { public IEnumerable<ISelectItem> GetSelections(ExtendedMetadata metadata) { return new Country[] { new Country() { CountryCode = "US", Name = "United States" }, new Country() { CountryCode = "SE", Name = "Sweden" } }; } } class RegionSelectionFactory : ISelectionFactory { public IEnumerable<ISelectItem> GetSelections(ExtendedMetadata metadata) { return new Region[] { new Region() { CountryCode = "US", RegionCode = "NY", Name = "New York" }, new Region() { CountryCode = "US", RegionCode = "CA", Name = "California" }, new Region() { CountryCode = "SE", RegionCode = "AB", Name = "Stockholm" }, new Region() { CountryCode = "SE", RegionCode = "O", Name = "Västra Götaland" } }; } } </code></pre> <pre class="language-csharp"><code>[ContentType(AvailableInEditMode=false)] public class LocationBlock : BlockData { [SelectOne(SelectionFactoryType = typeof(CountrySelectionFactory))] public virtual string Country { get; set; } [SelectOne(SelectionFactoryType = typeof(RegionSelectionFactory))] public virtual string Region { get; set; } } </code></pre> So far so good. We have got 2 drop down list for our properties. However they are not inter-connected so user can still chose country as Sweden and region as California! Make no sense? <h2>FilterableSelectionEditor</h2> When we mark the property with SelectOne attribute, it will use the built-in widget SelectionEditor. Unfortunately, this widget doesn’t support filtering the available options. We need to extend it a little bit: <pre class="language-csharp"><code>define([ "dojo/_base/declare", "dojo/_base/array", "epi-cms/contentediting/editors/SelectionEditor" ], function ( declare, array, SelectionEditor ) { return declare([SelectionEditor], { _allOptions: null, filter: null, _setOptionsAttr: function (options) { // summary: set the options this._allOptions = options; this.inherited(arguments, [array.filter(options, this.filter || function () { // return all options if no filter function provided. return true; }, this)]); }, _setFilterAttr: function (filter) { // summary: set the option filter function this._set("filter", filter); this.set("options", this._allOptions); } }); });</code></pre> <h2>Wrap everything up</h2> Let’s look at the diagram again. There are 2 green boxed. They are the things that we need to extend to achieve what we want. First, we need to create a custom group container for our block, then replace the default one using an editor descriptor. By default, in All properties mode, the group containers are "epi/shell/layout/SimpleContainer". We just extend this container, override the addChild method and hook up the widget we are interested in. Add a new file named LocationBlockContainer under the ClientResources folder. <pre class="language-csharp"><code>define([ "dojo/_base/declare", "dojo/_base/lang", "epi/shell/layout/SimpleContainer" ], function ( declare, lang, SimpleContainer ) { return declare([SimpleContainer], { countryDropdown: null, regionDropdown: null, addChild: function (child) { // Summar: Add a widget to the container this.inherited(arguments); if (child.name.indexOf("country") >= 0) { // If it's the country drop down list this.countryDropdown = child; // Connect to change event to update the region drop down list this.own(this.countryDropdown.on("change", lang.hitch(this, this._updateRegionDropdown))); } else if (child.name.indexOf("region") >= 0) { // If it's the region drop down list this.regionDropdown = child; // Update the region drop down this._updateRegionDropdown(this.countryDropdown.value); } }, _updateRegionDropdown: function (country) { // Summary: Update the region drop down list according to the selected country // Clear the current value this.regionDropdown.set("value", null); // Set the filter this.regionDropdown.set("filter", function (region) { // Oops, the region code is prefixed with country code, for the simplicity return region.value.indexOf(country) === 0; }); } }); });</code></pre> And tell EPiServer that we want to use it for the LocationBlock: <pre class="language-csharp"><code>[EditorDescriptorRegistration(TargetType = typeof(LocationBlock))] public class LocationBlockEditorDescriptor : EditorDescriptor { public override void ModifyMetadata(Shell.ObjectEditing.ExtendedMetadata metadata, IEnumerable<Attribute> attributes) { base.ModifyMetadata(metadata, attributes); metadata.Properties.Cast<ExtendedMetadata>().First().GroupSettings.ClientLayoutClass = "alloy/LocationBlockContainer"; } } </code></pre> Last but not least, we need to indicate that we will use the FilterableSelectionEditor for the Region property. <pre class="language-csharp"><code>[ClientEditor(ClientEditingClass = "alloy/editors/FilterableSelectionEditor", SelectionFactoryType = typeof(RegionSelectionFactory))] public virtual string Region { get; set; } </code></pre> And we are done! <h1>Conclusion</h1> I hope that this small example will help to explain a little bit more on how the Edit mode is built in EPiServer. It’s not a cake walk to extend at the moment but doable with not so much trouble. We will hopefully improve the public APIs and probably add more convenient methods, extension points, … in the future release to make it easier and more fun. Happy extending and overriding!2014-01-20T11:22:24.0000000Z

Blog post

Custom views and plugin areas in EPiServer 7.5<h1>Create custom views</h1> You might have already known that in EPiServer 7.5, it is possible to create custom views in Edit mode beside the built-in “On page edit” and “All properties” views. In the simplest practice, all you need is to create a widget which represent your custom view and register it on the server side using a descriptor class. In the below example, I will create a very simple view which simply displays the text “My very simple edit view”. The widget looks like this: <pre class="language-csharp"><code>define([ "dojo/_base/declare", "dijit/_WidgetBase", "dijit/_TemplatedMixin" ], function ( declare, _WidgetBase, _TemplatedMixin ) { return declare([_WidgetBase, _TemplatedMixin], { templateString: "<div>My very simple edit view</div>", updateView: function (viewInfo, context) { } }); });</code></pre>           Be noticed that the widget should have an updateView method, which is called when the view is loaded or updated due to context change. And here is the view configuration on the server side: <pre class="language-csharp"><code>using EPiServer.Core; using EPiServer.ServiceLocation; using EPiServer.Shell; namespace EPiServer.Templates.Alloy.Business.ViewConfigurations { [ServiceConfiguration(typeof(ViewConfiguration))] public class SummaryView : ViewConfiguration<IContentData> { public SampleView() { Key = "sampleView"; Name = "Sample View"; Description = "Very simple view"; IconClass = "epi-iconForms"; ControllerType = "alloy/views/SampleView"; } } }</code></pre> Nothing special! You provide a key, a name, a description, and an icon class for your view. The single interesting point here is the property ControllerType whose value is the module id of the widget mentioned above. You may ask why is it called Controller type while we are creating a view. The answer is that the Edit UI is design toward the MVC pattern where you have a controller widget which in turn will decide the view widget to load. In this example, for the simplicity, the controller widget does not care about the view widget as it always display the same text. Here is what we get: <a href="/link/7677a181c4534796badceb5522bfef50.png"><img style="margin-right: auto; margin-left: auto; float: none; display: block; background-image: none;" title="blog-1" src="/link/a2477cfe6bca43148a86644166376f8b.png" alt="blog-1" width="244" height="144" border="0" /></a> The Edit mode switch button is now a drop down menu where you can select the brand new Sample View from. <a href="/link/c7df623b4bfa421b860acbeaf0495b20.png"><img style="margin-right: auto; margin-left: auto; float: none; display: block; background-image: none;" title="blog-2" src="/link/72b60158fded4289adc8d78f7ef6ab20.png" alt="blog-2" width="506" height="222" border="0" /></a> And the simple view is showing up. <h1>Plug the custom view to a pluggable area</h1> When you have so many view, the drop down many may get crowded. Also, you may want to add your view to some other places, for instance the Tool button under the Content Settings Header, or the Publish/Option menu. This feature has unfortunately missed the train in EPiServer 7.5, but with a little bit effort, we can achieve it. If you inspected the ViewConfiguration class, you would have seen 2 properties: HideFromViewMenu and PlugInAreas. Let’s modify our sample view a bit. <pre class="language-csharp"><code>using EPiServer.Core; using EPiServer.ServiceLocation; using EPiServer.Shell; namespace EPiServer.Templates.Alloy.Business.ViewConfigurations { [ServiceConfiguration(typeof(EPiServer.Shell.ViewConfiguration))] public class SampleView : ViewConfiguration<IContentData> { public SampleView() { Key = "sampleView"; Name = "Sample View"; Description = "A stupid simple view"; ControllerType = "alloy/views/SampleView"; IconClass = "epi-iconForms"; HideFromViewMenu = true; PlugInAreas = new string[] { "toolButton" }; } } }</code></pre> In this configuration, we want to hide the view from the drop down menu and state that we want to plug our view to the Tool button. However, no magic has happened yet. To make it happened, I have created a simple command provider which inspects all the views available to the current content context and are configured to the specified plugin area. You just need to configure your plugin area in the client module initializer. <pre class="language-csharp"><code>commandregistry.registerProvider("epi.cms.contentdetailsmenu", new AvailableViewsCommandProvider({ plugInArea: "toolButton" })); </code></pre> The above method call registers a AvailableViewsCommandProvider with plugInArea “toolButton” to the global command provider of the Tool button whose key is “epi.cms.contentdetailmenu”. Here is the result: <a href="/link/61fead2520444d8c91fd461d0083812e.png"><img style="margin-right: auto; margin-left: auto; float: none; display: block; background-image: none;" title="blog-3" src="/link/cbbeaa9a1f084127acf7a9d5acdda1ee.png" alt="blog-3" width="244" height="186" border="0" /></a> I will let you discover the command provider by yourself. It will give you a better understanding on how the command provider/consumer pattern works in EPiServer as well as how to get informed when a view is loaded. I hope it will help you to extend the awesome EPiServer Edit UI to fit your customer’s requirements. Happy coding! Download the code for the command provider: <a href="/link/0e164517bd974d9e8d1d9e4a90309e51.zip" target="_blank">ViewCommandProvider.zip</a>. <div id="scid:0767317B-992E-4b12-91E0-4F059A8CECA8:b326280e-3410-447c-afa3-edd3b41239d6" class="wlWriterEditableSmartContent" style="margin: 0px; padding: 0px; float: none; display: inline;">Technorati Tags: <a href="http://technorati.com/tags/view" rel="tag">view</a>,<a href="http://technorati.com/tags/edit+mode" rel="tag">edit mode</a>,<a href="http://technorati.com/tags/EPiServer+7.5" rel="tag">EPiServer 7.5</a>,<a href="http://technorati.com/tags/pluggability" rel="tag">pluggability</a></div>2013-12-06T15:53:23.0000000Z

Blog post