LiveHelp:方便地在Asp.net界面上添加帮助文档

背景

作为开发人员，我觉得应用程序有个 /Help/ 文件夹专门放帮助就行了；但是客户却要求在操作界面也放给出相应的帮助，原因是他不愿意多点击几下鼠标.好吧，You're the boss，容我想个能偷懒的方案来吧.

实现

首先我不打算在不同的地方重复文档的具体内容（一是我懒，二是如果有变化了要改的地方很多，而且有忽略了某处造成信息不同步的可能），那么最好的办法就是文档内容还是在原来的 /Help/　文件夹里，你愿意到这来看还能看到；操作界面调用这里的内容（估且称在某处出现的帮助文字叫帮助块(HelpPiece)吧)。这样的话就必须给这些文档定义一个统一的格式，因为只有这样才能方便地解析出里面的帮助块，以便调用。

根据原有文档的格式，我稍作修改，做出了以下约定：帮助块是紧随在命名的<h2>或<h3>或<h4>后面<div>。前面的<hx id="xxx">的id是此帮助块的id, 其内容是帮助块的title, <div>里的内容是此帮助块的具体内容。<hx>的id应该是唯一的，而且是在所有帮助文档的范围内唯一。

有了这些信息，就可以打造我们的HelpPiece和HelpParser了：LiveHelper.cs
using System;
using System.Collections.Generic;
using System.Text;
using System.Web.UI;
using System.ComponentModel;
using System.Web.UI.HtmlControls;

namespace LiveHelp
{
public class LiveHelper : Control
{
string helpId;
string helpHtmlPath = "~/help/";
ParseMode parseMode = ParseMode.DirectoryAndDescendants;
string helpUrlFormat = "{0}";
string fileFilter = "*.htm";
string text="Help";

[Category("HelpFiles"), DefaultValue("*.htm"), Description("When parsing files in directory, use this to filter files to parse.")]
public string FileFilter
{
get { return fileFilter; }
set { fileFilter = value; }
}

[Category("HelpFiles"), DefaultValue("~/help/"), Description("The file or directory path where the help files are.")]
public string HelpHtmlPath
{
get { return helpHtmlPath; }
set { helpHtmlPath = value; }
}

[Category("HelpFiles"), DefaultValue(ParseMode.DirectoryAndDescendants), Description("Parse a file, Parse a directory, or Parse a directory and all its sub directories.")]
public ParseMode ParseMode
{
get { return parseMode; }
set { parseMode = value; }
}

[Category("Data"), Description("This specifies which help will be shown.")]
public string HelpId
{
get { return helpId; }
set { helpId = value; }
}

[Category("Data"), DefaultValue("Help")]
public string Text
{
get { return text; }
set { text = value; }
}

public HelpPiece Help
{
get
{
if (string.IsNullOrEmpty(helpId) || string.IsNullOrEmpty(helpHtmlPath))
throw new ArgumentNullException("HelpId, HelpHtmlPath", "要使用LiveHelper,必须先设置这两个参数.");
Dictionary<string, HelpPiece> cached = Page.Cache[GetCacheKey()] as Dictionary<string, HelpPiece>;
if (cached == null)
{
cached = GetParsedResult();
Page.Cache[GetCacheKey()] = cached;
}

return cached[helpId];
}
}

Dictionary<string, HelpPiece> GetParsedResult()
{
string helpPath = Page.Server.MapPath(helpHtmlPath);
HelpParser parser;
switch (parseMode)
{
case ParseMode.File:
parser = new HelpParser(helpPath, helpUrlFormat, Page.Request.PhysicalApplicationPath);
break;
case ParseMode.Directory:
parser = new HelpParser(helpPath, fileFilter, false, helpUrlFormat, Page.Request.PhysicalApplicationPath);
break;
default:
parser = new HelpParser(helpPath, fileFilter, true, helpUrlFormat, Page.Request.PhysicalApplicationPath);
break;
}

return parser.Parse();
}

string GetCacheKey()
{
return parseMode.ToString() + ":" + helpHtmlPath +":" + fileFilter +":" +helpUrlFormat;
}

protected override void OnPreRender(EventArgs e)
{
base.OnPreRender(e);
ClientScriptManager sm = Page.ClientScript;
sm.RegisterClientScriptResource(this.GetType(), "LiveHelp.ibox.js");

HtmlLink link = new HtmlLink();
link.Attributes.Add("type", "text/css");
link.Attributes.Add("rel", "stylesheet");
string defaultStyleSheet = sm.GetWebResourceUrl(this.GetType(), "LiveHelp.ibox.css");
link.Attributes.Add("href", defaultStyleSheet);
Page.Header.Controls.Add(link);
}

protected override void Render(HtmlTextWriter writer)
{
writer.Write(string.Format(@"<a href=""#{0}"" rel=""ibox"" title=""{1}"">{2}</a>", ContentClientId(), Help.Title, text));
writer.Write(string.Format(@"<div id=""{0}"" style=""display:none"">{1}<p style=""text-align:right;""><a href=""{2}"">More

</a></p></div>", ContentClientId(), Help.Content, Help.PageUrl));
}

string ContentClientId()
{
return "help_" + HelpId;
}
}

}

用法

OK,现在我们能这样使用这个控件了：
<%@ Register Assembly="LiveHelp" Namespace="LiveHelp" TagPrefix="live" %>

<live:LiveHelper FileFilter="*.htm" HelpHtmlPath="~/Help" HelpId="testHelp"
ParseMode="DirectoryAndDescendants" Text="Help" runat="server">
</live:LiveHelper>
<!--或者使用默认参数值-->
<live:LiveHelper HelpId="testHelp" runat="server"></live:LiveHelper>

Html帮助文件的格式：
...
<h2 id="testHelp">帮助一</h2>
<div>
<p>some contents here.</p>
</div>
...

示例

代码下载

全部代码(包括测试，演示)下载: LiveHelp.zip.（为什么不让上传 7z 格式的文件?　我用 7z 格式压了只有35KB, 用了zip格式压缩是110KB.)

感想

还是正则表达式快，比XmlDocument+XPath快了十倍以上！