DocSite Templates

C# DocSite VB.NET DocSite
DocSite ASP.NET Web Application Example Enlarge
Figure 1: DocSite ASP.NET Web Application Example and Sandcastle vs2005 presentation style

Introduction

DocProject Templates are used to create Visual Studio projects that build compiled help for their project references (references to other projects in the same solution) and/or external sources. When a project based on a DocProject template is built, it produces a managed assembly and then its sources are built into a single compiled help file.

DocSite Templates are DocProject Templates that also generate AJAX-enabled ASP.NET Web Application projects. DocSites build a fully-functional, interactive website for users to browse project documentation over the web or on your company's intranet.

To get started building a DocSite right away, see the Creating a DocSite (Quick Start) tutorial.

Features

Some of the features of DocSites are:
  • Familiar, AJAX-enabled ASP.NET Web Application project in Visual Studio that you can customize.
  • Full support for ASP.NET themes (comes with one theme named, BasicBlue that has images, stylesheets and .skin files).
  • ASP.NET Master page and a componentized layout with user controls.
  • ASP.NET localization is used to provide resource-based text for all pages and user controls.
  • Sidebar:
    • Interactive, hierarchical table of contents with active topic highlighting.
    • Filterable index with active file highlighting.
    • Resizeable by dragging its handle with the mouse.
    • Persistable, so that the user's placement of the handle is recalled upon the next visit to the website.
    • Save, Bookmark, Email and Print buttons that act on the current topic. (Save and Bookmark are only visible in IE.)
  • Customizable and highly extensible full-text search built from the ground up:
    • Capable of indexing HTML files but customized specifically for searching against HTML topic files generated by Sandcastle.
    • Extensible using .NET 2.0 Providers
    • The default provider generates and uses an in-memory search index.
    • Supports complex queries against the index, including operations such as AND, OR, - (not), and parenthetical grouping.
    • Customizable, factor-based weight and rank calculations.
    • URL query string supports bookmarking searches.
  • Keyword browse page for live browsing of the search index (also supports a URL query string for bookmarking).
  • Site administration page for configuring DocSite options, search factors and for viewing simple search statistics.
  • Auto-generated header with site logo, project name and company name.
  • Link to download the compiled help file (.chm).
  • Breadcrumbs.
  • Scrollable content area that displays the active HTML topic file.
  • Auto-generated footer with copyright information.
  • Hackable URLs (currently based on a query string, not URL redirection).

Requirements

There are some extra requirements that you must consider if you are going to use the DocSite templates in Visual Studio 2005:
Visual Studio 2008
For Visual Studio 2008 users, only Standard edition or higher is required. Support for Web Application projects and AJAX Extensions are built-in.

Template Languages

The DocSite templates are available in two languages: Visual C# and Visual Basic.NET. Each DocSite template produces the exact same output; they are just written in different languages.

The language that you choose for your DocSite project does not affect which projects you can build compiled help for, in terms of language.

For more information, see DocProject Templates, Template Languages.

Browser Compatibility

The DocSite templates build a website that has been tested for compatibility with the following web browsers only:
  • Firefox 2.0.0.9
  • Opera 9.24
  • Windows Internet Explorer 7.0.6000.16575
  • Microsoft Internet Explorer 6.0.2900.2180; SP2
Earlier versions of MSIE such as 5.5 have not been tested and may not be compatible.

Frame Layout
Layout is accomplished using Cascading Style Sheets (CSS) and DIV tags, without any HTML tables. For the layout to work correctly in older versions of Internet Explorer, such as 6.0, the style sheets have rules that use CSS Expressions (an MSIE-only feature) and extensive use of the !important declaration to override such rules in the more standard-compliant browsers such as IE 7.0, Firefox and Opera.

The layout HTML can be found in the DocSite.Master page and each individual section of the frame is encapsulated in a user control found in the Controls folder.

Markup
DocSites produce XHTML 1.0 output, mostly generated dynamically by ASP.NET controls.

Deployment

DocSites can be deployed in the same way as any other typical Web Application project. For example, you can manually copy the required files and folders to a host web server, or you can use Visual Studio's Publish feature to make deployment easier. Another, recommend option is to use the Sandcastle/Deployment Build Engine Provider to automate deployment.

For more information, see How To Deploy a DocSite.

Windows Security Issue

DocSite templates generate a default header with a direct link to download the compiled help file (.chm) from the web server. Due to security restrictions on Windows operating systems, you must save the file to disk instead of opening it immediately.

When the browser prompts you to Open or Save, choose Save. Once the file is saved to disc, double-clicking it will result in an Open File - Security Warning dialog asking, Do you want to open this file?. Clicking Open will open the Help dialog but you'll see a message similar to the following in place of the content for every topic:

Navigation to the webpage was canceled

To fix this issue you must:
  1. Right-mouse click the file and select Properties.
  2. On the General tab press the Unblock button.
  3. Click OK on the file properties dialog.
Now, double-clicking the file should allow you to see all of the html topics as expected.

ValidateRequest

HTML and other "unsafe" text can be entered into the site's search box since the ValidateRequest property has been disabled for all pages in the application. This is done in the web.config file, not each individual page.

The DocSite templates handle post data appropriately when it's received through the search box in the header by parsing it and HTML-encoding it for display; however, if you extend the template by adding additional input controls then you must make sure to validate user input yourself to prevent against hacks and possible injection attacks.

For more information, see HttpRequestValidationException Class.

DocSite Administration Page

The DocSite Administration page provides a set of configurable options with application-wide scope. The administration page can be used in ASP.NET's local web server for configuring the site, before deployment, and it can also be used live on the web server, after deployment.

