Microsoft Project 2002 Project Guide Architecture and Extensibility
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
Preethi Ramani, Marcel Parent, and Laurie Hughes
Microsoft Corporation
June 2002
Applies to:
Microsoft Project Standard 2002
Microsoft Project Professional 2002
Summary: The Project Guide in Microsoft Project 2002 is a new tool designed to encourage new and legacy users to discover new features and to assist novice users to quickly and easily initiate and organize projects. For more versatility, the Project Guide is fully customizable, so that an organization can change the content and behavior of the Project Guide to conform to their own project management framework.
Note For information on customizing the Project Guide, see Introduction to Customizing the Microsoft Project Guide.
Contents
Introduction
The Project Guide
Project Guide Architecture
Security
Custom gbui:// Protocol
Conclusion
Introduction
The Microsoft® Project 2002 Project Guide was developed to make Microsoft Project easier to use for beginning users. The Project Guide is a new interface element that complements the existing, and still familiar, Microsoft Project interface. There are three main components to the Project Guide:
- Project Guide toolbar is a command bar for top-level navigation that contains buttons for the main areas of the Project Guide.
- Side pane displays tasks within each area of the Project Guide and provides instructions on how to carry out the activities. Actions in the side pane affect the views and information displayed in the main view area.
- Main view area is the primary area for viewing and editing project information and is where users perform their work. The views and pages displayed depend on the task the user is following in the side pane.
The Project Guide can also be customized and extended for your organization. For example, your organization may want to change particular steps within a project management process, outline their own unique processes, and add links to additional information.
The Project Guide
Microsoft Project is sometimes perceived as a complex, difficult-to-use application. Many Microsoft Project users don't have full knowledge and understanding of the project management domain. And many existing Microsoft Project users may be unaware of many of the product's key features.
Therefore, the Project Guide was developed to:
- Give new users a clear path to follow through the primary steps involved in the project management process.
- Increase the discoverability of the primary features in the application.
- Integrate the decision-making context and domain knowledge with an interactive user interface.
Elements of the Project Guide
The main elements of the Project Guide are:
- Project Guide toolbar Displays buttons for top-level goal areas.
- The Project Guide toolbar is the top level of a navigation hierarchy that organizes the product into phases or goal areas that correspond to user's goals. It is displayed in addition to the Standard toolbar in Microsoft Project.
- The default Project Guide contains four goal areas that are displayed on the Project Guide toolbar: Tasks, Resources, Track, and Report. These goal areas represent the major project management phases of planning tasks, managing resources, tracking the project once it is underway, and reporting and analyzing project data. These goal areas were selected after extensive research and usability testing to discover how users group and categorize typical project management activities. However, it is possible to customize the default Project Guide and change these goal areas.
- **Side pane **Displays tasks within each goal area.
- A side pane is used for navigation within a particular goal area. When a user clicks a goal area in the Project Guide toolbar, the side pane displays a list of tasks for that goal area. For example, when a user clicks Tasks on the default Project Guide toolbar, the side pane displays a list of activities that should be completed as part of planning the tasks in a project, such as listing the tasks, organizing them into phases, and scheduling them.
- After the user selects a particular task, the side pane displays the content for that task. It may contain the controls for accomplishing the task, as well as links to related tasks, domain information, Help, feedback, and status text.
- **View or main area **The area to the right of the side pane is the main viewing and editing area.
- This space displays views of project data. It can also be used to show Web pages from Microsoft Project Server. The view or page displayed changes depending on the activity the user is following in the Project Guide. For example, if the user is entering tasks, the Gantt Chart is displayed on the right, but when the user is on the Enter Resource Information step of the Project Guide, the view on the right changes to show the Resource Sheet.
Figure 1 shows the three main components of the Project Guide.
.gif "Aa164326.projgde01(en-us,office.10).gif")
Figure 1. Project Guide components
Project Guide Architecture
Within the Microsoft Project application window, there is a document window for each active project. An instance of the Web browser control is hosted within each document window. Within the Web browser control, a Hypertext Markup Language (HTML) page is loaded that defines the layout and functionality of the user interface.
Note The Web browser control provides browsing, HTML rendering, document viewing, and data downloading capabilities.
The default HTML page displayed for Microsoft Project is Mainpage.htm, which has an associated script file, Mainpage.js.
The default Mainpage.htm consists of a frameset containing two frames:
- The left frame is the Project Guide side pane that displays the tasks within each goal area, and the Project Guide content for each task (each task in the Project Guide has a separate HTML page associated with it that contains the content that should be displayed in the side pane for that task).
- The right frame is used to display Microsoft Project views or Microsoft Project Web Access pages from Microsoft Project Server.
There is a control to display Microsoft Project views in the right frame that supports all the viewing and editing capabilities of the traditional Microsoft Project interface. This control is implemented by creating an Active Template Library (ATL) wrapper around what used to be the document window in Microsoft Project 2000. This control can display different views, such as the Gantt Chart, Network Diagram, Resource Sheet, and the user can look at and edit information in these views.
Note The control is not a true ActiveX® control in that it cannot be hosted on any Web page and used in a browser. It only works when it is hosted on a page that is viewed within the Microsoft Project window.
.gif "Aa164326.projgde02(en-us,office.10).gif")
Figure 2. Displaying Microsoft Project views in the right frame
For Project Guide tasks that require the user to work in a Microsoft Project view on the right, the page Right.htm is displayed in the right frame. Right.htm contains only the following lines of code, used to display the Microsoft Project view control:
<object id="IEControl"
ALT="Microsoft Project View"
classid="clsid:DE44AD54-CF55-4C05-840E-C177F51AE233"
style="position:relative; left:0; top:0; width:100%; height:100%">
</object>
Content Displayed in the Project Guide
The information structure and content for the Project Guide are defined by an Extensible Markup Language (XML) document. The default XML document used is Gbui.xml. The XML schema behind this document is fairly simple; the different elements are shown and explained below.
<element name="GBUIStructure">
<complexType>
<element ref="ViewChanges" maxOccurs=1 >
<element ref="PageChanges" maxOccurs=1 >
<element ref="GoalArea" maxOccurs=* >
</complexType>
</element>
An organization that is customizing the Project Guide replaces the default Gbui.xml document with its own XML document and defines its own structure and content for the Project Guide.
ViewChanges Element
The ViewChanges element in the GBUIStructure parent element defines how the Project Guide responds when the user changes views in Microsoft Project. For example, a user is looking at the Project Guide side pane titled List the tasks in the project. This side pane helps the user enter tasks and displays a task view on the right. Then the user switches to the Resource Sheet view on the right, using the View menu in Microsoft Project. The content for the List the tasks in the project side pane is no longer relevant when a resource view is displayed on the right. The side pane content changes dynamically so that it is relevant to whatever view is displayed on the right. This change is controlled using the ViewChanges element. This element has the following definition:
<element name="ViewChanges">
<complexType>
<element ref="ViewChange" maxOccurs="*">
</complexType>
</element>
The ViewChanges element can be made up of multiple ViewChange elements. The definition for a single ViewChange element is as follows:
<element name="ViewChange">
<complexType>
<choice maxOccurs=1 minOccurs=1>
<element name="ViewType">
<simpleType>
<restriction enumeration="-1 0 1" />
</simpleType>
</element>
<element name="ViewScreen">
<simpleType>
<restriction enumeration="1 2 3 4 5 6 7 8 9 10 11 12 13
14 15>" />
</simpleType>
</element>
<element name="ViewName" type="string" />
</choice>
<choice maxOccurs=1 minOccurs=1>
<element name="GoalAreaID" type="decimal" />
<element name="TaskID" type="decimal" />
</choice>
</complexType>
</element>
Each ViewChange element contains a pairing of one of {ViewType, ViewScreen, ViewName} to one of {GoalAreaID, TaskID}. This combination is used to specify which goal area or which Project Guide side pane is displayed when the user switches views.
ViewType is used to broadly categorize views into task or resource views. The permitted values for ViewType are 0 for task views, 1 for resource views, and -1 for neither task nor resource views (this value applies when Microsoft Project Web Access or other Web pages are displayed within Microsoft Project).
ViewScreen is a narrower categorization used to describe the nature of a view—for example, whether it is based on the Gantt Chart, the Network Diagram, or the Resource Sheet views. The permitted values for ViewScreen are 1 through 15, corresponding to the different values defined for the pjViewScreen enumeration defined in the Microsoft Project object model.
Table 1. Permitted pjViewScreen enumeration values
| Value | Enumeration |
| 1 | pjGantt |
| 2 | pjNetworkDiagram |
| 3 | pjRelationshipDiagram |
| 4 | pjTaskForm |
| 5 | pjTaskSheet |
| 6 | pjResourceForm |
| 7 | pjResourceSheet |
| 8 | pjResourceGraph |
| 10 | pjTaskDetailsForm |
| 11 | pjTaskNameForm |
| 12 | pjResourceNameForm |
| 13 | pjCalendar |
| 14 | pjTaskUsage |
| 15 | pjResourceUsage |
ViewName is used to identify a single specific view by its name. The values for ViewName can be any text string corresponding to the name of a view in Microsoft Project. ViewName can be set to the name of a custom view or to the name of one of the default views that are included in Microsoft Project.
GoalAreaID and TaskID define goal areas and tasks in the Project Guide. These are explained in more detail in the section titled "GoalArea" later in this paper.
The ViewChanges element defined in the default XML document, Gbui.xml, is:
<ViewChanges>
<ViewChange>
<ViewType> 0 </ViewType>
<GoalAreaID> 1 </GoalAreaID>
</ViewChange>
<ViewChange>
<ViewType> 1 </ViewType>
<GoalAreaID> 2 </GoalAreaID>
</ViewChange>
</ViewChanges>
This element specifies that whenever the user switches to a view that is no longer relevant to the current side pane, the following occurs:
- If the new view that the user has switched to is a task view (ViewType=0), then the list of tasks for the Tasks goal area (GoalAreaID=1) is displayed.
- If the new view that the user has switched to is a resource view (ViewType=1), then the list of tasks for the Resources goal area (GoalAreaID=2) is displayed.
The concept of a relevant view for a Project Guide side pane is explained in detail in the section titled "GoalArea" later in this paper.
The default Project Guide behavior is to perform fairly simple goal area changes, based on the view type. However, the ViewChanges element does support more granular switching to a goal area or even to a specific side pane based on ViewScreen or ViewName. An organization that is customizing the Project Guide can support more advanced switching by using a custom XML document and changing the ViewChanges element in this document.
PageChanges
The PageChanges element defines how the Project Guide should respond when the user displays Microsoft Project Web Access pages from Microsoft Project Server inside Microsoft Project. Microsoft Project 2002 includes a new Collaborate menu that the user can use to display Microsoft Project Web Access pages inside Microsoft Project. The following pages can be displayed by choosing the appropriate item from the Collaborate menu:
- Update Project Progress page, showing Updates for the active project
- Project Center page
- Resource Center page (only available in Microsoft Project Professional)
- Portfolio Analyzer page (only available in Microsoft Project Professional)
- Portfolio Modeler page (only available in Microsoft Project Professional)
- Documents page, showing documents for the active project
- Issues page, showing issues for the active project
Some side panes in the Project Guide instruct the user on how to work with some of these pages. When the user chooses these items directly from the Collaborate menu, the content displayed in the side pane changes to match the pages displayed on the right. This change is defined by the PageChanges element.
The PageChanges element has the following definition:
<element name="PageChanges">
<complexType>
<element ref="PageChange" maxOccurs="*">
</complexType>
</element>
Similar to ViewChanges, the PageChanges element can be made up of multiple PageChange elements. The definition for the PageChange element is as follows:
<element name="PageChange">
<complexType>
<element name="ProjectServerPageID">
<simpleType>
<restriction enumeration="1 2 3 4 5 6 7" />
</simpleType>
</element>
<choice maxOccurs=1 minOccurs=1>
<element name="GoalAreaID" type="decimal" />
<element name="TaskID" type="decimal" />
</choice>
</complexType>
</element>
Each PageChange element is made up of a ProjectServerPageID paired with either a GoalAreaID or a TaskID.
Table 2. ProjectServerPageIDs definitions
| ProjectServerPageID | Page |
| 1 | Updates page, showing updates for the active project |
| 2 | Document Library page for the active project |
| 3 | Issues page for the active project |
| 4 | Project Center page |
| 5 | Resource Center page |
| 6 | Portfolio Analyzer |
| 7 | Portfolio Modeler |
When the user chooses an item on the Collaborate menu that displays a Microsoft Project Web Access page in Microsoft Project, the PageChanges element determines which side pane content should be displayed in the Project Guide. The PageChanges element defined in the default Gbui.xml document is as follows:
<PageChanges>
<PageChange>
<ProjectServerPageID> 1 </ProjectServerPageID>
<TaskID> 19 </TaskID>
</PageChange>
<PageChange>
<ProjectServerPageID> 2 </ProjectServerPageID>
<TaskID>9</TaskID>
</PageChange>
<PageChange>
<ProjectServerPageID>3</ProjectServerPageID>
<TaskID>22</TaskID>
</PageChange>
<PageChange>
<ProjectServerPageID>4</ProjectServerPageID>
<TaskID>28</TaskID>
</PageChange>
<PageChange>
<ProjectServerPageID>5</ProjectServerPageID>
<GoalAreaID>2</GoalAreaID>
</PageChange>
<PageChange>
<ProjectServerPageID>6</ProjectServerPageID>
<GoalAreaID>4</GoalAreaID>
</PageChange>
<PageChange>
<ProjectServerPageID>7</ProjectServerPageID>
<GoalAreaID>4</GoalAreaID>
</PageChange>
</PageChanges>
Task IDs 19, 9, 22, and 28 correspond to Project Guide side panes for Incorporate progress information into the project, Add documents, Track issues, and View multiple projects in Project Center, respectively. There are no Project Guide side panes for the Collaborate menu items Resource Center, Portfolio Analyzer, and Portfolio Modeler, so the user is taken to a relevant goal area instead, such as the Resources goal area (GoalAreaID=2) for Resource Center and the Report goal area (GoalAreaID=4) for Portfolio Analyzer and Portfolio Modeler.
GoalArea
Multiple GoalArea elements can be included in the GBUIStructure parent element. Each GoalArea element defines the Project Guide side panes displayed for the tasks or activities in that goal area. Together the GoalArea elements define the content and structure of the Project Guide.
The definition of a single GoalArea element is as follows:
<element name="GoalArea">
<complexType>
<element name="GoalAreaID" type="decimal" />
<element name="GoalAreaName" type="string" />
<element name="GoalAreaDescription" type="string" minOccurs=0 />
<element name="URL" type="string" />
<element ref="RelevantViews" minOccurs=0 />
<element ref="GoalAreaTask" maxOccurs=* />
</complexType>
</element>
Each GoalArea element is made up of the following:
GoalAreaID
Each goal area must have a unique ID.
GoalArea Name
This name represents the goal area on the Project Guide toolbar.
GoalArea Description
This introductory text is displayed at the beginning of a goal area side pane. It conveys the main purpose of the goal area and the activities within it. This text is optional.
URL
Each goal area has an HTML page associated with it. This page is displayed when the user clicks on that goal area in the Project Guide toolbar. The pages used for the default goal areas only include a script function that dynamically lists all the tasks within the goal area on the page. To customize the look of the Project Guide and associate—for example, a stylesheet or background image with the different goal areas, you can customize the pages for each goal area.
The URL element in the GoalArea definition points to the HTML page for the goal area. A custom protocol, gbui://, references the HTML pages for the Project Guide. See the section titled "Custom gbui:// Protocol" later in this paper for more information.
RelevantViews
The RelevantViews element is used to define the views that are relevant to a particular goal area. For example, when the user is in the Task goal area, resource views are not relevant. Therefore, RelevantViews defined for the Tasks goal area only include views of type task. Then, when the user switches to a view that is not relevant, the ViewChanges element, described earlier, dictates which goal area or side pane to switch to. In this way, content in the side pane always stays relevant to the view on the right.
Note For the Resources goal area, both task and resource views are considered relevant because some tasks in Resources, such as assigning resources, require a task view, whereas others require a resource view. Similarly, for the Track and Report goal areas, both task and resource views are considered relevant.
The definition of the RelevantViews element is as follows:
<element name="RelevantViews"> <complexType> <element name="ViewType" minOccurs=0 maxOccurs=*> <simpleType> <restriction enumeration="-1 0 1" /> </simpleType> </element> <element name="ViewScreen" minOccurs=0 maxOccurs=*> <simpleType> <restriction enumeration="1 2 3 4 5 6 7 8 9 10 11 12 13 14 15>" /> </simpleType> </element> <element name="ViewName" type="string" minOccurs=0 maxOccurs=*/> </complexType> </element>A RelevantViews element can contain any number of ViewType, ViewScreen, or ViewName elements.
For the Tasks goal area, all task views are relevant, so the RelevantViews element for this goal area is defined as:
<RelevantViews> <ViewType>0</ViewType> </RelevantViews>While goal areas tend to have a broad category of relevant views, such as all task views, individual activities within a goal area may have more specific view requirements. Therefore, RelevantViews for a Project Guide side pane may be restricted to a particular set of ViewScreens, or even a specific ViewName. RelevantViews for Project Guide side panes are defined within the GoalAreaTask element, described in more detail below.
You can have multiple ViewType, ViewScreen, or ViewName sub-elements in a RelevantViews element. These will be combined using the OR operator when deciding whether a particular view is relevant to a goal area or a Project Guide side pane. For instance, if RelevantViews for a goal area or Project Guide side pane is defined as:
<RelevantViews> <ViewType>1</ViewType> <ViewScreen>14</ViewScreen> </RelevantViews>Then any resource view or a view of screen type Task Usage will be considered relevant.
Note The RelevantViews element is optional, so if it is not defined at all for a goal area or Project Guide side pane, no views are considered relevant. In this case, as soon as the user switches to a different view, the content in the side pane changes, as specified in the ViewChanges element.
GoalAreaTask
The GoalAreaTask element corresponds to an individual Project Guide side pane. Each GoalArea element usually contains several GoalAreaTask elements, corresponding to all the tasks within that goal area. The definition of the GoalAreaTask element is:
<element name="GoalAreaTask"> <complexType> <element name="TaskID" type="decimal" /> <element name="Title" type="string" /> <element name="TaskName" type="string" /> <element name="URL" type="string" /> <element ref="TaskHelp" minOccurs=0 /> <element ref="RelatedTask" minOccurs=0 maxOccurs=* /> <element ref="RelatedActivity" minOccurs=0 maxOccurs=* /> <element ref="RelevantViews" minOccurs=0 /> </complexType> </element>TaskID
Each GoalAreaTask must have a unique ID (TaskIDs should be unique across goal areas).
Title
The Title string is displayed in the Header area at the top of each Project Guide side pane. It is typically a shorter string than the TaskName, to avoid titles that wrap.
TaskName
The TaskName string is used to represent the task in its parent goal area side pane. These strings are typically longer since they may wrap. For example, the side pane for listing the tasks in a project, uses the Title 'List tasks' and uses a longer TaskNameList the tasks in the project.
URL
Just as for goal areas, the URL for GoalAreaTasks points to an HTML page. Each GoalAreaTask has an HTML page that contains the content to be displayed in the side pane for that task.
TaskHelp
The TaskHelp element defines additional Help content for a GoalAreaTask. Many of the Project Guide side panes offer detailed assistance that can be accessed by clicking a Help link at the bottom of the side pane. The TaskHelp element is defined as follows:
<element name="TaskHelp"> <element name="HelpName" type="string" /> <element name="URL" type="string" /> </element>HelpName defines the display name for the Help link, and URL points to the HTML page containing the Help content. For example, TaskHelp for the Project Guide side pane List the tasks in the project is defined as follows:
<TaskHelp> <HelpName> More Information </HelpName> <URL> gbui://create_tasks_list_hlp.htm </URL> </TaskHelp>The TaskHelp element is optional, so if it is not defined for a GoalAreaTask, a Help link is not displayed at the bottom of that task.
RelatedTask
The RelatedTask element is used to reference other GoalAreaTasks that may be related to or pertinent to a specific GoalAreaTask. For example, when listing the tasks in a project, you may also be interested in adding additional information such as notes or hyperlinks to tasks. Therefore, you would define the task Link to or attach more task information as a RelatedTask to List the tasks in the project. A RelatedTask must be a defined GoalAreaTask in the Project Guide. RelatedTasks are displayed in the Next Steps and Related Activities menu.
The definition for the RelatedTasks element is as follows:
<element name="RelatedTask"> <element ref="TaskID"/> </element>TaskID must correspond to the TaskID of another GoalAreaTask in the XML document.
For example, RelatedTasks for List the tasks in the project is defined as:
<RelatedTask> <TaskID> 6 </TaskID> </RelatedTask>RelatedTasks are optional, so if no related tasks are defined for a GoalAreaTask, nothing is shown in the Next Steps and Related Activities menu when that task is selected. A single GoalAreaTask can also contain multiple RelatedTask elements, in which case each element will be displayed separately on the Next Steps and Related Activities menu.
RelatedActivity
The RelatedActivity element is used to reference related or pertinent activities that are not defined GoalAreaTasks in the Project Guide, but correspond to Microsoft Visual Basic® for Applications (VBA) methods in the Microsoft Project object model. For example, creating a recurring task is relevant when you are listing the tasks in your project. There is no GoalAreaTask in the default Project Guide that corresponds to creating a recurring task, but there is a VBA method, RecurringTaskInsert, that brings up a dialog box where you can enter recurring tasks. This is defined as a RelatedActivity for the GoalAreaTaskList the tasks in the project.
The definition for the RelatedActivity element is as follows:
<element name="RelatedActivity"> <element name="ActivityName" type=string /> <element name="VBAMethod" type=string /> </element>ActivityName represents the activity in the Next Steps and Related Activities menu. VBAMethod is the name of the Microsoft Project object model method that should be executed for that activity.
A RelatedActivity for the GoalAreaTask in the project is defined as:
<RelatedActivity> <ActivityName> Create a Recurring Task </ActivityName > <VBAMethod> RecurringTaskInsert </VBAMethod> </RelatedTask>Like RelatedTasks, RelatedActivities are optional. A single GoalAreaTask can also contain multiple RelatedActivity elements.
Security
The Project Guide includes the security provisions described in the following sections.
Trusted Sites Restriction
Project Guide pages can access the Microsoft Project object model with the window.external object (window.external gives access to the object model of the application hosting Microsoft Internet Explorer Browser components). In this case, it applies to Microsoft Project. For more information, see the external object reference in the HTML and Dynamic HTML SDK on MSDN.
Access to window.external enables a page to read, write, or manipulate data on the user's hard drive. For this reason, it's important to restrict which Project Guide pages are considered safe.
Pages are displayed only from sites that the user has explicitly identified as trusted in Microsoft Internet Explorer (this applies to scenarios where the Project Guide is ON as well as OFF).
For pages located on an intranet file share, such as file:\\servername\sharename, the user still has to specify this file share as a trusted site in Microsoft Internet Explorer. Pages located on the local hard drive are always considered trusted.
Cross-frame Scripting
A typical customization scenario to follow for the Project Guide is to have a custom XML document for ProjectGuideContent and custom .htm and .js files for GoalAreas and GoalAreaTasks that live on a central network share or intranet server. However, in many cases, organizations may choose to use the default functional and layout page that is shipped with Microsoft Project, Mainpage.htm, with their custom content.
Most GoalArea and GoalAreaTask pages have many references to functions that reside on Mainpage.htm and Mainpage.js. If custom pages for custom GoalAreas and GoalAreaTasks are written efficiently and cost-effectively, they will also refer to functions on Mainpage.htm and Mainpage.js. However, if the custom pages are located on a network share or intranet server, they will be in a different security zone than Mainpage.htm and Mainpage.js, which are located on the user's local computer. Microsoft Internet Explorer does not allow a page that is located in one zone attempt to call script on a page that is located in a different zone because of cross-frame scripting security checks (see the Microsoft Knowledge Base article, PRB: Permission Denied Error Message When Scripting Across Frames (Q167796) for more information on cross-frame scripting).
In Microsoft Project, only pages from trusted sites are displayed. Therefore, a page from one trusted site may access script on a page from another trusted site, or may access script on a page that is located on the user's local computer. This access is enabled so that organizations writing custom Project Guides can use functions on the default functional and layout page with their custom content.
Microsoft Internet Explorer does not allow access to script in a different security zone directly through the parent object. To resolve this issue, there is a WebBrowserControlWindow property on the Microsoft Project Window object. This property returns the DOM object of the Microsoft Internet Explorer window within the Web browser control for a particular Microsoft Project window. If you are using the default functional and layout page for a project's Project Guide, this property should return a pointer to Mainpage.htm. Instead of using the Microsoft Internet Explorer parent object to access scripts on Mainpage.htm, content pages can use the window.external.WebBrowserControlWindow object.
For example, the default GoalArea pages call a function displayGoalAreaHeader from Mainpage.js. To call this function, the parent object is not directly used as:
parent.displayGoalAreaHeader()
Instead, the following syntax is used:
pDisplayGoalAreaHeader()
The function pDisplayGoalAreaHeader() is defined in the script file Util.js, which is included in all of the default GoalArea and GoalAreaTask pages. This function has the following code:
function pDisplayGoalAreaHeader()
{
pscript().displayGoalAreaHeader();
}
The function pscript() is also defined in the script file Util.js and contains the following code:
function pscript()
{
var parentHTMLDoc = window.external.WebBrowserControlWindow();
return parentHTMLDoc.Script;
}
The function uses the WebBrowserControlWindow property to return a pointer to the parent Internet Explorer window.
If you are writing custom Project Guide pages that need to access functions on the default functional and layout page, then you should use this same syntax to access these functions.
Custom gbui:// Protocol
All of the default Project Guide files, the .htm and .js files for the various GoalAreas and GoalAreaTasks, our default functional and layout page, Mainpage.htm, and our default content file, Gbui.xml, are compiled into the Pj10intl.dll. This is the international .dll file containing localized resources, and it is located in a different <LCID> (locale ID) subfolder for each language version. For example, for U.S. English, Pj10intl.dll is installed in a <1033> folder that's created as a subfolder in the folder the user chooses to install Microsoft Project in. The GBUI files can be accessed using the protocol:
res://<LCID>/pj10intl.dll/filename
Note The res protocol can be used to access files compiled into a .dll.
However, to use this protocol as shown above, the URL references in all the Project Guide files have to be modified for different international versions of Microsoft Project, and the LCID changed to the appropriate LCID for each language. To avoid having to change the LCID, the concept of pluggable protocols provided by Microsoft Internet Explorer is used (more information on pluggable protocols can be found in the Cutting Edge: Pluggable Protocols article. Microsoft Project has its own URL protocol defined, by implementing the Asynchronous Pluggable Protocols API and writing its own protocol handler.
The custom protocol scheme is called gbui. When the Web browser control hosted within Microsoft Project encounters URLs that use the protocol gbui (such as gbui://mainpage.htm), it tries to resolve these by calling the custom protocol handler. The protocol handler translates the gbui URL into a res:// URL that references the Pj10intl.dll in the appropriate LCID folder.
This provides the following benefits:
- The URLs in the default Project Guide files don't need to be modified for the different international versions of Microsoft Project.
- Organizations can easily reference our default Project Guide files in any custom Project Guides that they create by referring to these files using the gbui:// protocol (they won't have to worry about where exactly the files have been installed).
If you are creating a custom Project Guide, but you want to include some GoalAreaTasks from the default Project Guide, you can easily reference these files in your custom XML document by using the gbui:// protocol.
Conclusion
The Project Guide in Microsoft Project 2002 is a new tool designed to encourage new and legacy users to discover new features and to assist novice users to quickly and easily initiate and organize projects.
For more versatility, the Project Guide is fully customizable, so that an organization can change the content and behavior of the Project Guide to conform to their own project management framework.
Additional Resources
- Cutting Edge: Pluggable Protocols article
- PRB: Permission Denied Error Message When Scripting Across Frames (Q167796)
- External object reference
Preethi Ramani is a program manager in the Microsoft Project Business Unit. Preethi has worked on the design and architecture of the Project Guide for Microsoft Project 2002, and has been with Microsoft for five years.
Marcel Parent is a program manager in the Microsoft Project Business Unit, and has been with Microsoft for two years. One of Marcel's areas of specialization is Project Guide customization.
Laurie Hughes is a technical writer on the Business Tools Division Web Content Services team. She recently moved from the Microsoft Project User Assistance team, where she honed her skills writing for a variety of audiences and technologies.