Best Practices: Working with Forms Tool Scripts in Groove 2007

  • Article

Summary: Review the recommended best practices for developing forms-based applications in Microsoft Office Groove 2007. (11 printed pages)

Joshua Mahoney, Microsoft Corporation

Josh Goldman, Microsoft Corporation

November 2007

Applies to: Microsoft Office Groove 2007

Contents:

  • Using Scripts in the Groove Forms Tool

    • Using a Separate Groove Workspace for All Development

    • Identifying Tools with a Unique Tool Name and Version Number

    • Design Name

    • Design Version

    • Naming Fields Explicitly

    • Defining Programmatic Aliases

    • Using Clear Names to Organize Script Files

    • Maintaining Version Number of Script Files

    • Placing System Callout Implementations in Form Script File

    • Using CSS-Defined Style File

  • Guidelines for Scripts

    • Considering UI Modes in System Callouts

    • Enclosing Top-Level Scripts in Try-Catch Blocks

    • Handling Errors and Providing Error Messages

    • Using Documented, Supported API Variables and Functions

    • Using Scripting Conventions

    • Adding Comments in Script Code

  • Conclusion

  • Additional Resources

The Microsoft Office Groove 2007 Forms tool provides a framework that enables you to create customized forms for displaying and entering data. You can create fields, forms, and views and enhance the look of your forms using available styles or by creating custom styles.

You can also use form scripts to add custom script code to your Groove Forms tool. These scripts run when the user is accessing the form. Scripts make it possible for you to extend the capabilities of the Forms tool to handle specialized application requirements.

This article describes how to develop the design and how to organize the design elements so that the design is easier to maintain. You can use the best practices for any Forms tool design even if you do not add scripts.

Using Scripts in the Groove Forms Tool

In addition to standard HTML Document Object Model (DOM) script programming, your scripts can do the following:

  • Run when certain Forms events occur, such as form initialization and submitting new or updated data.

  • Access Groove services to get context information such as the members of the workspace, or to perform methods such as sending an instant message.

  • Access data in the field values in the currently displayed form and underlying Forms record.

  • Perform lookups on data in the current tool, or in other Groove Forms tools, or in InfoPath Forms tools in the same or other workspaces.

  • Define a function that is executed to provide an initial value for a field.

You can associate each form script with a form, and execute it on HTML DOM events or on Groove Forms tool events such as form initialization. Forms scripts have access to the HTML DOM, to the underlying record, and to the Groove environment.

This article describes how to develop the design and how to organize the design elements so that the design is easier to maintain. The following best practices are useful for any Forms tool design even if you do not add scripts.

Follow these recommendations to make it easy to update and maintain Groove forms that you create for your team or for others.

Using a Separate Groove Workspace for All Development

During the process of developing a Groove Forms tool, it is a good idea to make changes and publish new versions of the tool often, for testing purposes and to refine the tool’s design.

Be sure to work on your tools in a separate development workspace because any changes to the tool you save are sent to all members of the workspace that contains the tool.

Limit the membership of your development workspace to only those users participating in the development or testing of the tool; otherwise members of the space who are not working on the tool receive and process data unnecessarily.

Use the Replace Design feature to show an iteration of the tool to end users for review when you make significant changes. The Replace Design feature of the Forms tool updates an end user workspace with the latest version of the tool. If you only make small changes, you can make the changes in the existing tool and not replace the design.

Be sure to save incremental versions of the template of the tool as you develop it so you can revert to a previous version, if necessary, or discard changes you do not want to keep. Template backups make it easy to get back to the last working version of the tool.

Identifying Tools with a Unique Tool Name and Version Number

The Form Design Name, Version, and Description properties provide a mechanism for external applications (including scripts) to identify a Forms tool and to document the design for end-users and other forms designers.

Be sure to specify a design name, version, and description even though these fields are optional. There is no automated mechanism for incrementing the design version number; it is the responsibility of the forms designer to increment the version number when appropriate.

Enter About This Tool information

  1. From the Designer list in the workspace toolbar, click Open Design Sandbox.

  2. On the Settings and Options page, click the About This Tool tab.

  3. In the text boxes, type a design name, design version, and description.

  4. Click Apply and Publish Sandbox to save your changes.

  5. From the Help menu, choose About This Tool to display the design name, design version, and a description for a tool.

Follow these guidelines when specifying a design name and incrementing the design version number.

Design Name

The design name is a unique string that identifies the organization that designed the Forms tool and the application class or purpose of the Forms tool. Use the same URN format that is used in Groove to identify other templates with the general format of “urn:your-company-namespace:unique-name”. Design names cannot contain spaces. If you are modifying an existing Forms tool template to create a new version and use of the tool, give it a new URN.

