• The bounds factor – proper use of Enum type guarantee that the selected value will fall within the constraints of the allowed value set.
• The ability to treat Enums as flags (and compound them into flag sets) as well as a one-of selector.
• The ease of use and potentially complete separation of the “Enum value” from the underlying machine type representation that ensures the most efficient memory usage.

Surprisingly enough EPiServer as it stands right now does not have an easy facility to turn Enums into properties. To give credit where credit is due, the EPiServer framework provides a nice surrogate that mimic that behaviour to a degree. The relevant property types are:

• PropertyAppSettingsMultiple  – which “creates check boxes with options that are defined in the AppSettings section in web.config. The name of the property should match the key for the app setting.”
• PropertyAppSettings  – which “creates a drop down list with options that are defined in the AppSettings section in web.config. The name of the property should match the key for the app setting.”

You quickly realize though that the properties have some limitations that makes their use a bit less compelling:

• The properties are not strongly typed
• The property entry in AppSettings section has to have the name that matches the property name on the page.
• It’s rather poorly documented, Other than relating to this blog entry or Erik’s post documenting it I could not find any other examples on how to use them. (but then again, who needs docs really when we have Reflector)
• You cannot have the very same property duplicated on the page since you can only have a single property of a given name per page. So you need to have multiple entries in AppSettings that match the name of each of those properties on your pages. I know… semantics but still…
• You are working on strings rather than enums (Did i mention it’s not type safe?)
• The values in the AppSettings are stored in a somewhat DLS-y manner (consecutive options are separated from each other with the ‘|’ character, the name and the value are separated with a ‘;’, for example: <add key = "RegionId" value="First Option;Option1|Default Option;Option2|Disabled Option;Option3" /> ) and I have had on an occasion entered a string there that caused the server to crash.
• The values are not translatable, or at least I could not find how to do it and any Reflector digging rendered no results either.

The solution to the problem:

The solution that the blog post describes is:

• Type safe
• Supports UI localization
• Easy to use in your custom implementation
• Flexible in allowing you to switch between the Enum being multi-choice or a single choice solution
• fully defined in the code – no need to modify web,config.

All you need to do to create your own custom Enum property is declare it.

using Cognifide.EPiserverControls.EnumDropDown;

[PageDefinitionTypePlugIn(DisplayName = "Sample Enum Property")]
public class SampleProperty : PropertyEnumSelector<MySampleEnum>
{
}

That’s it, really!

Now if you want to customize it; obviously you need to provide the information for the property to work with. But let’s stop for a while and think, where does that information belong?

• The property should worry about the mechanics of editing and the tediousness of persistence of the edited value, it clearly is not the place to specify the link between the Enum type and its human friendly drop down text.
• Web.config is for settings, not for describing content types and definitely not to enforce the property names.
• So where should the metadata around your Enum type be? How about we put it around the Enum type itself?

[Flags]
public enum MySampleEnum
{
  [ValueVisualisation(Name="First Option", LanguageKey="/enum/first")]
  Option1,

  [ValueVisualisation(Name="Default Option", Selected=true, LanguageKey="/enum/second")]
  Option2,

  [ValueVisualisation(Name="Disabled Option", Enabled=false, LanguageKey="/enum/disabled")]
  Option3,

  [ValueVisualisation(Name="Hidden Option", Hide=true, LanguageKey="/enum/hidden")]
  Option4,

  [ValueVisualisation(Name="Fifth Option", LanguageKey="/enum/fifth")]
  Option5,

}

What does all that do?

The property using an Enum described this way will look the following way in EPiServer:

Let’s get into the what’s happened here as there’s more than catches the eye.

As you can see the enum values are named like they are in the attributes describing them, Default option is selected just like you could have expected by looking at the Selected=true in its attribute. The Enabled=false in the Disabled option results in an option that cannot be changed. The unchangeable option can be both unselected or selected by default. You may want to disable some deprecated options but still show them in the UI as a legacy but for some reason you might not want users to be able to change their value. Option4 is clearly missing, which is intended and specified by the Hide=true, as you might want to hide options that have been removed form the UI and on the same time you don’t want to loose compatibility with a legacy API that uses the option.

Also There is one thing about the first option on the list – it’s translated! The mechanism to specify the translation is based on the standard EPiServer localization files that you can find in the “lang” folder in your typical EPiServer installation. The Translation for the property looks like the following

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<languages>
  <language name="English" id="en">
    <enum>
      <first>First Option Translated EN</first>
    </enum>
  </language>    
</languages>

so you see the value will take its translation key from the LanguageKey="/enum/first".

Ok, so we have the PropertyAppSettingsMultiple replacement, but what about PropertyAppSettings?

So here I reach the place where I am not 100% certain whether I took the proper path but I am sure I will hear about it if I didn’t :) The place where the property determines if it’s supposed to allow for multi selection or not is whether the Enum is marked with the [Flags] attribute. Obviously Flags mean that the property is a form of a bit flag and should be able to allow the user to flip the bits independently rather than being the “one-of” type. So once you remove the [Flags] form your enum you’re going to see it rendered the following way:

But hey, it’s not a one way trip, if you decide that you want the enum rendered in another type of property and force the opposite behaviour you can always override it in the derived property like follows:

    [PageDefinitionTypePlugIn(DisplayName = "Sample Enum Property Checklist")]
    public class SamplePropertyChecklist : PropertyEnumSelector<MySampleEnum>
    {
        static SamplePropertyChecklist()
        {
            MultiSelectEnum = true;
        }
    }

so even if you think my usage of [Flags] is faulty, the damage can be undone :)

Ok, but what about the enums that we have no control over – like enums form libraries. Obviously cannot retrofit attributes into them. Well, true but we still can have all of the control over the property.

Let’s assume for a moment that this is our legacy enum:

public enum MySampleLegacyEnum
{
  Option1,
  Option2,
  Option3,
  Option4,
  Option5,
}

You can just do nothing and simply use it in the property but the UI will display the not so nice Option1… names. That can be easily fixed – Again, specifying translation is the easiest way of achieving that goal. An xml for that enum would look like follows:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<languages>
  <language name="English" id="en">
    <MySampleLegacyEnum>
      <Option1>First Option</Option1>
      <Option2>Default Option</Option2>
      <Option3>Disabled Option</Option3>
      <Option4>Hidden Option</Option4>
      <Option5>Fifth Option</Option5>
    </MySampleLegacyEnum>
  </language>  
</languages>

The default values can be added by retrofitting the “DefaultValues” list with the elements that you want selected in the scenario where the property is first displayed for editing. You can also modify the inherited AvailableItems list to set the rest of the properties otherwise adjustable by the attributes.

Following is a sample of such retrofitted rules to match our original attribute-defined-enum.

[PageDefinitionTypePlugIn(DisplayName = "Sample Legacy Enum Property")]
public class SampleProperty : PropertyEnumSelector<MySampleLegacyEnum>
{
    static SampleProperty()
    {
        MultiSelectEnum = true;

        // Make Option2 a default selected value
        DefaultValues.Add(MySampleLegacyEnum.Option2.ToString());
        AvailableItems.Where(p => p.Value == MySampleLegacyEnum.Option2.ToString()).First().Selected = true;

        //Disable selection of Option3
        AvailableItems.Where(p => p.Value == MySampleLegacyEnum.Option3.ToString()).First().Enabled = false;

        //Remove hidden Option4
        AvailableItems.RemoveAll(p => p.Value == MySampleLegacyEnum.Option4.ToString());
    }
}

The [code for the EnumProperty] as well as [the compiled binaries] are available as Open Source and you can incorporate it in your projects as long as the Cognifide namespace is used for the code.

What do you think? Is that going to be useful for you?

for the most part the syntax for the call is equivalent to what is was before so go to my previous article regarding that (check out the old article for details). What I’ve added this time around is:

• the @PropertyName can be declared as ‘%’ if you want to look in all property names
• @PropertyType can be –1 if you want to look in all property types otherwise you need to specify type id (this has changed from type name before due to database schema changes)
• additionally this version of the stored proc will only look in the Master language Branch, so it will work for the single language pages and for multi-language but for language agnostic properties. (should you require the language to be variable the change is pretty simple – I can send you the updated version by email.

/****** Object:  StoredProcedure [dbo].[PagedSearch]    Script Date: 07/07/2009 12:18:10 ******/
IF  EXISTS (SELECT * FROM sys.objects WHERE object_id = OBJECT_ID(N'[dbo].[PagedSearch]') AND type in (N'P', N'PC'))
DROP PROCEDURE [dbo].[PagedSearch]
GO

CREATE Procedure PagedSearch
    @Condition varchar(1024),
    @PropertyName varchar(1024),
    @PropertyType int,
    @PageSize int,
    @PageNumber int,
    @Offset int
AS
BEGIN

    DECLARE @RowStart int
    DECLARE @RowEnd int

    SET @RowStart = @PageSize * @PageNumber + @Offset;
    SET @RowEnd = @RowStart + @PageSize + @Offset;

    WITH PageRefs AS
        (SELECT page.pkID as PageId,
            ROW_NUMBER() OVER (ORDER BY pageLang.StartPublish DESC) as RowNumber
            FROM tblPage page, tblProperty propValue, tblPageDefinition propDef, tblPageLanguage pageLang
            WHERE page.pkID = propValue.fkPageID
                AND page.fkMasterLanguageBranchID = pageLang.fkLanguageBranchID
                AND page.pkID = pageLang.fkPageID
                AND propValue.fkPageDefinitionID = propDef.pkID
                AND (@propertyType = -1 or propDef.fkPageDefinitionTypeID = @propertyType) -- is proper type
                AND propDef.Searchable = 1 -- the property is searchable
                AND propValue.String like @Condition -- contains facets
                AND propDef.[Name] like @PropertyName) -- property of proper name
    SELECT PageId
        FROM PageRefs
        WHERE (RowNumber Between @RowStart and @RowEnd) or (@PageSize = 0);
END
GO

However… looking how the schema has changed over time, I am not convinced this approach is really the best one for someone who is not prepared to deal with the changes (e.g. you better be able to change the stored procedure based on the schema changes – or bribe me with pizza and beers for updates :) ).

