Rough Book » infusionsoft http://vivin.net random musings of just another computer nerd Tue, 17 Jan 2012 23:32:52 +0000 en hourly 1 http://wordpress.org/?v=3.3.1 Generating API Documentation from XML using XSLT http://vivin.net/2011/07/09/generating-api-documentation-from-xml-using-xslt/?utm_source=rss&utm_medium=rss&utm_campaign=rss http://vivin.net/2011/07/09/generating-api-documentation-from-xml-using-xslt/#comments Sat, 09 Jul 2011 18:39:04 +0000 vivin http://vivin.net/?p=1748 I work at Infusionsoft, and we offer our customers API access. Visibility and access to the various tables and their fields is controlled by an XML file on our end. Naturally, our customers require user-friendly documentation that tells them what tables and fields they can access and in what manner. Previously, a former developer had written a maven goal that would generate the API documentation from the XML file. Unfortunately this was something that he did on his own and the code wasn’t in our subversion repository. When that developer left, we decided to take a look at the code to see if we could continue generating the documentation using the maven goal. We determined that the original solution though helpful, involved a lot of work in Java simply to generate API documentation. This was when I suggested using XSLT as it would be a remarkably lightweight solution and it is also perfectly suited to this task. My colleagues agreed and so I decided to go ahead with the task. There was one slight problem though. I had very little experience with XSLT! But how hard could it be? I love learning new things anyway!

As it turned out, it wasn’t all that hard (this doesn’t mean I am an expert; I’m still a novice!). I went through a few tutorials and examples and in about an hour or so I had a basic idea of the language (especially its functional aspect). It took me about a day to write out the entire XSLT document (tweaks and all). Most the time was spent looking up instructions in XSLT to do certain things (string operations, date formatting, etc.).

Here’s an example of what I had to work with, from the XML document (this is not the exact document; it’s just an example that follows the structure):

<tables>
 <table name="Contact" access="EDAR">
  <fields>
   <field name="FirstName" />
   <field name="LastName" />
   ...
   <field name="LastUpdated" type="DateTime" access="R" />
  </fields>
 </table>
</tables>

As you can see, the structure is pretty simple. As far as the resulting API documentation was concerned, what I wanted was an index.html that contained links to other pages. These other pages should be structured so that there is an HTML page for each table. This page will contain information about the table fields, as well as their access modes (E: Edit, D: Delete, A: Add, R: Read). As it turns out, in XSLT 1.0, you cannot create separate documents. You can only transform one document into another document. In XSLT 2.0 however, you can transform one document into multiple documents using the xsl:result-document instruction.

The XSLT that I’ve written is pretty straightforward (if you know XSLT; even if you don’t, you can kinda get the gist of it from the instructions). The only thing I had trouble with was translating the access-mode letters into their expanded forms. To do this, I had to write a recursive template that looks at each character (there are other ways). This is where the functional aspect of XSLT comes into play. Once I started thinking of XSLT like Lisp, it became much easier to write my solution because I wasn’t fighting the language. Anyway, here is my solution:

<?xml version="1.0"?>
<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

 <!--
  XSLT document that transforms Infusionsoft's API Field-Access XML into HTML pages
  Author: Vivin Suresh Paliath
  Date: 4/11/2011
 -->

 <xsl:output method="text" />
 <xsl:output method="html" indent="yes" name="html" />

 <xsl:template name="translateAccessModes">

  <xsl:param name="accessModes" />

  <xsl:if test="string-length($accessModes) > 0">

   <xsl:variable name="accessMode" select="substring($accessModes, 1, 1)" />
   <xsl:choose>
    <xsl:when test="$accessMode='E'">Edit </xsl:when>
    <xsl:when test="$accessMode='D'">Delete </xsl:when>
    <xsl:when test="$accessMode='A'">Add </xsl:when>
    <xsl:when test="$accessMode='R'">Read </xsl:when>
    <xsl:otherwise>Unrecognized Access Mode: <xsl:value-of select="$accessMode" /> </xsl:otherwise>
   </xsl:choose>

   <xsl:call-template name="translateAccessModes">
    <xsl:with-param name="accessModes" select="substring($accessModes, 2, string-length($accessModes))" />
   </xsl:call-template>

  </xsl:if>

 </xsl:template>

 <xsl:template match="/">
  <xsl:result-document href="tables/index.html" format="html">
   <html>
    <xsl:comment> Generated via XSLT on <xsl:value-of select="format-dateTime(current-dateTime(), '[F], [MNn] [D], [Y] at [h]:[m01] [P]')" /> </xsl:comment>
    <head>
     <title>Infusionsoft Table-Access Documentation</title>
     <link rel="stylesheet" href="styles.css" />
    </head>
    <body>
     <h2>Database Tables &amp; Fields</h2>
     <div id="tables">
      <ul>
       <xsl:for-each select="//table">
        <xsl:variable name="filename" select="concat('tables/', @name, '.html')" />
        <xsl:variable name="tableAccessModes">
         <xsl:choose>
          <xsl:when test="@access!=''">
           <xsl:call-template name="translateAccessModes">
            <xsl:with-param name="accessModes" select="@access" />
           </xsl:call-template>
          </xsl:when>
          <xsl:otherwise>Edit Delete Add Read</xsl:otherwise>
         </xsl:choose>
        </xsl:variable>
        <li>
         <xsl:element name="a">
          <xsl:attribute name="href"><xsl:value-of select="concat(@name, '.html')" /></xsl:attribute>
          <xsl:value-of select="@name" />
         </xsl:element>
        </li>

        <xsl:result-document href="{$filename}" format="html">
         <html>
          <xsl:comment> Generated via XSLT on <xsl:value-of select="format-dateTime(current-dateTime(), '[F], [MNn] [D], [Y] at [h]:[m01] [P]')" /> </xsl:comment>
          <head>
           <title><xsl:value-of select="@name" /> Table (Access Modes: <xsl:value-of select="substring($tableAccessModes, 1, string-length($tableAccessModes) - 1)" />)</title>
           <link rel="stylesheet" href="styles.css" />
          </head>
          <body>
           <h2><xsl:value-of select="@name" /></h2>
           <table>
            <tr>
             <th>Field Name</th>
             <th>Type</th>
             <th>Access</th>
            </tr>

            <xsl:for-each select="./fields/field">

             <xsl:variable name="fieldType">
              <xsl:choose>
               <xsl:when test="@type!=''"><xsl:value-of select="@type" /></xsl:when>
               <xsl:otherwise>String</xsl:otherwise>
              </xsl:choose>
             </xsl:variable>

             <xsl:variable name="accessModes">
              <xsl:choose>
               <xsl:when test="@access!=''">
                <xsl:call-template name="translateAccessModes">
                 <xsl:with-param name="accessModes" select="@access" />
                </xsl:call-template>
               </xsl:when>
               <xsl:otherwise><xsl:value-of select="$tableAccessModes" /></xsl:otherwise>
              </xsl:choose>
             </xsl:variable>

             <xsl:variable name="rowClass">
              <xsl:choose>
               <xsl:when test="(position() mod 2) = 0">even</xsl:when>
               <xsl:otherwise>odd</xsl:otherwise>
              </xsl:choose>
             </xsl:variable>

             <xsl:element name="tr">
              <xsl:attribute name="class"><xsl:value-of select="$rowClass" /></xsl:attribute>
              <td><xsl:value-of select="@name" /></td>
              <td><xsl:value-of select="$fieldType" /></td>
              <td><xsl:value-of select="$accessModes" /></td>
             </xsl:element>
            </xsl:for-each>

           </table>

           <h2><a href = "index.html">Back to list of tables</a></h2>

          </body>
         </html>
        </xsl:result-document>

       </xsl:for-each>
      </ul>
     </div>
    </body>
   </html>
  </xsl:result-document>
 </xsl:template>
</xsl:stylesheet>

That’s all there is to it! To actually use the XSLT document to generate the API HTML files, I used Saxon, which supports XSLT 2.0. This is how I used it:

java -cp saxon9he.jar net.sf.saxon.Transform -t -s:api_field_access.xml -xsl:api_doc.xslt

So if you’re an Infusionsoft customer or a developer who is reading the API documentation, you now know how it was generated!


Comments]]> http://vivin.net/2011/07/09/generating-api-documentation-from-xml-using-xslt/feed/ 5 Comments Sorry for the delay http://vivin.net/2008/08/08/sorry-for-the-delay/?utm_source=rss&utm_medium=rss&utm_campaign=rss http://vivin.net/2008/08/08/sorry-for-the-delay/#comments Fri, 08 Aug 2008 20:32:18 +0000 vivin http://vivin.net/?p=386 I’m really sorry for not updating this journal for… well, seems like forever. I figured I’d start writing regularly but that turned out to not be the case. A few things got in my way. Ever since I started working at Infusionsoft, I’ve had less of a desire to come back home and sit at the computer… again. The reason being, that most of my code-cravings are taken care of at work. Seriously, I love it. As a result I don’t really feel like coming back home and sitting in front of the computer.

The second thing was that my parents were here for a long time, and so I was spending most of my time with them. Then what else… oh yes, there was a thunderstorm and the power went out and my server decided that it didn’t recognize the NIC it had recognized for the past four years. So I went and bought a new one, and as soon as I plugged it in, it recognized the old one. I love computers. Then of course, there’s the fact that I was just pretty lazy. For some insane reason I decided that I wanted to upgrade the server to FreeBSD 7.0 and then I kinda just dragged my foot on setting everything else up.