Design Version

The design version provides a way for form designers to indicate and document changes they make to a Forms tool template. After a Forms tool template is deployed and external applications are developed to access the tool, it is very important to provide information about modifications to the tool using the design version number. Application developers can ensure that their applications are working with the correct version of the Forms tool using this number. External applications can be affected when fields, views, and forms are added to the Forms tool, or when an existing one is modified. Typically, external applications are not affected by modifications to the user interface design, such as moving a field in a form.

The design version is an ordered set of four digits delimited by periods, and is stored as a string. The design version conforms to the version identification scheme: (0.0.0.0). From left to right, the four version digits represent:

  • Major version

  • Minor version

  • Custom version

  • Build number

Use the following guidelines to increment the design numbers:

  • Major version indicates an incompatible Forms tool schema change. For example, if you modified the Issue Tracker template and deleted the AssignedToIndividual field and added IssueManager, IssueTester, and IssueDocumenter fields, you should change the major version number. A major version upgrade of a Forms application should be considered a different application altogether. While functionally the application remains the same application class, (it is still an Issue Tracker application), it uses a completely different record data schema.

  • Minor version indicates no incompatible schema changes that would affect existing external applications. A minor version upgrade can add new fields, forms, and views to a Forms tool but cannot delete or make schema modifications to existing ones.

  • Custom version is considered a patch release, which has specific functionality or modifications to serve a specific purpose.

  • Build number is a designer-specified increasing sequence used to associate a particular software build sequence to the forms application.

For more information about these properties, see Design Names, Versions, and Descriptions for Groove Forms Tools.

Naming Fields Explicitly

Be sure to name all fields in a form. You cannot change field names after the field is created. If you do not enter a field name explicitly, the name is derived from the contents of the Label property of the field.

Field names generated from the Label property are difficult to work with in a script because any spaces, punctuation, or other characters are replaced.

For example, the field label Enter Customer First Name**:** results in the field name “Enter_32Customer_32_First_32Name_58”.

It is difficult to work with field names generated from the Label properties in script, external integration code, and within the Designer UI.

Defining Programmatic Aliases

If a Forms tool is localized for multiple languages, the form and view names should be translated into the local language because they are displayed to the user. If you use the form or view name in a call to the OpenFormByAlias Method or OpenViewByAlias Method, you have to modify the script files each time the tool is localized. To avoid this problem, define a programmatic alias for each form and view defined in your tool. Since this alias is not displayed to the user, it does not need to be translated when a tool is localized. You can define a programmatic alias on the form or View Options tab in the Forms tool designer. It is a good practice to define an alias whenever you create a form or view.

Using Clear Names to Organize Script Files

Use one script file to contain all the functions and variables in a tool that are commonly used in all forms in a tool and name the file Common.js or Shared.js.

Any script that is unique to a specific form should be saved in a single script file that uses the same name as the form.

For example, if the form is named Contact, save all scripts in a file named Contact.js or ContactFormFunctions.js and keep the naming consistent across all scripts.

This naming convention makes it easier to maintain scripts and also ensures that the form only loads the script file that it uses. This speeds up tool loading and performance.

Maintaining Version Number of Script Files

The Forms script editor is very simple and does not provide color-ahead or type-ahead coding help. Typically, you develop a script in an external editor and then copy and paste the script into the script editor. Be sure to maintain a version number at the top of each script file especially if there is more than one developer working on a tool.

Developers can easily determine which script file (if any) is updated using the version number and can verify that their local copy is up to date before making any additional changes. Maintaining the script version number at the top of the file is also helpful if you work with a common script library that is across multiple tools. It is easier to determine when the script library file is updated and which version of the library tools are in use.

Placing System Callout Implementations in Form Script File

Place system callout implementations in their respective form-specific script file to make scripts easier to find and maintain.

Enter a function reference in the system callout script file and define the function in the specific script file defined for the form. This provides a single file that contains the body of all the functions that are used on the script.

Use the following naming convention for the function names of the system callout implementations:

form_name_system_callout_name

For example, if you are implementing the following callout OnAfterInitialize for the Contact form, name the function Contact_OnAfterInitialize and place it in the form-specific-file, Contact.js.

Any calls to the script in the system callout script editor are calls to the implementation in the form-specific script files. This provides developers with one location to make changes to any script used by the Contact form.

Using CSS-Defined Style File

Assign class names defined in Style files to fields in the Designer or use other cascading style sheets selectors to achieve the desired visual effect. This makes it easier to maintain visual formatting and allows a designer familiar with cascading style sheets to alter visual formatting without editing a script.

