Custom template (adding custom information into properties columns)

Topics: Developer Forum, Project Management Forum, User Forum
May 31, 2013 at 6:19 PM
Edited May 31, 2013 at 6:24 PM
I've been studying how to create and present custom tags along nDoc and SandCastle Help File Builder.

There is an example of a property member documented as we want to do.
 <member name="P:CM.CMFlex.LivrosFiscais.Domain.LancamentoBase.NumeroDocumento">
            <para>Número do Documento, conforme informado pelo usuário, ou gerado automáticamente pelo sistema nos casos de emissão de Documentos eletrônicos.</para> 
            <para>É string para comportar os diversos números com zeros a esquerda 
            que devem ser armazenados conforme apresentados nos documentos fiscais de origem do lançamento.</para> 
           <para> Ex.: 00001, 980, 0000000344.</para>
   <description>Número do Documento</description>
We have changed utilities_reference.xsl to create header columns, only when there is a property table been created, let me show the code:
<xsl:with-param name="p_content">
<table id="memberList" class="members">
  <th class="ps_iconColumn"> &#160;</th>
  <th class="ps_nameColumn">
    <include item="header_typeName"/>
  <th class="ps_descriptionColumn">
    <include item="header_typeDescription"/>
<xsl:if test="$v_header='tableTitle_property'">
But We couldn't find how to show the custom information in table lines. I've Found these code lines, but It did'nt work at all.

In utilities_reference.xsl, I've done those changes:
<xsl:template match="element"   mode="memberlistRow" name="t_memberlistRowElement">
   <xsl:if test="starts-with(@api,'P')">
    <td>Fake Type Info</td>
    <td><xsl:call-template name="t_getElementSize"/> </td>
    <td>Fake Required info</td>
In main_sandcastle.xsl:
    <xsl:template name="t_getElementSize">
        <xsl:apply-templates select="fieldsize[1]"/>
And in main_reference.xsl:
<xsl:template name="t_getElementSize">
       <xsl:when test="normalize-space(ddue:fieldsize[1]) != ''">
      <span sdata="memberAuthoredSummary">
        <xsl:apply-templates select="ddue:fieldsize[1]/ddue:para/node()" />
        <xsl:apply-templates select="ddue:fieldsize[2]/ddue:para/node()" />
When I tested it, I could produce a table with all my header columns for properties tables, but in thoses lines, beside description (member summary), only my fake data "Fake Type Info" and "Fake Required info" were shown.

But none of this was sufficient. I confess that my skills on transformations aren't above average, but aren't bellow it.

Can anyone give me a hint?
May 31, 2013 at 8:21 PM
Which version of Sandcastle Help File Builder are you using, and which presentation style did you modify? You wrote that you changed main_reference.xsl, but I don't see that file anywhere in SHFB and Sandcastle It did exist in Sandcastle 2.6.10621.1, though.

Have you verified which of your t_getElementSize templates gets actually executed? E.g. by putting different constant text in each.

Your t_getElementSize template in main_reference.xsl looks like a variant of the getElementDescription template in vs2005\transforms\main_reference.xsl of Sandcastle 2.6.10621.1. However, I don't think that template has anything to do with <summary> elements written in XML comments. Rather, it deals with <ddue:summary> elements read from separately authored XML files in the DDUEXML directory. If this is the template that gets executed, I expect that ddue:fieldsize matches nothing because the fieldsize element you write in the XML comments is not in the DDUE namespace. And even if it were, it wouldn't have those ddue:para elements within it.
May 31, 2013 at 8:28 PM
Takakalka, tks for your fast response.

I'm using SHFB, and I'm trying to modify VS2010 template.

I will verify what you said about t_getElementSize because you got me some directions,

Tks again
May 31, 2013 at 8:40 PM
I've found that te following template has been executed:

    <xsl:template name="t_getElementSize">
        <xsl:apply-templates select="fieldsize[1]"/>
I didn't discover how to access those custom tags that I've created such: <required>, <fieldsize> and <description> in that template.

Can you help me on that?
May 31, 2013 at 8:50 PM
One thing you could try is edit the *.config file to insert another SaveComponent right before the TransformComponent, changing it to save the files to a different directory. This would reveal how the XML tree looks before the XSL transformations, making it easier to find the correct XPath expressions.
May 31, 2013 at 9:02 PM
Edited May 31, 2013 at 9:03 PM
I think I found the problem.
In sandcastle.config, there is a section marked <!-- Copy in reflection data and comments for members -->. In it, there is a CopyFromIndexComponent that copies only some of the elements:
                        <copy name="comments"
                                    target="/document/reference/elements//element[@api=$key]" />
I think you'll need to change that to source="summary|overloads|inheritdoc|fieldsize" so that the fieldsize element of the member will be available when the documentation of the containing class is generated.

I haven't tried any of your changes though. Good luck!
Jun 1, 2013 at 7:32 PM
The main_reference.xsl file was obsolete and was removed from the latest version. I'd suggest creating a custom presentation style so that you aren't modifying the stock presentation styles and template files for Sandcastle and SHFB. This also ensures that you won't lose your changes when a new version is released. More information on creating custom presentation styles can be found in the Custom Presentation Style help file topic and its related walkthrough.

Takajalka is probably correct. If the information is intended to appear on the Member List page, you'll need to modify the copy command in your custom presentation style's copy of the VS2010.config configuration file to include the extra elements in the section following the comment "Copy in reflection data and comments for members". The new source attribute value would be "summary|overloads|description|required|fieldtype|fieldsize".