Finally, there was my getting deployed again. Yeah, you read that right. I was going to Iraq… again. I pretty much found out about it around the time of my WLC training. So there was all the preparation for that. I really wasn’t looking forward to going (who does, anyway?) but I figured I had to (all that duty stuff, raising my right hand, taking the oath). However a few weeks ago I found out that I really didn’t have to go. As it turned out it hadn’t been two years since I got back and so I had the option of not going. So I told my readiness NCO that I didn’t want to go. I have my career to think of, and I think one tour in Iraq is more than enough. I was pretty torn when I had to make that decision. It took me about half a second to decide what I wanted to do. Part of me almost wanted to say “yes”. But I think this is the better decision.

Anyway, I just wanted to let you all know that I’m alive and that I’m definitely going to try and write more frequently on this journal. I’m doing a lot of exciting things at work and I’d like to be able to write about them. So, until next time…


Comments]]> http://vivin.net/2008/08/08/sorry-for-the-delay/feed/ 1 Comments A lot of stuff http://vivin.net/2008/02/12/a-lot-of-stuff/?utm_source=rss&utm_medium=rss&utm_campaign=rss http://vivin.net/2008/02/12/a-lot-of-stuff/#comments Tue, 12 Feb 2008 23:08:00 +0000 vivin http://vivin.net/?p=383 I didn’t update this site for a while because I had a lot of stuff going on. A lot happened towards the end of last year. My house was destroyed, and then it was rebuilt. While that was going on, I also lost my job when Intel decided to “redeploy” my entire group. I was offered an option to look for positions within the company, but I declined. I honestly wasn’t doing as much programming as I would have liked, so I decided to look for jobs outside Intel. I interviewed with Google and didn’t get in despite doing really well (their words) on the phone and in-person interviews. I got a call back from the recruiter who said that “although the interviewers really liked you and thought that you were incredibly smart and knowledgeable, they didn’t feel that your skills are a good match for the position”. I thought it was a standard “Thanks, but no thanks” response and I was a little disheartened. To be honest, my faith in my own skills and knowledge was a little shaken. I talk to my friend Iliyan (he works and google and he’s the one who actually referred me) and he said that they were actually telling the truth. Apparently, at Google they try to match you up pretty well with your job. If they feel that you don’t match up with the position, they don’t offer it. He said that if I had applied to Google and Mountain View, instead of Phoenix, I would have received an offer for sure. He also let them know that they made a mistake in not hiring me. Either way, I wasn’t all that depressed.

I got a few more offers and did a few more interviews before finally accepting a position at Infusion Software. They basically write CRM (Content and Resource Management) Software for small businesses. They are a relatively new company. I have been here for a month and I’ve been loving it since my first day. The first day I walked in, they basically said “Here’s your system. Pick an OS and install it and set up your development environment”. I was like “Awesome!”. Of course, I set up PC-BSD (which is basically a FreeBSD distro). The environment at Infusion Software is very energetic and fast-paced. The demographic is also rather young. During my interview they showed me around and when I got to the developer room, they showed me a projector and said “This is where we play Halo or Guitar Hero 3 when we need to take a break”. ‘Nuff said. I’m glad everything eventually worked out. I was rather stressed after my house got wrecked, and to add to it, I got laid-off. The way my friend Suhrid puts it. “You have the weirdest luck in the world. Really bad stuff happens to you, but then something really cool happens after that to make it better than before… you got to remodel your home for a great price, and you got a better job!”

My parents came down for a month at the beginning of January. My mom’s staying behind to help me set up the house. Of course, because of that I had to tell my girlfriend that she couldn’t come over anymore (this is all true, yes it is). Oh yeah, so I’m renting out my house. My parents had bought a house here that they don’t live in. So I’ve basically moved over there. It’s a bit of a drive to places, but nothing too bad.

Oh yes, I finally got to put my citizenship to use. Yes, I voted in the primaries. I registered as Republican so I could vote for Ron Paul. Let’s just say that I believe in a lot of what he says because I identify myself as Libertarian. I know a lot of people said that he wasn’t going to win, but that wasn’t the point. This country needs to change. It’s constitutionally a multi-party system, but the only parties that matter are the Republicans and Democrats and they haven’t been doing anything for this country. The current administration has done a great job of ignoring that piece of paper this country was founded up. The subtle erosion of Civil Rights alarms me. We need to remember what this country was founded upon. Honest, law-abiding citizens should have no fear of their government. That is why I support Ron Paul. It is besides the point that he didn’t win. We need to challenge the current situation. We need to change the current situation. Of course, the idiotic media ignored Ron Paul and didn’t even talk about him. Despite that, the man was able to garner a large and loyal following through the internet. What that says is that there are people who are willing to listen and who want to listen and who want change. The sad truth is that the people with big pockets, and big media exposure get all the attention, and not the people with the good ideas. I hope that in time his ideas will prevail. I hope in time Americans will realize that this country needs to get back to its roots.

That’s about it. I’m going to try and update this blog a little more frequently, but no promises.


Comments]]> http://vivin.net/2008/02/12/a-lot-of-stuff/feed/ 1 Comments