Guidelines for Scripts

Follow these general guidelines to create easy to maintain scripts.

Considering UI Modes in System Callouts

It is important to remember that your system callout script can be called when the user is performing different actions with the form. For example, the OnBeforeInitialize script can be called when the user is:

  • Creating a record

  • Updating an existing record

  • Viewing an existing record

  • Viewing the record in the preview panel

  • Using the form to search the records

Your script may need to function differently in each context. For example, your script may need to enable or disable a field based on whether the user is viewing or updating the record.

Enclosing Top-Level Scripts in Try-Catch Blocks

A top-level function is any function that is the first entry point where a script performs an operation. System callout implementations and event handlers for buttons or fields are considered top-level functions by this definition.

The Forms tool catches errors that occur in user-defined functions with no indication to the end user or developer that an error occurred. This is why it is good to wrap any script in top-level functions within try…catch blocks and display, or otherwise handle any resulting errors. This puts the developer in control of how to handle errors (display them or not or take some other action) which can make troubleshooting easier.

Handling Errors and Providing Error Messages

Be sure to handle errors and display error messages.

Generally, it is not a good idea to hide an error and not display an error message. Users are confused if a feature is not working as expected but there is no indication to the user or description of the problem; the user cannot correct his or her mistake.

Ignoring or hiding errors can also make troubleshooting more difficult. Be sure to add comments that fully document any circumstance or situation that leads to an error that you track but do not display an error message.

Using Documented, Supported API Variables and Functions

The Microsoft Office Groove 2007 Forms Developer Reference contains the complete list of supported API variables and function. For example, you may determine the definition (when using Microsoft Visual Studio) of global variables “g_” prefix, such as g_IsCreateAnother. These global variables and functions that are visible in the JavaScript sources are internal variables and functions and are not part of the supported API. While it is technically possible to use these variables and functions, you do so at the risk of those variables and functions being changed or removed in a later version of Groove (causing your tool not to function).

You should avoid system implementation for the same reasons. Examples of implementation details are the format of URLs returned from script lookups, and custom attributes on form fields such as ISREQUIRED.

Using Scripting Conventions

Follow these scripting conventions.

  • Declare all variables using the var statement to keep them within the global scope.

  • End all statement with a semicolon.

  • Place global variable declarations at the top of script files.

  • Avoid using the g_ prefix on variables

  • Use consistent casing conventions:

    • For example, use lower case for the first word then initial capitals for following words such as "someVariable".

    • For function names, use initial capitals for all words, such as "SomeFunction".

  • Use consistent spacing, indenting, and formatting.

The following script presents an example of the conventions in use.

Example of consistent formatting:

function OpenParentDocument()
{
    try
    {
        var curRec = GetFormRecord();
        if (curRec.HasParentRecord)
        {
            var parRec = curRec.OpenParentRecord();
            var partFrmID = parRec.OpenField(cRecordFormsToolFormID);

            GetApp().NavigateToForm(partFrmID, parRec.OpenField(cRecordIDField));
        }
        else
        {
            GetApp().DisplayStatusBarMessage(
"The current record has no Parent; parent record could not be opened", 
            GrooveMessageBoxIcon_Information);
        }
    }
    catch (err)
    {
        ShowError(err);
    }
}

Example of inconsistent formatting:

function OpenParentDocument (  ) {
    try {
        var curRec=GetFormRecord();
        if (curRec .HasParentRecord  )   {
        var parRec =curRec.OpenParentRecord();
        var partFrmID = parRec. OpenField(  cRecordFormsToolFormID);

            GetApp().NavigateToForm(  partFrmID , parRec.OpenField(cRecordIDField)) ;
        }
        else
        {
        GetApp().DisplayStatusBarMessage
("The current record has no Parent, thus parent record could not be opened", GrooveMessageBoxIcon_Information);
        }
    }
    catch (  err  )
    {
ShowError(err);
    }
}

Adding Comments in Script Code

Use descriptive and meaningful comments to describe script statements and sections of logic that are complicated or unclear. Avoid comments that are vague or state the obvious, such as //getting data or //setting the variable.

Use comments to help you remember why you wrote the script the way that you did. Comments can help you since they clarify decisions made at the time of development and they help other developers understand the code when they work on it and make changes.

Conclusion

You can use scripts to add custom script code to your Groove Forms tool and to extend the capabilities of the Forms tool to handle specialized application requirements. This article detailed a number of best practices to use to develop the design and to organize the design elements so that the design is easier to maintain. These best practices are useful for any Forms tool design even if you do not add scripts.

Additional Resources

For more information about Microsoft Office Groove 2007 Forms development, be sure to take advantage of the following resources: