If you haven’t heard, LabVIEW 2012 features a redesigned ‘Create Project’ dialog that provides recommended starting points for a breadth of measurement and control systems. One of our primary goals was to ensure that you don’t have to start new projects from scratch, and to help the LabVIEW community leverage well-established and robust architectures. In the process of designing this new experience, we recognized the importance of making it open and extensible by the LabVIEW community so that you can create and add your own custom templates and distribute them to colleagues and customers.
In this entry, I wanted to provide insight into the necessary steps to create a template, package and distribute it as a VI Package file, and also explore how you can add advanced customization capabilities using VI Scripting.
What It Looks Like for an End-User
Before we dive into how this works, I wanted to highlight the end-user experience. I’ve published several recent examples to the Large Application Community using this new approach. The download for the latest version of my Measurement Abstraction Framework is a single VI Package file, which installs two new items to the Create Project dialog in a new category, ‘Demonstrations.’ These two items are ‘Measurement Utility’ and ‘Measurement Plugin.’ (see image below). Imagine providing a similar experience for your colleagues in order to provide starting point that provides the correct communication mechanisms, APIs, UIs, etc…
The ‘Measurement Utility’ configuration page exposes the same default option as the majority of other shipping templates, including the ability to change the name, root, icon and file prefix – this dialog will automatically be used unless overridden or modified. Clicking ‘Finish’ kicks-off the process of copying the contents of this project, applying the user-defined settings as well as the environment defined settings (items in Tools > Options like where to place labels and whether to use icons or terminals).
The ‘Measurement Plugin’ is intended to be a starting point that another developer would heavily customize and change in order to create a new plugin for this framework, so I actually modified the default configuration dialog to add some unique options that programmatically modify the code. As shown below, you’ll see a series of check-boxes that determine which methods to include in a new child class and the hardware class constants that should be placed on the block diagram of a VI within the template.
The Basics of How to Create a Template
Templates are automatically read and loaded from the ‘ProjectTemplates’ folder within the LabVIEW directory. If you go explore this location, the necessary layout should be fairly obvious – exploring the organization of shipping items is probably the best starting point for understanding the basics of how this works, but in brief:
- The first folder is ‘MetaData,’ which contains XML files describing the organization and appearance of items within the ‘Create Project’ dialog. I recommend adding a new XML file for a template you create (in other words, don’t modify the existing ones for what ships with LabVIEW). There are a large number of tags that you can set, but the essential ones are all documented here. As noted in this document, there are only six required tags, including the name, description and path of the project. LabVIEW parses the content of this directory every time the ‘Create Project’ dialog is opened, so changes to the XML will be reflected without having to restart.
- The second folder is ‘Source,’ which is where you’ll need to put the project file and VIs that you would like to have users create a new template from. This is also where you’ll want to put any code that scripts the creation or modification of VIs when instantiating a new template – more on this later.
When you select an item from the ‘Create Project’ dialog, it performs the following steps:
- Copies the necessary source files to the specified location on disk
- Applies all environmental settings to this newly copied project, including source-only settings, appearance settings, name prefixes, icons, etc…
- [Optional] Runs any additional scripting methods to modify the contents of this new instance
I recommend setting up your project development to mimic the directory organization it will be installed to, but I strongly advise against doing actual development in the ProjectTemplates directory. Within the folder of all project I intent to turn into a template, you’ll find a ‘Source’ and ‘MetaData’ directory, and I do development here (under the careful watch of SVN). When I want to test a new version of a template I build it into a VI Package File, which I then use to deploy to the ProjectTemplate directory. Note that this step is very valuable because VIPM allows me to un-deploy (or uninstall) something very easily if something isn’t working right.
Also, be careful that any required components are either statically linked by calling VIs or explicitly loaded within the Project Explorer. If they are not, they will not be copied when a user creates a new template, even if they are in the source directory in ProjectTemplates.
Customizing your Template with VI Scripting
Here’s where things get a little more interesting: the settings that you define in the user dialog are stored in the private data of an object which is then passed to VIs that perform the default behaviors described previously. If we want to add new options we’re going to need to create a child of this class where we can store additional information, and we’ll override the parent’s methods responsible for modification of the template. Lets start with the configuration dialog:
1) Change the ‘Create Project Configuration’ Dialog
If you want to override the UI and/or change the scripting behaviors, you’ll need to create a child class of the MetaData Class, which is the default class that is used to store and pass the configuration settings. Similar to what was done with the Actor Framework sample project, I recommend keeping a ‘scripting’ folder inside of the source directory where this code will reside. The class you need to inherit from is stored in ‘LabVIEW 2012\resource\dialog\NewProjectWizard\MetaDataObj.’ It’s named ‘MetaDataObj.lvclass.’ Obviously, you’ll need to bring it into memory (just drop it onto a block diagram temporarily) and then create a new class that inherits from it.
Once you’ve create this child class, you’re going to want to create the VI that contains the custom UI and override the method that defines the path to this UI I strongly recommend just copying the custom UI from either the Measurement Plugin I wrote, or from the Actor Framework sample project, as you’ll need the connector pane to be identical.
The image above illustrates the components in the project that you’ll need to modify or create.
Modify the private data of the child class to contain the additional parameters and settings the user will configure though this interface, as they will be stored in the object. Once created, be sure this new VI containing the UI is a member of the child class you created and override the method ‘Read Spec Page Path.vi’ to return the path to the VI with the UI.
To see an example of how this works, explore the Actor Framework directory, which has a custom UI. You can find this here if you have LabVIEW 2012 installed: ‘ProjectTemplates\Source\Core\Actor Framework\scripting\TwoTasksMetaDataObj.’ You can also explore the scripting folder that’s installed by the Measurement Abstraction Utility, which will be here: ‘ProjectTemplates\Source\Measurement\scripting\MsmtMetaDataObj.lvproj’.
Finally, you’ll need to add ‘MetaDataClass’ to your XML document and set the value to the relative path where this new child class will reside. As an example:
2) Writing the Code to Execute Scripting Methods
The VI that will be run after the code is copied and settings are applied is determined in the XML. Assuming that you don’t want this VI to be seen when running, you’ll want to set the mode to ‘AfterPage2NoUI,’ as exemplified below. You’ll then need to set the path to VI that will be run.
The VI that you point to will need to enforce a standard connector pane that include the reference of the project that was created and the object that will be instantiated by the Create Project dialog (this is the object that you will have stored all the user settings in). I won’t go into how to do scripting in this entry, but the sky is the limit as far as what you can do with a reference to the project and a little know-how. There are a lot of great resources on how to take advantage of scripting in LabVIEW. If you’re new, check out this document on scripting. The image below illustrates the inputs to the VI that will be used to modify the copied files.
Again, I recommend installing the Measurement Abstraction Utility and browsing the code that is installed to the ProjectTemplates folder for an example of how this can be done.
Distributing a Template as a VI Package File
The process of manually putting the XML file, the scripting code, and the source files into the correct directory could be a painful one – and it would only get worse if you had to this manually every time you wanted to distribute an upgrade or uninstall an older version. Thankfully, you can use VI Package Manager to create a single file that puts everything in the right location.
From within VI Package Manager, create a new package by clicking on ‘Show VI Package Builder’ from the menu. In the first window that appears, point the builder to the root directory that contains the ‘Source’ and ‘MetaData’ folders where you developed the template. The 2012 version of VI Package Manager includes a new destination for ‘ProjectTemplates.’ Make sure that the ‘MetaData’ and ‘Source’ folders in your build both target this location, as shown below:
Those are the only things you’ll need to do differently to distribute a template, but you can add custom palettes so that a user not only starts with a template, but they also have a defined API with all of the VIs they may need to use for development. For more information on this and the other powerful features of VI Package Manager, check out jki.net/vipm.
The create project dialog is a powerful new tool to simplify the creation and distribution of templates, which stands to be an extremely useful feature for developers working in team-based environments that need to distribute and enforce standard style guidelines, UI layout, or perhaps make it easier for developers to contribute components within a larger project.
As always, please comment below if you want any additional information or have questions!