Additionally this procedure only searches for properties that store their value in Short string field. To make it look into long string you need to Change the highlighted line to.

AND (propValue.LongString like @Condition)

or alternatively to look in both change it to:

AND ((propValue.String like @Condition) or (propValue.LongString like @Condition))

Enjoy!

Also there are other limitations like time to wait for the server to timeout and time between clicks, which I am not sure the tool allowed them to adjust. Talking to them I recalled a tool for grabbing website thumbnails long time ago. one way for them would be to to make a batch file with it. The tool would grab the sites’ thumbnail and stress it, but they would still have to setup a number of clients. Also it creates and tears down an instance of IE every time, making it’s not optimal for that task.

So a couple of evenings later (and a few back-s and forth-s during the testing sessions) out comes SoakIE:

The app uses pretty much the same trick as the tool for grabbing website thumbnails but it does so in a nice UI and allows for some rudimentary settings for profiling the traffic:

You can select the number of IE instances that will do the clicking, you can select a minimum time between clicks – that is how often any IE instance can click (if it already finished with the previous request). this allows you to simulate clients that will stay a minute on your site and only click after they’ve read the page. Additionally if your application can on an occasion encounter a deadlock or a hang, it allows you to specify the maximum time to live of each request. If the request takes longer than the specified time, the application will “Stop” the request.

One thing that we’ve noticed though is that after a long time of soak tests the IE instances get mighty fat and start to slow down dramatically. Therefore I’ve added a maximum number of clicks an IE instance can perform after which the client will no longer recycle it for more click but will tear it down and create a new IE instance to continue testing.

Naturally the application needs to know what to test. This is specified in the “Test setup" tab in the “URLs to stress:" text box. The URLs will be picked in a round-robin fashion. The first browser will get the first url, the next one will get the second and so on, if the list will get exhausted the browsers will get fed it from beginning. You can theoretically put them in the box with some other text (like pasting it from a Skype window without stripping the message decoration around them) – SoakIE should be smart enough to parse the text and get the URLs out of it.

You can download SoakIE here

Well I have… and I’m sure I will. And so did Fredrikj on the our #epicode IRC channel ;).

Basically I had the tool that would convert from one language to another, but Fredrikj requested something that would switch master language of a page from one to another. Since I’ve already had some of the work done, I’ve updated the stored procedure I’ve written some time ago and slapped a nice GUI up on it. Here’s the result:

What the tool allows you to do is perform either language conversion or master branch switching on a selected page and all of its children (if you choose so).

The stored procedure have been updated to work on CMS5 R2 (will no longer work on R1 – but if you need that functionality, comment here or give me a shout and I’ll create a compatible version for you).

A word of caution though – I take no guarantee whatsoever about its operation. Especially, if you wreck your client’s database with it. I did what I could to prevent some of the obvious problems (like switching to a non existing master or converting to an existing one) but I will not be responsible if it won’t work for you. make a database backup and experiment there before you do any changes on the real data. That said – it works for me, so I think it should also work for you.

You can download the archive containing the tool here. unzip it to your EPiServer web application folder keeping the folder structure or the plugin reference will be wrong. Include the *.aspx and the *.cs files in your project and apply the SQL file to your database (The manipulation is performed by a stored procedure located in the file).

Also if you’re performing the change in a load balanced environment, you may need to restart the other servers once you do the changes. I reset the DataFactory cache, but I am not sure it propagates through to other servers.

• You may want to keep all of the files in one store – being forced to put them into a designated folder is not desired.
• You may want to make some file freely available for some time and lock it after a while, or the other way around (e.g. to allow the robots to crawl it initially). having to move them is just silly and defeats the purpose.

So how do you discriminate the files that you want locked from those that you want to be publically available, and potentially from those that you want only the logged in users to be able to get?

Specifying the EPiServer File Metadata sweetness

One of the potential solutions would be to define a special rights group and check for that group for the people that have your “registered” magic-cookie. That however introduces a bogus group, and I would rather like to avoid that. However if you look into the FileSummary.config file that’s located in your web application folder you will find a slightly mysterious content. A bit of hacking reveals that you can actually add your own metadata to the file. For example adding the access rights based on what I’ve established above would look as follows (the content you can already find in the file that comes with the public templates that-we-all-oh-so-love is skipped):

<root xmlns:xforms="http://www.w3.org/2002/xforms" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <model>
    <instance>
      ...
      <AccessLevel />
    </instance>
  </model>

  ...
  <xforms:select1 appearance="full" 
                  ref="AccessLevel" id="id_field51">
    <xforms:item>
      <xforms:label>Unrestricted</xforms:label>
      <xforms:value>Unrestricted</xforms:value>
    </xforms:item>
    <xforms:item>
      <xforms:label>Requires Registration</xforms:label>
      <xforms:value>RequireRegistration</xforms:value>
    </xforms:item>
    <xforms:item>
      <xforms:label>Requires CMS Login</xforms:label>
      <xforms:value>LoggedUserAccess</xforms:value>
    </xforms:item>
  </xforms:select1>
  ...

</root>

Great. So what does it look in the file manager now?

Splendid!

Accessing the metadata

Now that we gave the user to specify the metadata, we need the VPP to act upon them. For the benefit of automation of parsing I’ve specified the enum defining the access levels as follows:

enum FileAccessLevel
{
    Unrestricted,
    RequireRegistration,
    LoggedUserAccess
}

Now we need to update the GetFile method to discriminate the access levels (I have decorated the core lines with –>) those are the lines that access the meta data based on their format specified in the FileSummary.config.

public override VirtualFile GetFile(string virtualPath)
{
    string handledPath;

    if (TryGetHandledAbsolutePath(virtualPath, out handledPath))
    {
        UnifiedFile file = base.GetFile(virtualPath) as UnifiedFile;

        if (file != null)
        {
            string strAccessLevel = (string) file.Summary.Dictionary["AccessLevel"] ??
                                    FileAccessLevel.RequireRegistration.ToString();
            FileAccessLevel accessLevel = (FileAccessLevel) Enum.Parse(typeof (FileAccessLevel), strAccessLevel);

            bool isLoggedIn = HttpContext.Current.Profile != null && !HttpContext.Current.Profile.IsAnonymous;
            bool isRegistered = HttpContext.Current.Request.Cookies.AllKeys.Contains(PASS_COOKIE_NAME);
            string email = isRegistered ? HttpContext.Current.Request.Cookies[PASS_COOKIE_NAME].Value :
                (isLoggedIn ? HttpContext.Current.Profile.UserName : "unregistered");

            switch (accessLevel)
            {
                case (FileAccessLevel.Unrestricted):
                    return file;
                    break;
                case(FileAccessLevel.RequireRegistration):
                    if (!isRegistered && ! isLoggedIn)
                    {
                        HttpContext.Current.Response.Redirect(
                            string.Format(registrationFormUrl,
                                          HttpContext.Current.Server.HtmlEncode(virtualPath)));
                        return null;
                    }
                    return file;
                    break;
                case(FileAccessLevel.LoggedUserAccess):
                    if (isLoggedIn)
                    {
                        return file;
                    }
                    return null;
                    break;
                default:
                    return file;
            }
        }
    }
    return Previous.GetFile(virtualPath);
}

