Custom Item

Apr 15, 2009 at 4:53 PM
Hi all,

I'm starting to use this fantastic tool.
I would like to create a custom item in generated documentation.

for example in my code, I have :
/// <SpecialItem>
/// This is a custom tag.
/// </SpecialItem>
public int toto = 0;

and in the generated documentation, I would like to have another item named SpecialItem like field, methods or Properties

Is it possible ?
many thanks in advance for your help





Editor
Apr 15, 2009 at 8:41 PM
You can modify the Sandcastle transformations to add support for custom tags.  See this blog post for details: http://blogs.msdn.com/sandcastle/archive/2006/11/22/supporting-custom-tags-in-sandcastle.aspx

Eric
Apr 16, 2009 at 7:22 AM
Thanks for your help.
I have already seen this article and I tested it.
But, I'd like to create a new category like field or methods or Properties.
Is it possible ?
Apr 16, 2009 at 2:08 PM
Hi,

Yes it's possible, but how may depend upon the presentation style that you're using.  For example, if you're using vs2005 then you'll want to wrap the content in a call to the section template, as in the following example.

      <xsl:call-template name="section">
        <xsl:with-param name="toggleSwitch" select="'my_custom_switch'" />
        <xsl:with-param name="title">
            <include item="my_content_item_Title"/>
        
</xsl:with-param>
        <xsl:with-param name="content">
          <xsl:call-template name="my_content"/>
        </xsl:with-param>
      </xsl:call-template>

This example also uses a content item named, my_content_item_Title to retrieve the section's title.  You can add this item to the Content\shared_content.xml file in the vs2005 presentation style.

- Dave
Apr 16, 2009 at 2:28 PM
Edited Apr 16, 2009 at 2:30 PM
Hi,

I forgot to mention that you'll probably want to call your custom template from somewhere within the body template, located near the top of the main_sandcastle.xsl file.  You can either use a named template or simply match your custom tag.  For working examples see <xsl:call-template name="permissions" /> and <xsl:apply-templates select="/document/comments/remarks" />.  Where you place your call will determine where your section appears relative to the other sections.

If you'd like to add a hyperlink in the header that toggles your section, open the htmlBody.xsl file and find the headerRowLinks template.  Here you can include a toggle link using the name of the toggleSwitch that you've chosen.  For example:

    <xsl:if test="/document/comments/my_custom_tag">
      <xsl:if test="$hasTypeLink or $hasMembersLink">
        <include item="nsrLinkSeparator"/>
      </xsl:if>
      <a href="#my_custom_switch" onclick="OpenSection(my_custom_switch)">
        <include item="my_content_item_Title"/>
      </a>
      <xsl:text>&#xa0;</xsl:text>
    </xsl:if>

Where you place your call will determine where your link appears relative to the other links.  See <xsl:if test="$exampleSection"> for a working example.

- Dave
Apr 16, 2009 at 4:22 PM
Thank you very much for your help but I'm a big newbie in this technology.

I suppose that I have to add Section template in main_sandcastle.xsl file.
If I see other template the section begins with <xsl:template match="summary"> for example.
And in your reponse, there isn't this tag.
What must I put ?
Could you explain the meaning of different items like : my_custom_switch, my_content_item_Title,my_content ?

many thanks again for your help.
Maxime

Apr 16, 2009 at 6:02 PM
Hi Maxime,

Assuming that you arleady have something like the following:

<xsl:template match="my_custom_tag">
    <p><xsl:value-of select="." /></p>
</xsl:template>

First, you may want to move the content to a named template as follows:

<xsl:template match="my_custom_tag">
    TODO
</xsl:template>
<xsl:template name="my_content">
    <p><xsl:value-of select="." /></p>
</xsl:template>

And then you can follow my example above for wrapping the content in a section:

<xsl:template match="my_custom_tag">
    <xsl:call-template name="section">
        <xsl:with-param name="toggleSwitch" select="'my_custom_switch'" />
        <xsl:with-param name="title">
            <include item="my_content_item_Title"/>
        </xsl:with-param>
        <xsl:with-param name="content">
            <xsl:call-template name="my_content"/>
        </xsl:with-param>
    </xsl:call-template>
</xsl:template>
<xsl:template name="my_content">
    <p><xsl:value-of select="." /></p>
</xsl:template>

Note: I didn't actually test this markup so there may be typos or other issues.

The switch is used as the name for the HTML object that toggles (collapses/expands) your section via a link in the header, if you choose to add one.  The value should be unique among all other switch names in the current document.

The title specifies the text that is displayed in the header of your section; e.g., Members, Properties, Example.  You can hard-code the value or you can follow Sandcastle's paradigm and put the text in a shared content file; e.g., shared_content.xml.  (Think, the DRY principal and/or localization.)

Your content is the content inside the section.  You can add it in-place or call another template instead, as I've done in this example.

- Dave
Apr 17, 2009 at 7:56 AM
Hi,

So I've done what I said :

in c# source I put :
        /// <customTag>
        /// This is a custom tag.
        /// </customTag>
        public int toto = 0;

in main_sancastle.xsl file I put :
<xsl:template match="customTag">
    <xsl:call-template name="section">
        <xsl:with-param name="toggleSwitch" select="'my_custom_switch'" />
        <xsl:with-param name="title">
            <include item="my_content_item_Title"/>
        </xsl:with-param>
        <xsl:with-param name="content">
            <xsl:call-template name="my_content"/>
        </xsl:with-param>
    </xsl:call-template>
</xsl:template>

<xsl:template name="my_content">
    <p><xsl:value-of select="." /></p>
</xsl:template>

But in generated chm file, toto is already in fields section although I'd like to have toto in customTag section.
I think it's not possible to modify that because Members, Constructor, Fields, Methods, Properties depends on the language.
What is your opinion ?




Apr 17, 2009 at 2:12 PM
Edited Apr 17, 2009 at 2:14 PM
Hi Maxime,

Did you modify the body template like I suggested?

You need to add something like <xsl:apply-templates select="/document/comments/customTag" /> to the body template wherever you want your section to appear relative to the predefined sections.

Did you add my_content_item_Title to the shared_content.xml file like I suggested?

You need to add this item so that a title appears.

- Dave
Apr 20, 2009 at 9:40 AM
Hi Dave,

I've done what you said.

I obtain this screenshot http://rapidshare.com/files/223505110/Sandcastle.jpg.html

The problem is that "toto" is in "MacroAfficheImage Fields" although I'd like to have toto in new section name "CustomTag"

Is it possible ?

Maxime




Apr 20, 2009 at 12:14 PM
Hi Maxime,

The image shows what I expected.  So if that's not what you wanted, then are you asking how to add a new node to the table of contents (TOC) instead?

- Dave
Apr 21, 2009 at 7:37 AM
yes exactly. I'd like to have a new content named "MacroAfficheImage Custom" like "MacroAfficheImage Fields" where there is "toto Custom"

Regards,
Maxime

Oct 5 at 10:01 AM
Hi Dave,

I have a query regarding adding a custom tag to sandcastle documentation. I am trying to add a custom tag to my c# class method.

In order to get that in the sandcastle documentation, I followed the following steps:

1) Added a tag in main_sandcastle.xsl:

<xsl:apply-templates select="/document/comments/CUSTOM_TAG"/>

2) Added template in main_sandcastle.xsl for it :

<xsl:template match="CUSTOM_TAG">
    <xsl:call-template name="section">
        <xsl:with-param name="title">
            <include item="CUSTOM_TAG_Title" />
        </xsl:with-param>
        <xsl:with-param name="content">
            <xsl:apply-templates />
        </xsl:with-param>
    </xsl:call-template>
</xsl:template>
3) Added the title tag in shared_content.xml :

<item id="CUSTOM_TAG_Title">CUSTOM_TAG</item>

But still I couldn't get the custom tag in the documentation.
All the above changes are done in installation directory VS2005 folder and I generated the documentation.

Did I miss something or is there any other step to be followed in order to obtain the custom tag?
Kindly help.