Downloads

By Haemoglobin
5/30/2010 (revision 37)

Download

The Wiki Control can be downloaded from here: http://wikicontrol.codeplex.com/

.NET 3.5

This user control is created with Visual Studio 2010 and targets version 3.5 of the .NET framework.

BlogEngine.NET

BlogEngine.NET is unfortunately still running on 2.0. Most web hosts are running 3.5 now however and to have BlogEngine run on 3.5 instead it is a simple(ish) matter of making a few modifications to the web.config.

For BlogEngine.NET users I recommend making a backup of your current web.config, and downloading and using my .NET 3.5 BlogEngine Web.config file instead. You will of course need to re-integrate any changes you have made to your web.config since you downloaded it.

Database

The Wiki Control runs entirely off a single table called WikiEntry. The script to create this is in the file Database Scripts\CreateTable.sql.

If you are already running your site on a SQL database it is up to you whether you use this or create a dedicated database for the wiki table. If using an existing, you just have to make sure a table named "WikiEntry" doesn't already exist in that database.

Once this is done, add the connection string to the database by modifying/adding the following line to the connectionStrings section of the web.config:

For connection string syntax for SQL Server, check http://www.connectionstrings.com/sql-server-2005#p1

The Database Scripts folder also contains SQL upgrade scripts that you can run if upgrading between versions of the control.

ValidateRequest

Markdown is designed to implement a subset of HTML and can be used as a way to sanction user input. However, there is nothing stopping you from typing raw HTML alongside Markdown for anything additional you want on top of what Markdown implements.

This however requires posting HTML code back to the web server that ASP.NET considers unsafe by default.

If you wish to be able to do this, the best option is to modify the page directive for the aspx page containing the wiki control. For example, in BlogEngine you would modify page.aspx to look like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="page.aspx.cs" Inherits="page" ValidateRequest="false" %>

Once again, this is optional.

File Deployment

  • Copy the App_Browsers and App_Code directories to your web server.
    • Note that the file in App_Browsers is used to create some magic to ensure forms are posted back to the original requested URL, not the rewritten URL as happens in BlogEngine.NET. Without this images are broken after AJAX postbacks.
  • Copy the WikiControl folder to a location of your choice. In BlogEngine.NET, you would typically copy this into the User Controls folder.

Spinning It Up

BlogEngine.NET

Create a new page that you want the wiki to exist on. Edit the page, click HTML view and add the following snippet:

[usercontrol: ~/User controls/WikiControl/WikiControl.ascx InstanceID=Downloads;]

General ASP.NET

In the aspx page where you want to use the control, reference the user control as you would any other: 

<%@ Register src="WikiControl/WikiControl.ascx" tagname="WikiControl" tagprefix="uc1" %>
    <uc1:WikiControl ID="WikiControl1" runat="server" InstanceID="Downloads" />

In each case - replace Downloads with something that makes sense for that particular wiki instance. There are other parameters that you can add here, as described in the next section. The default values will be used if the parameter is left off.

Parameters

  • InstanceID (default: "Default")
    • Multiple instances of the wiki can exist on the same database. This is used to group pages that belong to a particular wiki.
  • DisplayVersionHistory (default: false)
    • Displays the following buttons to the non-logged in user
      Version History
  • UsePathInfo (default: true)
    • This will cause the URL of the page to look like "Downloads.aspx/Installation Instructions" as opposed to "Downloads.aspx?page=Installation%20Instructions"
    • This has search engine optimisation benefits as well as making it look prettier but is likely to break lots of references (scripts/css/images) on your site unless you make use of absolute references.
  • DisableTitleModification (default: false)
    • The control will add the wiki page name to the title of the page. This has search engine optimisation benefits as well as providing more information in the user's bookmark if they bookmark the page.
  • DisplayQuickLinks (default: false)
    • Displays a list of all pages in the wiki. Useful for the administrator of the wiki to look for any orphaned pages, however this can be shown to the user also as a form of navigation if you wish.
  • SyntaxHighlighterBrush (default: "c#")
    • If using SyntaxHighlighter Integration (see below), this is where you can define the "brush" to use for code snippets. By default this is set to c#.

Using It

Creating New Pages

  1. Add [[My new page]] into the wiki entry.
  2. Save.
  3. Click on the created link and add text to the new page.

Using Markdown

Use the Markdown syntax page to assist you with Markdown.

Also, while editing the wiki entries you can use the following keyboard shortcuts:

  • Ctrl+B for strong
  • Ctrl+I for emphasis
  • Ctrl+K for code

SyntaxHighlighter Integration

If the website you install the control within has both jQuery and SyntaxHighlighter installed, the control will detect this and ensure any snippets set to 'code' using the WMD editor's code button (or Ctl-K hotkey) will be highlighted correctly when the wiki page is displayed.

Additionally, the button Format Code is displayed in edit mode and will format any code in the preview window with the SyntaxHighlighter after being clicked.

If you wish to use a different brush than the one defined in the SyntaxHighlighterBrush setting, you can revert back to the normal way of using SyntaxHighlighter by inserting text like so: 

<pre class="brush: js">javascript code</pre>

Note that every time a key is pressed in the wiki edit dialog code formatting is lost in the preview (due to the nature of the DOM being altered). One implementation option is to wait x seconds and reconvert (as discussed here), but I found this to be annoying due to the preview jumping position unexpectantly (this is due to a difference between google's code prettify and SyntaxHighlighter where SyntaxHighlighter will replace pre tags with div tags allowing the code snippet to wrap with the screen width).

I found it more effective to be able to click the Format Code button to review how things look after typing what you need.

Conclusion

Let me know if I need to update these instructions with anything else that would make the process easier!

Enjoy :)


Comments