Shell profile

Table of contents

• Introduction
• Client API
  • Initializing Client Profile Object
  • Accessing the Global Profile on a Component
  • Reading
  • Writing
  • Observing Changes
• Server API
  • Reading
  • Writing
  • Giving New Profiles Default Values

Introduction

EPiServer Shell contains a simple profile API store usable for storing editor settings. It is similar to the ASP.NET profile but a bit more practical to use and has a client API available for Dojo components.

Client API

This section shows how to use the profile from client side code.

Initializing client profile object

Usually the client profile is registered in the service locator, this means multiple components can manipulate the same profile and observe changes on the profile. The CMS application already performns this initialization so when creating CMS components this is not necessary.

initialize: function (settings) {
    // Once during module initialization
    dojo.require("epi.shell.Profile");
    this.registerDependency("epi.shell.Profile", new epi.shell.Profile());
}

Accessing and storing the global profile object on a component

A good way to work with the client profile is assigning an object field during component initialization.

postCreate:function () {
    // resolve profile from dependency system
    this._profile = epi.dependency.resolve("epi.shell.Profile");
},

Reading from the client profile object

To access values in the profile use the get method.

getProfileValue: function(){
    // get value from profile
    return this._profile.get("MyKey");
},

Writing to the client profile object

To set values in the profile use the set method.

setProfileValue: function(value) {
    this._profile.set("MyKey", value);
}

Observing changes to the client profile

The profile is a Dojo observable object and the Dojo API for observing changes can be used.

postCreate:function () {
    this._profile = epi.dependency.resolve("epi.shell.Profile");
    this._profile.watch("MyKey", dojo.hitch(this, function (name, oldValue, value) {
        this.doSomethingUsefulWith(value);
    }));
},

Server API

This section shows how to use the profile from server side code.

Reading profile data

To read values on the profile get it using the profile repository.

using EPiServer.Shell.Profile;

public class ProfileManipulator : TemplatePage
{
    public object GetMyValueFromProfile()
    {
        if(User.Identity.IsAuthenticated) 
        {
            var repository = Locate.ProfileRepository();
            var profile = repository.GetOrCreate(User.Identity.Name);
            object value;
            if (profile.Settings.TryGetValue("MyKey", out value))
            {
                return value;
            }
        }
        return null;
    }
}

Writing profile data

To set profile values programmatically get a profile using the profile repository, change it, and use the save method on the profile repository. Keep in mind that the value must be a type supported by DDS.

using EPiServer.Shell.Profile;

public class ProfileManipulator : TemplatePage
{
    public void StoreValueInProfile(bool isOrIsnt)
    {
        if(User.Identity.IsAuthenticated) 
        {
            var repository = Locate.ProfileRepository();
            var profile = repository.GetOrCreate(User.Identity.Name);
            profile.Settings["MyKey"] = isOrIsnt;
            repository.Save(profile);
        }
    }
}

Giving new profiles default values

Setting values on a profile involves listening to events on the profile repository, and manipulating the profile object before it's used for the first time. A good place for doing this is in an initializable module.

using EPiServer.Shell.Profile;

public class ProfileInitializer : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        var repository = context.Locate.ProfileRepository();
        repository.ProfileCreated += OnProfileCreated;
    }

    void OnProfileCreated(object sender, ProfileEventArgs e)
    {
        // Set setting to a value on newly created profiles
        e.Profile.Settings["MyKey"] = true;
    }
}