Api\HtmlTextWriterHelper.cs

/*       Copyright (c) Eric Ledoux.  All rights reserved.       */
/* See http://www.dwell.net/terms for code sharing information. */

// HtmlTextWriterHelper.cs
//
// Implements class HtmlTextWriterHelper and related types.
//

using System;
using System.IO;
using System.Web.UI;
using CodeDocApi.Properties;

namespace DwellNet.CodeDoc
{

HtmlTextWriterHelper Class

Extends HtmlTextWriter with additional functionality.

public class HtmlTextWriterHelper : HtmlTextWriter
{
    //////////////////////////////////////////////////////////////////////////
    // Public Fields
    //

HtmlTextWriterHelper.MarkOfTheWebHtml Field

The HTML that comprises the Mark of the Web. See HtmlTextWriterHelper.BeginHtmlDocument for more information.

    public const string MarkOfTheWebHtml =
        "<!-- saved from url=(0014)about:internet -->";

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

HtmlTextWriterHelper Constructor (TextWriter)

Initializes a new instance of this class based on a given TextWriter.

Parameters

textWriter

The TextWriter that renders the markup content.

    public HtmlTextWriterHelper(TextWriter textWriter)
        : base(textWriter, "  ")
    {
    }

HtmlTextWriterHelper Constructor (TextWriter, string)

Initializes a new instance of this class based on a given TextWriter and a given tab string.

Parameters

textWriter

The TextWriter that renders the markup content.

tabString

The string to use to render a line indentation.

    public HtmlTextWriterHelper(TextWriter textWriter, string tabString)
        : base(textWriter, tabString)
    {
    }

HtmlTextWriterHelper Constructor (HtmlTextWriterHelper)

Initializes a new instance of this class by copying the state of another HtmlTextWriterHelper.

Parameters

htmlWriter

A HtmlTextWriterHelper to copy.

    public HtmlTextWriterHelper(HtmlTextWriterHelper htmlWriter)
        : base(htmlWriter.InnerWriter, "  ")
    {
    }

HtmlTextWriterHelper.FormatTag Method

Writes an HTML tag with no content (i.e. "<tag-name attributes... />") to the output stream, including zero or more attributes and an optional newline.

Parameters

format

A comma-delimited list of names. The first name (required) is the HTML tag name of the element to write. Subsequent names (optional) are attribute names, one per element of attributeValues. String values are written as-is (with HTML encoding); non-string values are converted to strings using Convert.ToString using a culture-invariant conversion. Following the list of names may be one or more newline characters, causing a corresponding number of calls to WriteLine to be made after rendering the HTML tag.

attributeValues

The attribute values corresponding to the attribute names in format.

Remarks

Any calls to AddAttribute preceding a call to FormatBeginTag will cause additional attributes to be included in the tag.

Example

The following example:

htmlWriter.FormatBeginTag("link,rel,href/\n", "stylesheet", "_CodeDoc.css");

...writes the following HTML, including a newline at the end:

HTML

<link rel="stylesheet" href="_CodeDoc.css" />

    public void FormatTag(string format, params object[] attributeValues)
    {
        HelpFormatTag(format, attributeValues, true);
    }

HtmlTextWriterHelper.FormatBeginTag Method

Writes the opening tag of a markup element to the output stream, along with zero or more attributes and an optional newline.

Parameters

format

attributeValues

The attribute values corresponding to the attribute names in format.

Remarks

Use RenderEndTag to write the closing HTML tag corresponding to the opening tag written by FormatBeginTag.

Any calls to AddAttribute preceding a call to FormatBeginTag will cause additional attributes to be included in the tag.

Example

The following example:

htmlWriter.FormatBeginTag("html,xmlns", "http://www.w3.org/1999/xhtml");

...writes the following HTML:

HTML

<html xmlns="http://www.w3.org/1999/xhtml">

When RenderEndTag or FormatEndTag is called subsequently (after a matching number of begin/end render calls) the "</html>" tag will be written.

    public void FormatBeginTag(string format, params object[] attributeValues)
    {
        HelpFormatTag(format, attributeValues, false);
    }

HtmlTextWriterHelper.FormatEndTag Method

Calls RenderEndTag to writes the end tag of a markup element to the output stream. Also writes one or more newlines.

Parameters

format

One or more newline characters, causing a corresponding number of calls to WriteLine to be made after rendering the HTML tag.

Example

The following example:

htmlWriter.RenderBeginTag("title");
htmlWriter.Write("Title goes here");
htmlWriter.FormatEndTag("\n");

...writes the following HTML, including a newline after "</title>":

HTML

<title>
  Title goes here
</title>

    public void FormatEndTag(string format)
    {
        // render the end tag
        RenderEndTag();

        // write newlines, if specified
        foreach (char ch in format)
        {
            if (ch == '\n')
                WriteLine();
            else
            {
                throw new ArgumentException(Resources.InvalidFormatString,
                    "format");
            }
        }
    }

HtmlTextWriterHelper.BeginHtmlDocument Method

Writes the beginning of an HTML file, including "<DOCTYPE>" and "<html>" elements, as applicable.

Parameters

htmlDocType

The type of HTML document.

markOfTheWeb

true to include the Mark of the Web on the page, false if not. The Mark of the Web enables pages to be loaded into Internet Explorer 6.0 without a security warning, when the pages are on a local hard disk. However, if the Mark of the Web is included in a frameset page, frames cannot load any content except HTML pages that also have the Mark of the Web.

Remarks

Use EndHtmlDocument to end the HTML file.

    public void BeginHtmlDocument(HtmlDocType htmlDocType, bool markOfTheWeb)
    {
        // write the "<!DOCTYPE>" declaration, if applicable
        switch (htmlDocType)
        {

        case HtmlDocType.XhtmlTransitional:

            WriteLine("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
            WriteLine();
            break;

        case HtmlDocType.XhtmlFrameset:

            WriteLine("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Frameset//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd\">");
            WriteLine();
            break;
        }

        // write the "Mark of the Web", if specified; for more information, see:
        // http://msdn.microsoft.com/workshop/author/dhtml/overview/motw.asp
        if (markOfTheWeb)
            WriteLine(MarkOfTheWebHtml);

        // begin the "<html>" block
        if ((htmlDocType == HtmlDocType.XhtmlTransitional) ||
            (htmlDocType == HtmlDocType.XhtmlFrameset))
        {
            // XHTML
            FormatBeginTag("html,xmlns\n", "http://www.w3.org/1999/xhtml");
        }
        else
        {
            // non-XHTML
            FormatBeginTag("html\n");
        }
    }

HtmlTextWriterHelper.EndHtmlDocument Method

Writes the end of an HTML file that was begun using BeginHtmlDocument.

    public void EndHtmlDocument()
    {
        FormatEndTag("\n\n");
    }

    //////////////////////////////////////////////////////////////////////////
    // Private Methods
    //

HtmlTextWriterHelper.HelpFormatTag Method

Helps implement FormatTag and FormatBeginTag.

Parameters

format

The formatting string; see FormatTag.

attributeValues

Attribute values; see FormatTag.

renderEnd

true to call RenderEndTag (before any calls to WriteLine), false if not.

    private void HelpFormatTag(string format, object[] attributeValues,
        bool renderEnd)
    {
        // remove trailing '\n' characters (if any) from <format>; set
        // <newlineCount> to the number of newlines found
        int newlineCount = 0;
        while (format.EndsWith("\n"))
        {
            format = format.Substring(0, format.Length - 1);
            newlineCount++;
        }

        // split <format> into array <namesArray>
        string[] namesArray = format.Split(',');
        if (namesArray.Length - 1 != attributeValues.Length)
        {
            throw new ArgumentException(String.Format(
                Resources.AttributesArrayLengthMismatch,
                namesArray.Length - 1, attributeValues.Length));
        }

        // add attributes (if any)
        for (int i = 0; i < attributeValues.Length; i++)
        {
            AddAttribute(namesArray[i + 1],
                Convert.ToString(attributeValues[i],
                    System.Globalization.CultureInfo.InvariantCulture));
        }

        if (namesArray[0] == "br")
        {
            // special case -- bug workaround
            WriteBreak();
        }
        else
        {
            // render the HTML tag
            RenderBeginTag(namesArray[0]);

            // make this an empty tag, if specified
            if (renderEnd)
                RenderEndTag();
        }

        // write newlines, if specified
        for (int i = 0; i < newlineCount; i++)
            WriteLine();
    }
}

HtmlDocType Enumeration

Specifies an HTML document type.

Members

Name

Description

None

Indicates no HTML document type specified.

XhtmlFrameset

Indicates XHTML Frameset document type.

XhtmlTransitional

Indicates XHTML Transitional document type.

public enum HtmlDocType
{

HtmlDocType.None Enumeration Value

Indicates no HTML document type specified.

    None,

HtmlDocType.XhtmlTransitional Enumeration Value

Indicates XHTML Transitional document type.

    XhtmlTransitional,

HtmlDocType.XhtmlFrameset Enumeration Value

Indicates XHTML Frameset document type.

    XhtmlFrameset,
}

}