Category Show-n-Tell Thursday
Bookmark :              

Note: This is Part III of a series.

• Part I can be found here
• Part II can be found here

In the last installment I explained the Generate Design Element Docs agent, and we looked at how it works overall. This installment is diving into two particular functions used in that agent - the getElementType and getUseCases functions.

getElementType function

The first function, getElementType is a generic function I created (with tremendous help from Henry Newberry and Bob Balaban) that will take a look at design element and determine what it is. In MOST design elements there is a special item called $Flags. This item contains one-character flags that indicate a myriad of things about an element - does it have prohibit design refresh/replace flag set, is it formula or lotusscript, etc. However, most elements DO NOT have a flag that says simply "hey, I'm a form!" or "hey, I'm a view!". In fact, those two elements may not even HAVE a $Flags item! Therefore determining exactly what a design element is can be a tricky proposition, which makes this function a bit more involved.

Let's take a look at the function itself, then we'll dive into some of the design decisions I made.

NOTE: The in-line CSS version of this code was too big for the HTML conversion routine in Blogsphere - it was over 32K. So, I had to post it as a graphic so you could see it all. So, to make sure you get the code it is a part of the DesignFlags.txt file available in the Downloads area.

The first thing you may notice that is weird is the colon (":") that I use at the end of many lines. That is an OLD VB syntax that allows you to string together two lines of code on one line. I could have used the traditional format of wrapping those with an End If, but there were so many I thought that this convention lent itself to easier reading.

The beginning of this code checks the flags for obvious ones that define what the element is. If a flag is found, then that flag is returned and the function exits (what's why I use the colon). Notice that the flags are in a certain order, too. If it is an "easy" flag, where the flag defines the element outright, then I use the colon/Exit function call. If, however, the flag is one of the ones used for a view, then there is a bit more work to be done.

For a view there is no single flag that defines it. A view can have one of many flags, or more than one flag. Since there can be more than one flag for a view, I have to use a type of "fall-through" code whereby the flag result will be the last flag I encounter. In this case I didn't add code to figure out all permutations of views (calendar, outline, private, public, shared-private on first use (SPOFU) stored on server, SPOFU stored on desktop, etc.), only the ones I care about - but you could easily add those additional values if you wanted.

After views I check for agent flags. Agents are even trickier than views, because they can be multiple languages, they can be scheduled or triggered, and so on. I have a small if statement that first determines the language of the agent, then it determines if the agent is scheduled or run-as-user. I concatenate these values together to build my agent description.

The next set of If statements is used to check for a Form. There is no single flag that says, "hey, I'm a form"; instead there are certain flags that only forms have, or a form may not have ANY flags. I check for the form-only flags (C, D, V) and set the results appropriately.

If there is no flag, then I have to do a bit more detective work. I check for a couple of items that are either form or view specific. For forms, I check for $FIELDS or $$FORMSCRIPT. For views I check for $VIEWFORMAT.

At this point if I haven't determined some result set, then I have no idea what I am dealing with - and I simply return *UNKOWN*. To test this I ran it over and over until I didn't get an *UNKOWN* anymore - and if I did, then I determined what element was unknown and I looked for some distinguishing characteristic I could use to determine what it is.

Before we get off of this topic and move onto the next function, I want to answer that question that's burning in your mind right now - "This is all great, Rock, but how the hell do I KNOW what all the flags are? Is this some voodoo, ancient geek wisdom you have?" Of course not, silly rabbit. I got Bob to give me the relevant part from the file stdnames.h, which is used in C API programming. In order to make it easier for you, I have created a simple text file that contains the relevant design flag information as well as the help about design flags from the C API Help. You can download this text file from here, which is in my Downloads area.

Conclusion
I think this function is pretty kewl, and really opens up a bunch of possibilities for deconstructing and documenting your code. It can easily be expanded to support more design element types - and if you do so, please share with the class so we can all benefit, ok? Additionally I would love to hear of any uses you find for this function - and I think you'll find quite a few.

Rock
**You know, I spent a fortune on deodorant before I realized that people didn't like me anyway.