Now the user is really in control of what is published to the general public and robots, what is protected with the registration form and what is only available to logged in users. (now you may add more granularity with file rights naturally, this is just a basic setting that an editor without administrative rights can add.

Yet a full fledged registration doesn’t seem like a proper thing to do – cluttering your EPiServer user repository with (let’s face it – for a large part fake or temporary email addresses that user create only to get your content).

While there may be a lot of ways to handle that (streaming it through a page Response.WriteFile might seem as one of the more obvious ones), I would like to show you a cleaner, simpler and more elegant way that I’ve come up with.

We really don’t want people to deep link to our files without them knowing the files are from our site, that’s just rude – so hiding them behind an obscure URL wouldn’t work (thus we cannot use the regular file providers). We’ve already establish that we don’t want to log them in, so setting file rights are useless. But I want all the benefits including client-side caching.

Basically the solution boils down to creating a thin layer over the File provider of our choice, in my case the versioning file provider. The only method we need to override in it is GetFile. I want to allow downloading for logged in users and I want to allow downloading for all users that have a “magic-cookie” set. If either of the conditions are met, the file just downloads using the underlying provider’s routines including all the logic EPiServer has put for caching and rights. But if neither of the requirements are met, the user is directed to a page of our choice.

public override VirtualFile GetFile(string virtualPath)
{
    string handledPath;

    if (TryGetHandledAbsolutePath(virtualPath, out handledPath))
    {
        if ((HttpContext.Current.Profile != null && !HttpContext.Current.Profile.IsAnonymous) ||
            HttpContext.Current.Request.Cookies.AllKeys.Contains(PASS_COOKIE_NAME))
        {
            return base.GetFile(virtualPath);
        }

        HttpContext.Current.Response.Redirect(
            string.Format(registrationFormUrl,HttpContext.Current.Server.HtmlEncode(virtualPath)));
        return null;
    }
    return Previous.GetFile(virtualPath);
}

How you specify that page’s totally up to you, but there is a nice initialization routine called during the Virtual Path Provider loading phase where all of the settings that are specified in your relevant web.config VPP declaration are passed to you, why not use it? What you’ll need define your VPP in the web.config is what follows:

<add showInFileManager="true" virtualName="CookieEnabled" virtualPath="~/CookieEnabled/" 
     bypassAccessCheck="false" name="CookieEnabled" 
     type="Cognifide.EPiServer.CookieEnabledVirtualPathProvider.CookieEnabledVirtualPathProvider,Cognifide.EPiServer.CookieEnabledVirtualPathProvider" 
     indexingServiceCatalog="Web" physicalPath="C:\vpp\Resources" 
     RegistrationFormUrl="/File-Asset-Request-Form/?filepath={0}" />

you can then define your class as:

public class CookieEnabledVirtualPathProvider : VirtualPathVersioningProvider
{
    private const string REGISTRATION_FORM_URL_WEB_CONFIG_PARAM_NAME = "RegistrationFormUrl";
    public const string PASS_COOKIE_NAME = "ResourcePass";
    private string registrationFormUrl;

    public CookieEnabledVirtualPathProvider(string name, NameValueCollection configParameters) :
        base(name, configParameters)
    {
        registrationFormUrl = configParameters[REGISTRATION_FORM_URL_WEB_CONFIG_PARAM_NAME];
    }

    ...

}

So we know now where we want to direct people without a “magic-cookie” who want to get our assets, and how to do it, but how do we finally allow that file to get down to them?

In your page – for the same of simplicity I assume you will be using XForms for gathering the user data, but that really does not matter. When you validate the form data (or get the user to click on a link that you’ve sent them) you just set the “magic” cookie that I called “ResourcePass” to any value and to to expire in some a long amount of time, like a year. So that they can now access your files unrestrained and direct them BACK at the URL they came from – and now the VPP will allow them to just download the file they initially requested:

protected void XForm_BeforeSubmitPostedData(object sender, SaveFormDataEventArgs e)
{
    if (!Page.IsValid)
    {
        e.CancelSubmit = true;
    }
    else
    {
        string requestedFile = Request.Params["filepath"];
        HttpCookie cookie = new HttpCookie(CookieEnabledVirtualPathProvider.PASS_COOKIE_NAME, "true");
        cookie.Expires = DateTime.Now.AddYears(1);
        cookie.HttpOnly = true;
        Response.Cookies.Add(cookie);
        if (!string.IsNullOrEmpty(requestedFile))
        {
            Response.Redirect(requestedFile);
        }
    }
}

It’s incredibly convenient:

And fairly deadly to the merged contact. Once those contacts are merged and you save them but later try to come back to them to re-edit, I’ve noticed that whenever I select them for editing after that, they don’t pop up for the task, but instead the previously selected contact is being opened for editing. I can see the details of such contact, it synchronizes with the phone perfectly, just the editing won’t work.

Browsing through gmail support groups I’ve found out that a lot of people have this problem but somewhat it eludes Google. People suggest that clearing up cookies or history worked for them. No luck here.

What did the trick though was exporting all of them to the Google CSV:

Deleting all the contacts and then importing them back. Unfortunately once you do that all the associations they’ve had with the groups that youv’e defined are gone, but at least you can edit them again!