SandCastle – Creating a website

Something which I forgot to mention in yesterday’s post was that SandCastle can create a website for your API.

When executing the example included within the CTP, in the output folder there is a subfolder called HTML. However, this isn’t very useful as it is simply all the pages which are later compiled in the CHM.  However, Sandcastle Help File Builder (SHFB) has an excellent feature, where it takes this output and actually makes it useful.

SHFB takes the Sandcastle HTML files created via either external content or from the XmlComments, together with some magic files, mainly a Tables of contents in XML and some Javascript files which creates a table of contents for use within a HTML page, or use within an ASP.net page – both created for you.  From this page, it loads the HTML, created by Sandcastle, in an IFrame allowing for all of the Help content to be displayed online. Very cool, however it doesn’t look very nice.

I have been nice and uploaded the example which SHFB outputs to here with the ASP.net output here.  The project I used was different to the previous post as SHFB couldn’t import the example, required a real solution file but its more to demonstrate something.

Just to summarise, SHFB can use the Html outputted from Sandcastle, to convert it into a website which can be uploaded onto a site.

How to use ASP.net to create a ‘nice’ API website

I am now going to go over the process of creating a website based on the output from SHFB and make it look how you want, this could then be incorporated into your own documentation site.

The first thing I did was create a new ASP.net Ajax enabled C# based website.  I then copied the following files into the solution.

  • html folder
  • icons folder
  • scripts folder
  • styles folder
  • Collapsed.gif
  • Expanded.gif
  • Item.gif

These are all the files I will be using, if you want other items for different requirements you can include them as well. The most important files, are the folders which Sandcastle outputs and WebTOC.xml which SHFB generates.

From this, we can now generate the documentation site based on your own requirements. I simply processed the WebTOC xml file, created a TreeNode for each item, using the Value property for the URL of the related HTML page.  After adding all of them to the TreeView, I hooked into the SelectedNodeChanged event on the TreeView so when a item was clicked, I could load up the related page.

To display the page, I used an embedded iFrame, however to be able to set the URL of the iFrame from the code behind, I had to manually create the HTML for an iFrame within the code-behind and set it to the Text property of a Literal control on the page.

To make the whole thing a bit more pleasing for the user, I wrapped everything in a UpdatePanel and set the UpdateMode to Conditional.

View default.aspx.cs which contains the C# for the site
View my example site
Download all code

That’s it, very simple once you have the XML processed into the navigation control.  With the HTML and the WebTOC.xml are left as loose files so an automated process could simply replace these from a newly created output and the site would automatically update.  While my example might not look ‘better’, it was move to prove a point that it could be done.

Note, full credit goes to Eric Woodruff for creating SHFB and the code for the original example.  Visit Sandcastle Help File Builder

Technorati tags: ,

3 thoughts on “SandCastle – Creating a website”

  1. Hi again 🙂

    You didn’t mention anything about DocProject’s DocSite template. Have you tried it? It’s an AJAX-enabled C# Web Application, with several features. I’ve gotten feedback from people saying how nice it looks.

  2. Hi Dave, cheers for the comments and sorry for not reply.

    I’ll admit, I haven’t tried DocProject’s DocSite.

    I am doing to have another look at DocProject after your previous comment in the next day or two and write another post about DocProject and the differences between yours and SHFB.

    Keep an eye on the blog for that, if I have any questions i’ll ping you a message 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *