Updated 8/29/2006
In a previous post, I showed how to use a GiftWorks Addin. In this post I will expand on that same HelloWorld example by explaining the contents of the addin file. The HelloWorld Addin is simply an xml file with a specific structure recognized by GiftWorks. There are several more elements that can be included in an addin file, but for this example we will only focus on the <taskmenu> element.
Here is the HelloWorld Addin file:
1: <gml id="MissionResearch_HelloWorld">
2: <info>
3: <title>HellowWorld Addin</title>
4: <versions>
5: <version match="2.0.*.*" module="version2" />
6: </versions>
7: </info>
8: <module id="version2">
9: <taskmenu>
10: <menu task="graphite://provider/startpage">
11: <item section="RELATED TASKS" type="script" text="Hello World" before="Add a Donor">
12: <![CDATA[App.Shell.MsgBox("HelloWorld!")]]> 13: </item>
14: </menu>
15: </taskmenu>
16: </module>
17: </gml>
identify your addins
Lines 1 and 3 are used to identify your addin. The id attribute in line 1 is a key that uniquely identifies your addin. The contents of this attribute are up to you. It just has to be unique among other addins used within your copy of GiftWorks. It can only contain alpha-numeric characters and underscores. I will typically use something prepended with my companies name. This should be unique enough as long as someone else in my company doesn't have the same idea. The id in Line 1 is not something seen by GiftWorks users. Line 3 is the <title> element. This title will show up in the GiftWorks Addin Manager and will identify your addin to the GiftWorks user. This example doesn't use them, but you can also include <publisher>, <description> and <website> elements to further identify your addin.
addin versioning
Supporting addins becomes very tricky as GiftWorks functionality is enhanced. For this reason our addins need to specify the version of GiftWorks that it will support. Depending on the functionality of your addin you may need to update it when a new version of GiftWorks will be released. A single addin file can target several versions of GiftWorks. When we officially release a software development kit (SDK) for building addins we will document the rules that we use when incrementing version numbers within GiftWorks. You will be able to use these rules to know when to provide updates to your addin. Along with the addin SDK we will support a developer community that will get notified of version changes and have the opportunity to test prerelease versions of the software.
Like I said, a single addin file can target multiple versions of GiftWorks. Minimally you need a single <version> element with a match attribute and a module attribute in every addin file. The match attribute is used to figure out what version should be selected and the module attribute points to the corresponding <module> section within the addin. If you need to support multiple version you can include more <version> elements and <module> sections within the file. The <version> elements will be processed from top to bottom in case there is any overlap.
For this example, I'll target a small range of GiftWorks' versions. GiftWorks will support addins starting from GiftWorks Update 3 (version 2.0.80.00), so by using '2.0.*.*' I've enabled the use of my addin for GiftWorks version 2 or higher. By specifying the match string like this it should allow future updates of GiftWorks 2006 to use this addin.
adding a menu item
This HelloWorld example just inserts a menu item on the start page in GiftWorks. When the user clicks on the new menu item a script is called which displays the message "HelloWorld" in a popup. Lines 9-15 defines where the menu item is inserted and what happens when you click the menu item. There are several options when defining new menu items, but to keep this post as short as possible I will only describe the ones used in this example.
Line 10 specifies the menu to modify. From a high level, GiftWorks is just a series "pages" that the user navigates thru (very similar to a website). Each page performs a unique function. Along the left side of each page you will typically find a menu--a list of links that the user can use to perform a function related to the current page. In development, the "pages" are called tasks and they are uniquely identified by a URL. At any point while using GiftWorks you can see the current task name by pressing SHIFT-F6. The "current task" line lists the task's URL. This is how we identify what menu we want to modify in our addin. We use 'graphite://provider/startpage' in line 10 of our example.
Each menu is divided into sections. On the start page we have two section: RELATED TASKS and DID YOU KNOW. The <item> element in line 11 of our example represents a single new menu item that gets placed in the RELATED TASKS section directly before the existing 'Add a Donor' menu item. The text attribute contains the name of the new menu item as seen by the GiftWorks user. The type attribute tells GiftWorks what should be done when the user clicks the menu item. In this case it executes a script which is included within the <item> element on line 12.
Line 12 contains the actual script that is executed when the user clicks the new menu item. I have enclosed the script within CDATA brackets so we can use characters that may not be recognized in xml. I recommend you that you just use them around all your addin scripts.
the script
Explaining everything that can be done with scripting is way beyond the scope of this post. GiftWorks Addins support Microsoft's ActiveX scripting. You may use any ActiveX scripting language by specifying a language attribute in the containing element tag. The default language in an addin script is VBScript (Microsoft Scripting).
The key thing to note in this example is the App reference. This single reference gives the addin developer access to the entire object model within GiftWorks. The same object model that the Mission Research developers use to create GiftWorks. I won't go into detail yet, but most Windows developers will know how to view the GiftWorks object model in an object browser. If you aren't familiar with object models or App references, you will need to wait a bit until I can go into more detail or find a resource that can help you figure it out.