BlogEngine.NET Wiki


Edit

1 - Overview

Creating themes with BlogEngine.NET is easy and powerful. (Yes, it is an incredible combination and you get it for free with BlogEngine.NET.) Below is all the information you need to create themes in BlogEngine.NET.

At its simplest level, a BlogEngine.NET theme needs a folder with the name of the theme along with a master page (site.master) and 2 user controls, PostView.ascx to format the view of the post and CommentView.ascx to format the view of the comments. Other files often added include style sheets, images, and additional user controls.

Edit

2 - Folders

In the web project, there is a folder called themes. All themes are required to be stored in this folder to be used by your blog. To make a new theme, simply add a new folder under in "themes" with the name you wish to call your theme.

Edit

3 - Master Page (site.master)

The site.master page is the master page that is applied to every BlogEngine.NET page. Basically, anything you can do with a standard ASP.NET master page you can do here.

Edit

3.1 - Header Considerations

Normally, the header contains lots of links, meta data, and scripts. In BlogEngine.NET most of this is pushed in for you, so you don't have to worry about it.

The average theme will only need a link to a style sheet and the the shortcut icon.

Items pushed in as of version 1.1 include:
  • MicroSummary
  • RSD (Really Simple Discovery (for MetaWeblog API tools)
  • RSS/Atom links
  • Content and Start links
  • Open Search
  • Scripts to javascript resources needed
  • Lots of meta and keyword info.

Edit

3.2 - Body Considerations

This is where the action takes place. The main thing you need to put in is a ContentPlaceHolder called "cphBody". BlogEngine.NET is expecting it and uses it for the different page types in the application. Basically, this is where page specific details will be displayed.

<asp:ContentPlaceHolder ID="cphBody" runat="server" />

After the ContentPlaceHolder, everything else is really gravy. You can do whatever you like. Add a nice title bar, a side bar, and footer.

You could hard code everything, but that wouldn't be best. Ideally, you will use the Controls and BlogEngine object properties where appropriate. These are all listed below. For example, you could just type in the name of your blog, but if you use the Blog object property, you can change that later in the admin section and have the changes take effect without a coding change.

Edit

3.3 - Controls and Object Properties

Ok, you've finally found the most helpful information on this page.

BlogSettings

BlogSettings are the values stored in the setting stored in the admin section of your blog. It is all available here including a lot of stuff you'll never likely use in creating themes. The most commonly used items are listed below.

  • Blog Description/Slogan
    • Code: 
      <%=BlogSettings.Instance.Description %>
    • This is the secondary line of the title as specified in your settings.
  • Blog Name
    • Code: 
      <%=BlogSettings.Instance.Name %>
    • Blog title as specified in your settings.
  • Blog Notification Email Address
    • Code: 
      <%=BlogSettings.Instance.Email%>
    • Email address listed in settings for notification
  • Blog Theme
    • Code: 
      <%=BlogSettings.Instance.Theme%>
    • Name of the Theme being displayed.
  • Blog Version
    • Code: 
      <%=BlogSettings.Instance.Version() %>
    • Version number of the version of BlogEngine.NET you are using.

Controls

Below is the list of included controls that can be useful on the site.master page or your own custom user controls.

  • Author List
    • Code: 
      <blog:AuthorList runat="Server" />
    • Shows the authors (or users) on the blog
  • Blog Roll
    • Code: 
      <blog:Blogroll runat="server" />
    • Shows the blogroll control. The admin setting controls the entries and other settings.
  • Category List
    • Code: 
      <blog:CategoryList ShowRssIcon="true" runat="Server" />
    • Shows the category list. There is an optional property to control whether or not the category list shows the RSS links.
  • Month List
    • Code: 
      <blog:MonthList runat="server" />
    • Shows the month and year for previous posts
  • Page List
    • Code: 
      <blog:PageList runat="Server" />
    • Shows the pages you created for your blog. (Pages are not the same as posts.)
  • Post Calendar
    • Code: 
      <blog:PostCalendar runat="Server" NextMonthText=">>" DayNameFormat="FirstTwoLetters" FirstDayOfWeek="monday" PrevMonthText="<<" CssClass="calendar" BorderWidth="0" WeekendDayStyle-CssClass="weekend" OtherMonthDayStyle-CssClass="other" UseAccessibleHeader="true" EnableViewState="false" />
    • A calendar with days highlights that have posts.
  • Recent Comments
    • Code: 
      <blog:RecentComments runat="Server" />
    • Shows most recent comments made.
  • Recent Posts
    • Code: 
      <blog:RecentPosts runat="Server" />
    • Shows the most recent posts made.
  • Search Box
    • <blog:SearchBox ID="SearchBox1" runat="server" />
    • Shows search box (and optional include comments checkbox)
  • Search on Search
    • Code: 
      <blog:SearchOnSearch ID="SearchOnSearch1" runat="server" MaxResults="3" Headline="You searched for" Text="Here are some results for the search term on this website" />
    • Shows headline and search results when your site has been navigated to from a search engine.
  • Tag Cloud
    • Code: 
      <blog:TagCloud runat="Server" />
    • Shows the tag cloud as a unordered list. (Use CSS to control the look and style of the list to make it look like a standard tag cloud.)

Important Links

There are a few pages that are important to note. These are pages that BlogEngine.NET makes available for you.

Archive.aspx is a archive listing of all your blog posts by category. Contact.aspx is a simple contact form configurable in the admin section of the site. opml.axd is the OPML file for your blogroll.

Your feed url can be retrieved with the following code: 
<%=Utils.FeedUrl %>

Edit

3.4 - Code behind Considerations

While the standard BlogEngine.NET themes currently don't use the code behind, it doesn't mean it can't be used.

This is a great place to check what page (or type of page) is being displayed and turn on/off sections of the master page among other things.

Edit

4 - Post View (PostView.ascx)

The PostView.ascx is the user control that displays a post. This control is used on the main page to show many post (specified in your settings) and also in the individual post page to show the post by itself.

Edit

4.1 - PostView Considerations

You need to show the properties of the post you want to make available. Blog features can come into play here. If you want to use Tags you should display them here, if not, then don't. You need to add the admin links here if you hope to be able to edit and delete posts.

Edit

4.2 - Controls and Object Properties

Here is the reference for the PostView page.

Post Object

The Post object is the main place to get data about the post to be viewed.

  • Author
    • Code: 
      <%=Post.Author %>
    • The author/user who wrote the post.
  • Content
    • Code: 
      <%=Post.Content%>
    • The content of your post
  • Creation Date
    • Code: 
      <%=Post.DateCreated.ToString("d. MMMM yyyy HH:mm") %>
    • The date your post was created.
  • Perma Link
    • Code: 
      <%=Post.PermaLink %>
    • The guid based link to your post.
  • Relative Link
    • Code: 
      <%=Post.RelativeLink %>
    • The display friendly link to your post.
  • Title
    • Code: 
      <%=Post.Title %>
    • The title of your post

Utility Links

There are a lot of handy functions to pull the links you will need to make your PostView look good.

  • Admin Options
    • Code: 
      <%=AdminLinks %>
    • Links to Edit and Delete the post (only for logged in users).
  • Categories
    • Code: 
      <%=CategoryLinks(" | ") %>
    • The categories associated with the post.
  • Comment Feed
    • Code: 
      <%=CommentFeed %>
    • A link to the comment feed.
  • Rating
    • Code: 
      <%=Rating %>
    • The rating control.
  • Tags
    • Code: 
      <%=TagLinks(", ") %>
    • The Tag list for the post. Contains the text "Tags: " before the tags display. Will be blank if no tags exist.

Other Helpful Links

It you are interested in linking to email, other sites, or internal pages. These are the links to look at:

  • Comments
<a rel="nofollow" href="<%=Post.RelativeLink %>#comment"><%=Resources.labels.comments %> (<%=Post.Comments.Count %>)</a>
  • Del.icio.us
<a rel="nofollow" href="http://del.icio.us/post?url=<%=Server.UrlEncode(Post.AbsoluteLink.ToString()) %>&amp;title=<%=Server.UrlEncode(Post.Title) %>">del.icio.us</a>
  • DotNetKicks
<a rel="nofollow" href="http://www.dotnetkicks.com/submit?url=<%=Server.UrlEncode(Post.AbsoluteLink.ToString()) %>&amp;title=<%=Server.UrlEncode(Post.Title) %>">Kick it!</a>
  • DZone
<a rel="nofollow" href="http://www.dzone.com/links/add.html?url=<%=Server.UrlEncode(Post.AbsoluteLink.ToString()) %>&amp;title=<%=Server.UrlEncode(Post.Title) %>">DZone it!</a>
  • Email
<a rel="nofollow" href="mailto:?subject=<%=Post.Title %>&amp;body=Thought you might like this: <%=Post.AbsoluteLink.ToString() %>">E-mail</a>

Edit

5 - Comment View (CommentView.ascx)

The CommentView.ascx is the user control that displays comments left by users on your site. It is a required part although it is common for most themes to use a standard comment template.

Edit

5.1 - CommentView Considerations

You will want to show the most standard comment information as well as be sure to include the admin links for when you are logged in.

The CommentView control must inherit from BlogEngine.Core.Web.Controls.CommentViewBase

Edit

5.2 - Post and Comment Object Properties

Comment Object

  • Author
    • Code: 
      <%= Comment.Author %>
    • Entered Name of commenter
  • Comment/Content
    • Code: 
      <%= Comment.Content %>
    • The comment (raw) See ResolveLinks function below.
  • Creation Date
    • Code: 
      <%= Comment.DateCreated.ToString("MMMM d. yyyy HH:mm") %>
    • DateTime stamp of the comment
  • ID
    • Code: 
      <%= Comment.Id %>
    • id of the comment
  • Website
    • Code: 
      <%= Comment.Website  %>
    • Website of commenter

Utilities

  • Resolve Links
    • Code: 
      <%= ResolveLinks(Comment.Content) %>
    • Shows links in the comment (or whatever is passed to it).
  • Display Author with WebLink
    • Code: 
      <%= Comment.Website != null ? "<a href=\"" + Comment.Website + "\">" + Comment.Author + "</a>" : Comment.Author %>
    • A clean method for displaying author information
  • Gravatar Image
    • Code: 
      <%= Gravatar(80)%>
    • Displays gravatar image
  • Flag (of commenter)
    • Code: 
      <%= Flag %>
    • Shows flag image and text.
  • Admin Links
    • Code: 
      <%= AdminLinks %>
    • Show Admin links for comment.

Edit

6 - Your Style Sheet(s) (css)

A style sheet is not a required part of a theme but it is recommended. The goal of this wiki is not to go into the pro/cons of using CSS for your theme creation so we won't go beyond that here.

You may have multiple style sheets with your theme and use them as you see fit.

Edit

7 - Images and Path Considerations

Images are recommended. The only thing to remember is the path to theme. If you are linking to an image inside your theme, you will need to give it the appropriate path (with theme folder) so the image can be found.

Edit

8 - Site Considerations

Once you have all the pieces put together, it is a good idea to spend some time looking at the different pages to making sure it all looks as you'd hope it would.

Also, it is wise to check the view from as many different web browsers as you deem necessary for your audience.

Edit

8.1 - Default View (default.aspx)

This is the page that will display on the home page.

  • How does it look with a full compliment of posts?
  • How does it format with long titles?
  • Do long URLs in posts wrap or break correctly (if your users aren't the most HTML-savvy)?
  • Remember anything that is controled by the settings, can be variable length down the road.

Edit

8.2 - Post View (post.aspx)

This is the individual post page.

  • How does it look with long titles?
  • Have you checked short posts and long posts?
  • Be sure to check no comments, a few comments and lots of comment options.
  • Is the "Add Comment" section formatted correctly?
  • Is the "Related Posts" displayed and formated correctly if it is? (What would it look like later with it added/removed?)
  • Is the Comment Form formated correctly?
  • The Comment Form has validation in it. Does it look ok when activated?

Edit

8.3 - Page View (page.aspx)

This is only applicable if you have pages on your site.

Edit

8.3 - Archive View (archive.aspx)

This is a separate page which can be linked to show post history by category. You'll want to make sure it is formatted nicely.

Edit

8.4 - Contact Page (contact.aspx)

The contact page is another page that is easy to forget to check. Make sure it looks good with your formatting.

ScrewTurn Wiki version 2.0.33. Some of the icons created by FamFamFam.