This project is read-only.


What is a Widget?

A widget is a self-contained control that displays information on your blog. BlogEngine.NET includes over 15 widgets. Widgets are typically laid out vertically in the blog's sidebar.

Managing Widgets

While logged into your blog, you should see a dropdown list in the sidebar containing a list of the available widgets. You may add widgets by selecting the desired widget from the dropdown box and clicking the Add button. You may also re-arrange the widgets by dragging and dropping them into the order you prefer.

All widgets will have an 'Edit' link in the upper-right corner of the widget. These Edit links will only be visible while you are logged into your blog. Clicking the Edit link will bring up the widget editor. At a minimum, the Title of every widget is customizable. Several widgets have additional options that may be configured.

Widget Support in Older Themes

Some themes were created before the widget framework was developed. If you're using a recent version of BlogEngine.NET (version 1.4.5 or newer) with an older theme, in most cases, you can add widgets to your theme by adding the following markup in your theme's site.master file:

<blog:WidgetZone runat="server" />
You will probably also need to add some CSS styles to your theme's CSS file to control the layout and formatting of the widget area and individual widgets. You will find a "widget" section in the Standard theme's style.css file. As a starting point, you may copy the widget related CSS styles from the Standard theme's style.css file to your theme's style.css file.

Creating your own Widget

BlogEngine.NET makes it very easy to create your own widgets. Widgets are ASP.NET Controls. A great way to learn how a widget works is to look at the code in an existing widget. Each widget is in its own folder within the widgets folder found in your blog.


All widgets must have a widget.ascx file and a widget.ascx.cs file. The widget.ascx file is the actual control that will be rendered. The following requirements exist for the widget.ascx control.
  1. The widget.ascx and widget.ascx.cs files must exist in their own subfolder under the Widgets folder. The subfolder will be the name of the widget.
  2. The widget you create must inherit from WidgetBase.
  3. The widget must override the "Name" property. The property must return the name of the widget, which should be the same name as the subfolder you are creating the widget in.
  4. The widget must override the IsEditable property.
  5. The widget must override the LoadWidget method. The widget framework calls the LoadWidget method. It is in this method that the widget should output any content it needs to output.

The edit.ascx control is an optional control. If your widget has any configuration options, you will want to create an edit control. This will consist of an edit.ascx and edit.ascx.cs file. The edit.ascx control will be displayed when the 'Edit' link in the upper-right corner of the widget is clicked. The following requirements exist for the edit.ascx control.
  1. The edit.ascx and edit.ascx.cs files must be placed in the same folder as the widget.ascx and widget.ascx.cs files.
  2. The edit control must inherit from WidgetEditBase.
  3. The edit control must override the Save method. This method is called when the user is finished making their changes and clicks the Save button. The widget framework provides a Save button (and Cancel button) to the edit dialog window.
For storing and retrieving settings your widget needs to save, the widget framework provides two methods for your convenience -- GetSettings() and SaveSettings(). These methods retrieve and save a dictionary of string values. The values are persisted to the data store (either a file in the App_Data folder or in a database). If your widget has a very large number of settings to save, you may consider implementing your own get/save code to store your widget's settings in their own file or database table. For most cases, the built-in GetSettings() and SaveSettings() methods will be sufficient.

Sample Widgets

As mentioned above, BlogEngine.NET comes with over 15 widgets out of the box. These built-in widgets provide information and functionality for a lot of common blog needs. The built-in widgets are great samples in and of them selves. To get a close up look at the code behind these widgets, have a look at the code in these existing widgets in the "widgets" folder. A few of the widgets included in BlogEngine.NET are BlogRoll, Calendar, Month List, RecentComments, Twitter.

Many BlogEngine.NET users have developed and shared their own widgets with the public. Links to some of these widgets can be found here.

Last edited Mar 13, 2009 at 12:39 AM by BenAmada, version 2


No comments yet.