To access this page click the Admin link in the top-right corner of your DocSite. If you haven't logged in yet then you will be brought to the login page first. Enter the credentials that you configured when the project was first created and then click the Login button to continue.

Credentials
When you create a new DocSite in Visual Studio, DocProject's New Project Wizard will have a step that asks you for the DocSite's administrative credentials. It stores them in the web.config file's authentication section and automatically encrypts the password using the algorithm that is configured in the same section (SHA1 in the DocSite templates that ship with DocProject).

If you've created your own DocSite template and would like to have the New Project Wizard prompt for credentials, then add a user with the name, $admin$ to your template's web.config file. Also, set the appropriate password format (e.g., SHA1, MD5 or Clear) and the wizard will automatically use it when storing the password. Here's an example:

<configuration>
  <system.web>
    <authentication mode="Forms">
      <forms loginUrl="~/DocSiteLogin.aspx" timeout="10" slidingExpiration="true">
        <credentials passwordFormat="SHA1">
          <user name="$admin$" password="" />
        </credentials>
      </forms>
    </authentication>
  </system.web>
</configuration>

For more information about custom templates, see the Creating New Templates tutorial.

Settings

Settings are stored in the DocSite.config file found at the root of the project. Changes made directly to this file will not take effect until the application is restarted; therefore, use the web interface to configure settings whenever possible so that the application does not have to be restarted. If the application is restarted then the entire in-memory search index must be regenerated.

Categories
There are two main categories in the administration page: General and Search.

Changes to options in both categories are applied immediately, although changes to the full-text search index, such as keyword weight and rank factors, require the index to be regenerated by clicking the Create Index link. The Create Index link is also useful for ensuring that the index is generated immediately after the DocSite has been published to a production web server.

In the next section of this document each setting is listed with a short description of its purpose.

General

General settings apply to general features of the DocSite application for all web users. As more configurable features are added to the DocSite templates there may be more settings added in this section of the administration page.
Client Settings
Settings that directly affect web users and DocSite behavior.
Letter Bar Configure the characters that will appear in the letter bar at the top of the browse index page. Add characters from your native language or remove existing characters without having to modify any code.
Sidebar size persisted Controls whether a cookie will be used on the client to remember the last position of the sidebar's handle. This setting is enabled by default.

Search

The Search category has a few subcategories for viewing statistics and managing the full-text index, as well as settings related to the DocSite search and browse pages.
Index Statistics
Read-only, full-text search index statistics.
Provider name Name of the current search index provider. DocSiteMemorySearchProvider is currently the only implementation that is installed by DocProject; however, expect an SqlSearchProvider in a subsequent release.
Last creation date The last date and time that the index was created.
# keywords The total number of distinct keywords found among all documents that were indexed.
# documents The total number of files that were indexed.
Settings
General index-related settings.
Root search path Virtual path of the root directory in which the provider will begin the search, recursively. It's recommended that you do not change this setting; a different value may have unintended consequences.
Public search enabled Indicates whether unauthenticated users can use the full-text search page. This setting is enabled by default. Note: The search page and the search box in the header are always available to authenticated users regardless of this setting.
Public browse enabled Indicates whether unauthenticated users can use the index browse page. This setting is enabled by default. Note: The browse page and the search box in the header are always available to authenticated users regardless of this setting.
Keyword Settings
Related to keywords indexed in files and keywords in search queries that are entered by web users.
Minimum keyword length Defines the minimum number of characters that a word must contain in order to be included in the index. This setting is also used to ignore words in queries that have fewer characters than the specified value. The default value is 2.
Excluded keywords Comma-separated list of keywords that must be excluded from the index and queries.
Hot title keywords Comma-separated list of keywords that have special semantics in the titles of indexed documents and are used to add additional value to matches in query results through the Title Rank Factors values, described below. You can customize this list if you want to improve search results with queries that contain full or partial matches to these particular words when found in titles.
Weight Factors
Weight factors are integers that affect the weight of indexed keywords. Note that weight is calculated while the index is being created and rank is calculated when a keyword matches a search query. The values in this section do not set rank directly; however, the weight of a keyword does add additional rank to matches.
Early position keyword Factor used to calculate the weight of a keyword depending upon its location in the document being indexed. Typically, the earlier the position the higher the weight. The formula used to calculate weight is: keyword position / source length * -value + value where value is the value of this factor, which is 10 by default.
Title keyword Factor used to calculate additional weight for keywords found in the titles of indexed documents. The base weight of title keywords is the value of the Early factor (described above), but calculated relative to the keyword's position in the title, not the entire document. The value of this factor is then multiplied by the result. The default value is 1.2, which gives 20% more weight to keywords found in titles.
Title Rank Factors
Additional rank values for keyword matches that are found in the title of an HTML topic.
Exact title hot keyword match Additional rank for exact keyword matches found in both the title of an indexed document and the Hot title keywords list (described above). The default value is 250.
Partial title hot keyword match Additional rank for partial keyword matches found in the title of an indexed document, with an exact match found in the Hot title keywords list (described above). The default value is 100.
Exact title keyword match Additional rank for exact keyword matches found in titles of indexed documents. The default value is 50.
Partial title keyword match Additional rank for partial keyword matches found in titles of indexed documents. The default value is 20.

Last edited Dec 12, 2008 at 4:15 PM by davedev, version 27

Comments

davedev Jun 9, 2008 at 6:39 PM 
(No longer an issue. Thanks.)

ulu Feb 8, 2008 at 7:12 PM 
After installing the 3.5 framework, the System.Web.Extensions version should be changed to 3.5.0.0