Table of contents
Widgets (controls) are one of the key points of the extensibility in Sitefinity. Widgets are a small piece of functionality that users of Sitefinity can drag on the page in order to create page content. Sitefinity comes with numerous widgets out of the box (such as Blog Posts, Image Gallery and so on), but the ability to create new widgets and extend Sitefinity is really where Sitefinity shines. In this blog post, I will demonstrate how to create a widget for the Facebook Like button with a designer that is able to configure this widget.
Video of the final result
Before we dive deeper into the implementation of this widget, take a look at the short video that demonstrates the final result.
NOTE 1: You do not yet have Like button widget in your toolbox, as it is shown in the video. Scroll down to Installation instructions and code download to see how to add Like button to your toolbox.
NOTE 2: The error you will see towards the end of the video, results from the fact that the page that was liked is on the localhost and Facebook cannot reach it to verify it. This is ok; on the live site this will work fine.
You can take a look at the video here.
When implementing a widget, generally only one class is enough – the control that represents the widget. In Sitefinity, it is a very good idea to inherit from a base class called SimpleView, when implementing widgets.
If the widget is to be configured by the users, we may also decide to implement a widget designer, in order to provide a user friendly way of configuring the widget. Note that even if you don’t implement the widget designer, users will still be able to configure the widget through the automatically generated property grid. Now, take a look at the following screenshots to get a better feeling of the terminology.
Figure 1: Widget – this is the content or functionality visible to your users
Figure 2: Widget designer – this is the user friendly way to configure your widget. Note that widget designers need to be implemented; they are not automatically generated. You have absolute freedom in designing the user interface of a widget designer.
Figure 3: Property grid – property grid is an automatically generated by examining all the properties of your widget that are a) public and b) browsable. Every single widget when used by Sitefinity will automatically generate this editor and you do not need to do anything.
So, now that we are clear on the terminology, let’s start explaining the files included in the project and their purpose.
In order to tell Sitefinity that LikeButton widget has an associated designer, you need to place the ControlDesigner attribute at the top of the LikeButton class, providing the type of the designer as an argument, like this:
If you are unfamiliar with the IScriptControl interface and general development of the ASP.NET Ajax controls, you may find further information here, even though it is not absolutely necessary for this article.
You can use this property to get the instance of the parent object, called “PropertyEditor”. This object holds references to both designer and property grid. Generally you don’t need to use this property.
Used by Sitefinity; do not use.
Gets you the serialized version of the widget. This is how you modify the properties. For example, if you wish to set the “ShowFaces” property of our LikeButton widget to true, you would do it like this:
this.get_controlData().ShowFaces = true;
This method is called, when you need to refresh or update the user interface of your designer with the new data. Sitefinity automatically calls this method every time it needs to (for example, user switches to advanced mode and changes some properties in the property grid, then switches back to the simple mode or designer – this method will be called so that you can update the user interface of your designer with the changes that have been made in the advanced mode. Generally you can think of this method as “from data to user interface”.
This method is called, when Sitefinity needs to get the properties from your designer. For example, let’s say that user clicks the “Done” button in the designer. In that case Sitefinity needs to get all the properties from your designer and persist them so that it can render the widget properly. Generally, you can think of this method as “from user interface to data”.
A bit of background
Many people have complained that this new approach is too complicated, mainly saying that in 3.7 it has been simpler. I would have to disagree with this. Namely, most of the concerns come from the fact that we require you to build a designer with client side code and server side code is not an option.
First, let me explain why is it necessary that the designers are implemented on the client side. Namely, Sitefinity 4.0 is not using postbacks at all – and this would introduce quite an inconsistency if we’d use postbacks here. In order to make both, designers and property grid, be synchronized and be so without the postbacks we have decided to go this way. There is no doubt that your users like this approach better.
The sample provided in this blog post can be used as a starting point for any widget / designer implementation and by minimally changing it (only the things that are really different) you can have your designers up and running in no time. For example, it took me less than 2 hours to write this sample.
I hope this clarifies some of the misunderstandings with the new approach to widgets and designers.
Installation instructions and code download
- Create a new Sitefinity or use existing website. Open this website in Visual Studio.
- Download the project Telerik.Sitefinity.Samples.SocialTools.zip from here.
- Extract the zipped file in the parent folder of your website
- Right-click on the solution and select “Add” then “Existing project”
- Navigate to the folder that you have extracted and double click on the Telerik.Sitefinity.Samples.SocialTools.csproj file
- Expand the “References” folder of the project that you have just added and make sure that all references are working. If not, replace the references that are broken with the ones from the bin folder of your website.
- Build the project.
- Run the project
- Navigate to Sitefinity administration area
- Navigate to “Administration” > “Settings”
- Switch to “Advanced” settings
- In the tree, navigate to “Toolboxes” > “Toolboxes” > “Page controls” > “Sections” > “Content toolbox section” > “Tools”
- Click on “Create new” to add the widget to the page editor toolbox in the section “Content” (the first one)
- In the ControlType textbox type:
- In the Name textbox type:
- In the Title textbox type:
- In the Description textbox type:
Facebook Like button
- Click “Save changes”
- Navigate to Pages
- Create a new page or open existing one
- Locate the widget “Like button” in the first section of the toolbox “Content” and drag it on the page. Edit it if you decide to.
- Publish the page
- View the page and click on the like button (you may need to be logged in to Facebook to do so).