September 9th, 2018
One of the most frequently asked questions by people who start with Sitefinity is how to create widgets that can do simple things like selecting images or selecting internal pages. This isn't really hard to accomplish, so I'll explain in this short post how we can achieve this.
How can we create a simple Call To Action widget inside Sitefinity which will allow us to select an image, add a description and wrap it with a hyperlink to an internal Sitefinity page?
So in this example, I choose to build a simple ASP.NET UserControl which will be our 'widget'. Let's start by creating the control:
The first thing we need to do is to add a new ASP.NET UserControl to our Sitefinity project, inside Visual Studio.
We will add the markup which will define how our call to action will be rendered on the front end.
You can of course use your own markup and style it using CSS. This is just for reference.
Next, we will define some properties inside the code-behind class which will hold the values for the Image, Page, and Description.
After we have these properties defined, we need some logic to actually bind these values to the frontend controls. We can do this inside the
Page_Load event and call a separate method:
You see that we are using some helper methods here to get the Image and the Page objects based on the Guid properties we defined earlier.
To make things a little more user-friendly, we can inherit from the
ICustomWidgetVisualization interface, so that we can use two extra properties which help us to define a friendly message to the end-user whenever the defined properties are not set. In that case, we want to remind the end-user to set the properties using the widget designer.
So, we need to implement from this interface, which will look like this:
public partial class CallToAction : System.Web.UI.UserControl, ICustomWidgetVisualization
This interface will force us to implement two properties,
Now we need to create a designer for our widget. This is just a nice way to let the user assign values to the properties on our widget. So, let's start by first building our project.
We will use Sitefinity Thunder to create the designer. This is actually the most simple method to do this. You can just add a new item inside a folder of your project. You need to choose a 'Designer for an existing widget'
After choosing a name, the wizard will guide you through the process.
I will not go into detail about this, but it comes down to choosing the property from the list, giving it a name, and adding it to the properties list. In case you select a Guid property, you will get the option to use a PageSelector, ImageSelector, or DocumentSelector. This will insert those selectors on your designer.
When you are done creating the designer, we can add the widget to our toolbox. We also can use Thunder to do this, so after you have built your project, we click on the project name inside our Visual Studio solution. A blue Sitefinity Thunder icon will appear in the Solution Explorer toolbox:
Clicking this will launch another wizard that will allow you to select a widget from your project and add this to the Sitefinity Toolbox so that you can actually drag and drop the widget onto your pages.
Now when we have added the widget to our Toolbox, we can actually drag it onto our page. The first thing you will see after doing this is the message we defined when no properties have been set:
We can now set the properties using the designer that Thunder created for us, by clicking on the icon or the Edit link:
We can now choose an image, select a page, and set the description for our widget.
The end result will be something like this: