cancel
Showing results for 
Search instead for 
Did you mean: 
Workflow Hero

Form Documentation

Greetings:

I want to start documenting the forms we have created with Nintex Forms, including the form's controls, variables, rules, etc. I started doing this manually but then realized that the Form.xml  (exported form) already has all the information that I want (and much more) but to make it more readable I'd need to convert it into an HTML format, showing only the information that I am interested in.  This, of course, suggested that I write an XSLT stylesheet to transform the exported Form.xml into an informative, self-documenting, web page.  Good idea but...

...so far I have been unable to transform the Form.xml, even for such  such a simple purpose as displaying just the display names of the controls. For example, here is an XSLT style sheet (demo2.xslt) to display all the control DisplayName elements:

<?xml version="1.0" ?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:d3p1="http://schemas.datacontract.org/2004/07/Nintex.Forms.SharePoint.FormControls" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Nintex.Forms" version="1.0">

<xslSmiley Surprisedutput method="html"/>
<xsl:template match="/">
<html>
<head><title>Nintex Form Documentation Browser</title></head>
<body>
<h1>Form Controls</h1>

<xsl:apply-templates />
</xsl:template>
</body>
</html>

<xsl:template match="FormControls">
<xsl:apply-templates select="d2p1:FormControlProperties"/>
</xsl:template>

<xsl:template match="d2p1:FormControlProperties">
<xsl:apply-templates select="d2p1Smiley Very HappyisplayName"/>
</xsl:template>

<xsl:template match="d2p1Smiley Very HappyisplayName">
<b>Display Name: <xsl:value-of select="." /></b><br/>
</xsl:template>

</xsl:stylesheet>

I add this to the Form.xml file like this:

<?xml version="1.0" encoding="utf-16"?>
<?xml-stylesheet href="demo2.xslt" type="text/xsl"?>
<Form xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Nintex.Forms">
<AddListFormWebPartSubmitMessage>false</AddListFormWebPartSubmitMessage><AssignedUseSetting>Production</AssignedUseSetting><Category i:nil="true" /><Css>
/* Template styles */

...etc. for the rest of the file

In some browsers, such as IE, including this stylesheet in the XML should transform the form xml into an HTML file showing only the control names.  However, this doesn't work for me.  I have tried many permutations of the XSLT stylesheet but always get something like this:

falseProduction /* Template styles */ .nf-form-input { background-color: #ffffff; } .nf-form-input .nf-filler-control-inner, .nf-form-label .nf-filler-control-inner { top: 10px; bottom: 10px; left: 10px; right: 10px; } .nf-form-input .nf-textbox-wrapper { left: 0px; right: 0px; } .nf-section { border-top: 1px solid #FF0000; margin-top: -1px; } .nf-section-bottom { border-top: 2px solid #FF0000; margin-top: -2px; } .nf-item { background-color: white; } .nf-item-alternating { background-colo

...etc...

Notice that even though my stylesheet should be skipping all the junk at the beginning (before <FormControls...> in the XML it is still showing the contents of the AddListFormWebPartSubmitMessage, AssignedUseSetting, and  Css elements.

So my questions are these:  a) hasn't anybody done this before?  It seems like a natural way to self-document a form, and b) what's wrong with the above XSLT when applied to the Form.XML?

Thanks, in advance,

Bruce

Labels: (1)
0 Kudos
Reply
3 Replies
Workflow Hero

Re: Form Documentation

Hi Bruce Altner‌,

Using the exported XML file sounds like a good idea, but what when Nintex decides to change the internal structure, which they can and hopefully will do if that makes the product even better. You get my point I hope.

The way I look at documentation is the following: The best documentation is the source. This is something I picked up from developers , meaning I target my documentation more on the general understanding and functional desciption but much less on the technical part.

Cheers,

Rick

Accept as Solution Reply
Workflow Hero

Re: Form Documentation

Rick:

Thanks for the thoughtful response.  As a former Java developer I'm a big fan of commenting my classes so that later when I run the javadocs executable I get a complete description of the API for my entire application. 

Nintex forms (and workflows) are not suitable  for this kind of self-documentation.  There is no way to include comments in each form control, rule, variable, etc. or workflow action, and no way to compile them all into a document even if I could.  It would be nice to have that but I'm not holding my breath.  That's why transforming the Form.xml via XSLT seemed so appealing.  Your point about updating the structure of the XML is well-taken, but wouldn't deter me if I could just get this to work because a) the documentation on existing forms would be unaffected and b) it's easy enough to modify an XSL stylesheet if an upgrade changes the structure. It would still be XML (and presumably valid XML) no matter how they chose to reorganize the schema.

So, without either of these two approaches, it is likely that I'll have to go with your approach: focus on the high-level function and skip the details.  This is great for end-users but not so great for developers who may be asked, a year later, to fix a bug in a complex form that someone else built without a detailed description of its internals.


Cheers!

Accept as Solution Reply
Workflow Hero

Re: Form Documentation

What you say about Nintex Workflow is not completely true for on-prem. You can add user comments per action and use the print function 'Print with Notes'.

For Nintex Forms, you can add an hidden label which contain the documentatoion. I know this is a kind of workaround, but still, it let you place documentation inside the form.

Accept as Solution Reply