Saturday, September 26, 2009

Using the query system in EPiServer Community

The query system in EPiServer Community is a simple way of retrieving entities and collections specific to EPiServer Community. In this blog post I’ll walk through four examples of how the query system can be used.

Let us start with an easy one: Get a user by an ID. This can of course be done by calling the EPiServer.Community.CommunitySystem.CurrentContext.DefaultSecurity.GetUser() method, but let’s see how it can be done by querying:

As we are retrieving a user, we create a query of type UserQuery. All queries have properties of type [x]Criterion, where [x] can be Integer, String, Boolean etc. This means that before setting a property value, we always have to define its criterion type. In this case, as the ID is an int we create an IntegerCriterion and assign it to the userQuery.ID property. We can then set its Value. At last, we call the GetQueryResult() method to get the result of the query.

In the previous example we were only looking for one entity. Now what if we have a list of email addresses, and we want to retrieve all the users with those addresses?

One of the most common mistakes when using the query system is to forget an initialization of an object. If we were to remove the second or third line in the example above, we would get the error message: “Object not set to an instance of an object”. If you’re new to the query system, you’ll probably see this message quite a few times before you get the hang of it, but the only thing it means is that you’ve forgotten to initialize one of the objects.

Now, let’s pick up the pace. Searching is an important feature of every website, and in a search you’ll need to do logical operations. If in a search, you want to retrieve all the clubs with the word “Elephant” in the title OR the description, you’ll need to use a Logical OR operator:

In order to do a logical operation in a query, you need a CriteriaGroup to which you can add all the criteria. In the example above we create a StringCriterion for the clubs Name, and add it to the criteriagroup. We then do the same for the description, but now we specify a LogicalOperator. Finally, we need to add the criteriagroup to the query.

In the final example we’ll see how to query attributes.Let us say you’ve created an attribute for type IUser of type string which specifies the user’s phone number. You now want to retrieve a user based on that phone number:

That’s it for now, happy querying!

Monday, September 21, 2009

Customizing an EPiServer Community Module using Attributes

While developing an EPiServer Community or EPiServer Relate+ site, you will find the custom Community modules extremely useful. Sooner or later though, you will realize that you need to customize them in order to fit the customers need.

In this blog post, I’ll walk you through how to customize the ‘Add User’ module in the ‘System Settings’ section of the Community tab. I will not show you how to create a custom module as this has previously been explained by the brilliant Joel Abrahamsson.

So the goal in this blog post is to add a custom field, in this case a phone number, to the ‘Add User’ module:

The first thing you need to do is to create a class that inherits from and extends the EPiServer.Community.Web.Administration.EditUserPage class:

In this class I’ve added the textbox that we’ll include in the page later on, and three methods: OnInit, OnLoadComplete and a click event for the save button. Let’s take a look at the OnInit method first:

First we call the OnInit method in the base class, and then we invoke the buttonSave.Click event by supplying the method, buttonSave_Click. This means that the base class’ buttonSave_Click event will be called first and the buttonSave_Click event in our custom class will be called afterwards. The buttonSave_Click event looks like this:

Now, this is where the fun begins. In order for us to save the new users phone number, we are going to use attributes. For more information on attributes in EPiServer Community, click here. So assuming we have added a PhoneNumber attribute of type string for the type IUser, we will be able to save the phone number.

Before we can do this though, we need to retrieve the user who the phone number belongs to. As the buttonSave_Click event of the base class has already been fired, the user has been created and the only thing we need to do is to get the email address in order to retrieve the user. By snooping around in the base class, you’ll see that getting the email address is as easy as this: tabPageUserSettings.Email

So we now have the email address and are able to retrieve the user by calling the GetUserByUserName method (assuming an email address is used as the username). We then clone the user, set the attribute value, update the user and voilá! The phone number is saved.

So far this will not work as we haven’t changed the @Page directive of the EditUser.aspx or added the label and textbox. So first, change the @Page directive of the EPiServerCommunity\Security\EditUser.aspx so that the page inherits your custom class instead of the default implementation. Second, add a label and a textbox to the EditUser.aspx, make sure the textbox has the same id as in your custom class.

Now everything will work fine, except for one thing: Editing the user. If you try to edit the user you just created, you’ll see that the phone number textbox remains empty. In order to fix this, we need to override the OnLoadComplete method of the base class:

Again, we get the email and using that we retrieve the user. We can then get the PhoneNumber attribute value, and add that to the Text property of the textbox. And we’re done :)