Session ADF306

Putting the Task Pane Manager to Work

Tamar E. Granor
Tomorrow’s Solutions, LLC
tamar@tomorrowssolutionsllc.com
www.tomorrowssolutionsllc.com

The Task Pane Manager is a portal for VFP. Added in VFP 8, the tool itself is simply a container—it contains task panes. What's a task pane? Anything you want it to be. The tool comes with a number panes (seven, in VFP 8 and 8, in VFP 9) that span a wide variety of activities, but it's possible to add panes, either ones you write yourself or ones provided by others. In this session, we'll look at what you can do with the provided task panes, and then consider creating and installing custom panes.

Running the Task Pane Manager

You start the Task Pane Manager by choosing it from the Tools menu or from the Standard toolbar. The first time you open it, it opens to the Start pane (Figure 1). The button bar just below the title bar contains a list of available panes. If the list doesn't fit, the chevron button indicates that more panes are available; click it to see the list.

Figure 1: The Start Pane—This pane gives you quick access to both information and tools, as well as to the projects and databases you've worked with most recently.

You can also set the Task Pane Manager to open when VFP starts. To do so, click the Options button or, in VFP 8, click on Task Pane Manager startup options at the very bottom of the Start pane. Either choice opens the Options window (interestingly, not a dialog) shown in Figure 2. If necessary, click on Task Pane Manager in the list to see options that affect the tool as a whole. To have the Task Pane Manager open when you start VFP, check the appropriate checkbox. (Because the tool is written in VFP, CLEAR ALL does shut it down.)

Figure 2: Setting Task Pane Options—This window lets you specify options for the tool as a whole and for individual panes.

The dropdown at the top on this page lets you specify which pane is displayed when the tool opens. By default, it returns to the pane that was displayed when you closed it, but you can choose a specific pane if you prefer.

A number of the panes get some of their data from the web. The Check for New Internet Content section determines how often the tool looks for updated data. The setting on this page is a default. The Options page for each pane that has Internet data includes a similar section; there, you can override the default for that particular pane.

???Add proxy server settings???

The Start Pane

The Start Pane collects a variety of information and tools into a single location. It's not hard to imagine using this pane as the center of VFP development.

The pane is divided into four sections: Start, My Tools, Recent Projects, and Recent Databases. Each can be controlled individually from the Options window, so you can include as many or as few of them as you wish. (See Figure 3.)

Figure 3: Controlling pane contents—When a pane has multiple sections, the Options window lets you decide which sections are displayed.

At first glance, the Start section may look like it simply points to documentation. In fact, several of the links actually run tools. What's New in Visual FoxPro and its sub-items are, in fact, links to the VFP help file, and Go to the Visual FoxPro website does what its name suggests. But Create a new application and Create a new database run the Application Wizard and Database Wizard, respectively. Customize my development environment switches to the Environment Manager page, discussed later in this document.

The most intriguing section here is My Tools. When you click Manage, the My Tools dialog (Figure 4) opens. You can add a variety of items here, from VFP applications to forms to custom scripts.

Figure 4: Adding tools to the Start pane—The My Tools dialog lets you call existing applications, programs, forms and reports, or write scripts in VFP.

In Figure 4, the GenDBC utility is added to the My Tools list. You might also add a script that cleans up after running an application. The script code might look like:

SET SYSMENU TO DEFAULT

MODIFY WINDOW Screen

_Screen.Caption = VERSION()

Of course, a script could also prompt for input, so it doesn't have to do exactly the same thing every time you run it.

Once you've added at least one item to the list of tools, the My Tools section expands to include a dropdown of tools and a Run button, as shown in Figure 5. Choose a tool and click run to execute the specified tool.

Figure 5: Working with tools--Once some tools are registered, the My Tools section expands to let you use them.

The Recent Projects and Recent Databases section draw their entries from the MRU (most recently used) lists maintained by VFP. The number of items in each section is based on the setting for MRU list size in the Tools>Options dialog. Clicking on a project or database in the list opens it, along with the appropriate tool (the Project Manager or Database Designer). Each section has buttons beneath it that let you open an item not on the list or create a new one.

The Community Pane

Community is a hot button with Microsoft these days. They're putting a lot of effort into building developer communities (something FoxPro has had for a long time). So it's not surprising that the second of the panes supplied by Microsoft focuses on community.

This pane (Figure 6) is divided into two sections, but they don't directly map to the checkboxes on the Options window page for the pane. The top section (Community) is a list of community web sites. Most of them are places where you can ask questions and get answers from your peers. A few have different structures or purposes, but all of them offer opportunities to improve your VFP skills.

Figure 6: Joining the community—The Community pane provides quick access to VFP support sites and a listing of VFP news.

The bottom section (News) is a list of items drawn from one or more of the FoxCentral, Universal Thread and FoxPro Wiki websites. The Options window lets you specify which of them to use, as well as additional parameters for each of the three.

The Environment Manager pane

For those who work on more than one project at the same time, making sure you have the right settings in place when you work on a given project is a perennial problem. The Environment Manager pane (Figure 7) is designed to solve that problem. Click on the Manage Environments link to open the Environment Manager (Figure 8). In that dialog, you can create and edit what Microsoft calls environment sets.

Each environment set is listed in the Environment Manager pane. When you click on the name of the set (such as "Science Fair project" in Figure 7), those settings are applied. When you click on a project listed under a set, the settings are applied and the specified project is opened. Click on the design icon at the right to open the Environment Manager with this set selected for editing.

Figure 7: Managing settings—The Environment Manager pane lets you name a group of settings and, optionally, associate it with one or more projects.

Figure 8: The Environment Manager—This tool lets you create environment sets, which are named groups of settings, including path, default directory, and many SET commands.

To create an environment set, click New in the Environment Manager. Fill in the name, then specify the desired settings. The Default Directory / Path page shown in Figure 8 includes only the default directory and path, which default to the current settings. The Environment Settings page (Figure 9) lets you specify values for the most common SET commands, indicate the resource file (by default, FoxUser.DBF) to use, and specify scripts to run before and after applying the other settings. In each case, the script can be any VFP code, allowing you to handle items not directly included in the Environment Manager. (For example, you might open the Toolbox and point it to a specific data file.) The ellipsis button next to each script opens a larger editing window to make it easier to enter your script code.

Figure 9: Specifying settings—This page of the Environment Manager includes a number of SET commands, plus the resource file and scripts to run before and after applying the other settings.

VFP 5 introduced the idea of field mapping, specifying the class and class library to use for each data type when you drag and drop in the Form Designer. Ever since, making sure you’re using the right mappings for a given project has been a problem. In VFP 9, the Environment Manager has been enhanced to handle the problem for you. Use the Field Mapping page (Figure 10) to specify mappings for this environment set.

Figure 10. Choosing classes—The Field Mapping page lets you indicate what class to use for each data type.

The Forms page (Figure 11), also new in VFP 9, handles the same problem at the form level. You can specify a class to use each time you create a new form.

Figure 11. Specifying a form class—The Forms page of the Environment Manager lets you indicate what class to use for new forms with this environment set.

Use the Associated Projects page to list the projects for which this environment set applies. All the projects associated with a specified environment set are listed beneath it in the Environment Manager pane.

The Solution Samples pane

Since VFP 5, Microsoft has included a fairly comprehensive set of granular examples, each designed to show a single feature. The hard part has been getting people to pay attention to these Solution Samples. So, starting in VFP 8, they get a task pane of their own. This pane (shown in Figure 12) includes searching, the ability to install new samples as they become available, and a section to show links to websites that offer additional samples.

Figure 12: Lots of examples—The Solution Samples pane offers quick access to well over 100 examples that demonstrate VFP features.

From the pane, you can both run the individual examples and display the underlying code. The samples include more than a dozen that demonstrate new features of VFP 8. As of this writing, samples for VFP 9 had not yet been added, but no doubt there will be a selection of them when the product ships.

One secret for this pane: When you search, the results are listed beneath the search criteria. To remove the listing, clear out the textbox and click Search.

From time to time, new samples may become available (most likely from Microsoft's VFP website). They'll be supplied as a file called Manifest.XML. To add them to the pane, click the Install Sample button and point to the file. (Sadly, as of this writing, no websites are offering additional samples for VFP 8 in the specified format. When Microsoft did make additional VFP 8 samples available, they didn’t package them for this pane.)

The XML Web Services Pane

Web Services are a key technology direction for Microsoft, and VFP is well-equipped to go in this direction, with the ability to both create and consume (use) web services. The XML Web Services pane (Figure 13) provides access to a variety of tools and resources to help you in building and using web services.

Figure 13: Working with web services—This pane is a one-stop shop for web services tools and resources.

This pane has three sections. The XML Web Service Tools section has links to three key tools for working with web services. The first is the XML Web Services Registration dialog that lets you register a web service. Doing so provides IntelliSense for it and adds it to the Toolbox. Second is the XML Web Services Publisher, which lets you make web services you create available to others. The third is the XML Web Service Manager (shown in Figure 14), a new tool that lists registered web services and lets you add and delete them, as well as determine whether they're listed in the Toolbox. Each of these tools is quite capable, but they’re beyond the scope of this session.

Figure 14: XML Web Services Manager—This new tool offers quick access to all registered web services.

The second section of the XML Web Services pane provides help in using the web services you've registered. When you choose a web service from the dropdown (which appears only once you’ve registered at least one web service), the section expands (Figure 15) to include a dropdown of that web service's methods and sample code for using the web service.

Figure 15: Exploring a web service—When you choose a web service from the dropdown, the Explore an XML Web Service section expands. Click the icon next to the methods dropdown to test that method.

The icon next to the dropdown listing the methods lets you test the chosen method. When you click it, a dialog opens (Figure 16) for you to specify the parameters to pass to the method. Once you do so, another window opens showing the results from the method call. You can see the results either as XML or in a grid.

Figure 16: Testing a web service method—When you test a method, this dialog allows you to specify the parameter values to pass. Click OK to pass the specified values and execute the method.

The final section of the XML Web Services pane provides links to a variety of resources for building and using web services. They include relevant sections of the VFP Help file, documentation for the SOAP toolkit, some MSDN articles, and more.

The Filer pane

The Filer tool dates back to FoxPro 2.0, where it was introduced to provide an easy way to find files meeting various criteria. The functionality hasn't changed much over the years, but the form and face of the tool have. VFP 8 added another twist by housing Filer in a task pane (Figure 17). While the task pane version looks different than the stand-alone version (which is still available), the functionality is the same.

Figure 17: Searching for files—The Filer tool can be accessed through the Task Pane Manager to search for files meeting specified criteria.

The Data Explorer pane

With more and more VFP applications accessing data from other sources, the Data Explorer pane was added in VFP 9 (it’s the only new built-in pane in VFP 9). This tool (Figure 18) lets you collect information about all the databases on your network. For each database listed, you can see the tables, views and stored procedures, and even run queries created on the fly.

Figure 18: Examining data—The Data Explorer lets you drill into the databases available on your network.

To add an item (a database, a VFP table, or all the VFP databases in a directory), click the Add Connection button or right-click on the Connections node and choose Add Connection. The Add Connection dialog (Figure 19) appears. Choose the appropriate type. If you specify any FoxPro object, you’re then prompted to point to the object (directory, database or table) using a standard dialog.

Figure 19. Adding databases—This dialog appears when you click the Add Connection button. Specify the type of database you want to add.

If you specify SQL Server or SQL Database in the Add Connection dialog, the SQL Connection Properties dialog appears. (For SQL Server, the Database textbox is omitted.) Use the dialog to specify the SQL Server and, if appropriate, database to add, along with the login and connection information.

Figure 20. Adding a SQL database—When you choose to add a SQL Server or SQL Database to the Data Explorer, the SQL Connection Properties dialog opens.

If you specify ADO Connection, the ADO Connection properties dialog (Figure 21) opens, allowing you to point to an existing connection, using the DSN, or to specify a connection string.

Figure 21: Adding an ADO connection—You can specify either an existing data source or provide a connection string.

Once a database has been added, you can expand it to see Tables, Views and Stored Procedures sections, as in Figure 18. Each section has a number of options, accessible through its context menu. Most are self-explanatory, but a few are worth discussing.

Choose the Properties item for a FoxPro database, table or folder to open the VFP Connection Properties dialog. This dialog (shown in Figure 22) includes two check boxes: checking Show column info displays the type and size for the fields in each table; checking Sort objects organizes each section alphabetically. The SQL Connection Properties and the ADO Connection Properties dialogs also include the Show column info checkbox. For SQL data, you can also sort alphabetically.

Note that in all cases, these settings apply to the entire item that is below Connections in the treeview, whether it’s a database, table or directory. That is, you can’t turn on column info for one table in a database and not the others, and if you’ve added a whole directory of VFP databases, these settings are all or nothing for the items in that directory.

Figure 22: Customizing database information—The VFP Connection Properties dialog lets you determine whether fields show their type and size, and whether items are sorted alphabetically.

Many items include a Run Query item in their context menu. Choosing that item opens a window (Figure 23) that lets you create and run a query on the fly. Depending on the item selected when Run Query is chosen, the window may include a query to start with. For example, in Figure 23, Run Query was chosen from the shortcut menu of the Customer table. If a field’s shortcut menu is used, the query selects only that field. Choosing Run Query for a stored procedure of a SQL database generates a command to execute that procedure.

Figure 23: Examining data—When you choose Run Query from a context menu, this window appears to let you create a query. It’s initially populated with a query based on the item selected.

You can modify the query (or replace it entirely). When you click the Run button, the query is executed, and a page is added to the window, showing the results (as in Figure 24).

Figure 24: Query results—When you choose the Run button, the query is executed. The ResultCursor pages shows the results of the query.

The SQL Servers section is populated automatically with the list of available servers. Expand that node to see the databases on that server. The items listed offer the same collection of options that SQL servers and databases include in the Connections node.

The context menu for the SQL Servers node includes Properties. When you choose it, you get a cut-down version of the SQL Connection Properties dialog (Figure 20) that allows you to set defaults.

Finally, the Data Explorer has a built-in Options button that opens the dialog shown in Figure 25. The Task Pane’s Options window doesn’t include anything for the Data Explorer. It’s likely that the options are offered separately because the Data Explorer can be run outside the Task Pane Manager (by issuing DO HOME() + “DataExplorer.APP”).

Figure 25. Data Explorer Options—This dialog lets you change the font for the Data Explorer and remove all the items you’ve added.

The Minesweeper pane

The final pane supplied by Microsoft is just for fun. It's a VFP version of Minesweeper. It's missing some of the functionality of the Windows version, but includes the ability to set the size of the grid.

Actually, this pane has one other use. The code uses the Collection class added in VFP 8. You may want to examine the code to see how it works.

Extending the Task Pane Manager

While the panes provided by Microsoft are useful (or fun), the real power of the Task Pane Manager is in the ability to add panes. There are two ways to do so. The simpler, by far, is to install a pane supplied by someone else. The hard way is to create your own.

Installing third-party panes

Before VFP 8 was released, I expected most of the vendors of tools for VFP to create task panes for their products. Each framework and developer tool has its own portal, with some of them modal. The Task Pane Manager provides an opportunity to unify all the tools we use into a single interface. However, to date, this hasn’t been the case.

Nonetheless, you’ll find a few task panes available for download at http://taskpane.leafe.com/.

Installing a pane supplied by someone else is a breeze. Open the Task Pane Manager and click the Options button. In the Options window, open the Task Pane Manager folder. Then choose Customize. On the page that appears (Figure 26), click Install Pane.

Figure 26: Adding and creating panes—This page of the Task Pane Options window lets you install third-party panes and create your own panes.

Task panes are distributed as XML files, so you're prompted to point to the appropriate XML file. Once you do so, it appears in the Task Pane Options window, and focus lands on that pane, so you can set any options it may have. The pane is also added to the Task Pane Manager, of course.

The materials for this session include Mortgage_Calculator.XML, the installation file for a simple pane that computes mortgage payments (Figure 27).

Figure 27: Mortgage Calculator pane—This pane, built with VFP code, computes loan payments.

Creating custom panes

You use the same page of the Task Pane Options window to start the process of creating your own panes, as well as to modify existing panes. In this case, click Customize Panes, which opens the Pane Customization window (Figure 28).

Figure 28: Creating and modifying panes—The Pane Customization window lets you modify existing panes and create new ones.

To create a new page, click the New button on the button bar. The Pane dialog (Figure 29) appears. In this dialog, you specify a "vendor" (your name or your company name), the name for the new pane, and the type of pane you're building.

Figure 29: Creating a new pane—This dialog lets you specify basic information for a new task pane.

By default, the name you specify for Vendor is concatenated with the Unique ID to form the complete identifier for the pane. This combination increases the chances that every pane a user installs has a completely unique identifier. (The default value for Unique ID is generated using SYS(2015), but you can specify a different value if you want.)

The string you specify for Name is the pane's "friendly name." It appears in the Task Pane's button bar, in the title bar when the pane is displayed, and in the Task Pane Options window.

The tool supports four pane types: Web Page, HTML, XML, and VFP Controls. The type of a pane appears in the button bar of the Pane Customization window. (In Figure 28, the Mortgage Calculator pane is a VFP Controls pane.) We'll look at each type.

Web Page panes

The simplest type of pane to create is a Web Page. Web Page panes simply display a specified website in the Task Pane Manager. The only thing you need to specify for a Web Page pane is the URL of the website. You do so on the Data page of the Pane Customization dialog (Figure 30). The appearance of this page changes depending on the type of pane you're creating and on choices you make on the page.

Figure 30: Specifying a Web Page pane—For this type of pane, the only required information is the URL of the website to display.

There's one other item you may want to specify for this type of pane, as well as for other panes—that's the image to associate with the pane. The image appears next to the pane name in the button bar. You specify it on the General page of the Pane Customization window (see Figure 28).

The pane defined in Figure 30 is included in the materials for this session as TSLLC_website.XML.

VFP Controls panes

For VFP developers, panes based on VFP code are clearly the next easiest to create. The Mortgage Calculator in the session materials is a VFP Controls pane—we'll look at its code to see how to build this sort of pane.

For a VFP Controls pane, you specify a class and class library. The class should be subclassed from the PaneContainer class in the FoxPane.VCX class library that's part of the TaskPane project. (Unzip XSource.ZIP in the Tools folder, and then look in the VFPSource\TaskPane folder to find that .VCX.) While you probably can create a pane based on a different class, using PaneContainer ensures that all the necessary methods are present and that default behavior is provided.

When you subclass PaneContainer, add the controls and code necessary for the functionality you want the pane to have. The Mortgage Calculator pane has a few labels and spinners to represent the principal, interest and length of the loan, plus a textbox to contain the payment amount and a button to perform the calculation. There's one custom method, ComputePayment, which does the calculation (using the VFP's Payment() function). The Init method of the pane calls ComputePayment, as does the Click method of the Calculate button.

Defining Options

Panes can have options, items the user specifies that change the behavior of the pane. For example, the Minesweeper pane has an option for the size of the matrix. (To see it, open the Task Pane Options window, and click on Minesweeper.) The Mortgage Calculator pane has an option to indicate whether the interest rate specified is annual or monthly. Figure 31 shows this option in the Task Pane Options window.

Figure 31: Pane option—When creating a custom pane, you can define options that the user can specify when using the pane.

Options are specified on the Options page of the Pane Customization window (Figure 32). To add an option item, click New; the New Option dialog (Figure 33) appears. Specify a name for the option, the type of control it should use (textbox, checkbox, spinner, or password textbox) and a caption for that control.

Figure 32: Pane options—The Options page of the Pane Customization dialog defines options for the pane. The options specified here appear on the Options page for the specified pane.

Figure 33: Adding options—The New Option dialog lets you specify the name of an option and the control used for it.

Once an option has been defined, you can modify the control used to display it by setting properties of the control. The properties grid on the right-hand side of the Options page is initially populated with a few properties you're likely to want to change. You can add other properties to the list by clicking the New Property button above the grid. Then specify the name of the property and it's added to the grid. The Value column of the grid is editable, so you can set the properties.

Using Options

Of course, defining options wouldn't be very useful if there weren't a way to use them in figuring out what appears in a pane. There are actually two ways to access the value of a property; which one you use depends on the situation.

VFP code that you write for a pane (whether in a subclass of PaneContainer or in one of several other places used only for HTML and XML panes) generally receives one or more parameters. The one you need for accessing option values is oContent, a reference to an object based on the Content class defined in FoxPaneContent.PRG. The Content class has a GetOption method—pass it the name of the option and it returns the current value. (Option values are stored between VFP sessions.)

In the Mortgage Calculator pane, the OnRender method (inherited from PaneContainer) uses this code to get and apply the value of the IsAnnual option. Note that all option values are character, so the code must convert to the appropriate type:

LPARAMETERS oPane, oContent

LOCAL cResult

cResult = oContent.GetOption("isannual")

This.lIsAnnual = IIF(cResult = ".T.", .T., .F.)

IF This.lIsAnnual

This.lblInterest.Caption = "Interest rate (annual %)"

ELSE

This.lblInterest.Caption = "Interest rate (monthly %)"

ENDIF

The second way to use an option's value applies when you're using the option in the specification for the pane. For example, you might define a generalized Web Page pane that lets you specify a URL and then displays that page. To do so, you'd add an option called url to the pane. Then, on the Data page, in the URL textbox, specify:

##url##

You can see an example of this approach in the Community pane. Look at the Data page for the Wiki section of the page. The call to the Wiki's web service passes the parameter ##daysold##.

HTML and XML Panes

The last two types of panes, HTML and XML, have a lot in common. Both display their content in an Internet Explorer ActiveX control. The principal difference between the two is that XML panes must include an XSL style sheet to convert the content to HTML.

HTML and XML panes generally have most of their content in sections beneath the main pane. Web Page and VFP Controls panes don't support sections. You can tell whether a pane has sections by looking at the Task Pane Options window. Each section appears as a checkbox on the General options page for the pane, so you can control each separately. For example, the Solution Samples pane contains two sections: Solution Samples and Add-in Links.

As an example, we'll build a pane that displays the weather for a number of different cities. The forecast information will be retrieved using a web service whose definition is found at http://www.ejse.com/WeatherService/Service.ASMX?WSDL. (You need to register this web service before creating or using the pane. See RegisteringWebServices.txt in the session materials for instructions.) The Weather Report pane is included in the session materials for you to install as described earlier in these notes.

Once you've created the pane, you add sections by clicking the Add button in the Pane Content listing of the Pane Customization window. The new section shows up as a leaf node under the pane; you can change its ID and name on the General page, as in Figure 34. In the Weather Report pane, we'll use a section for each city we're interested in.

Figure 34: Adding subsections—The Add button adds a section to the pane you're editing. Each section has its own unique ID. Display of sections can be controlled individually through the Task Pane Options window.

For an XML or HTML pane, the Data page specifies the raw source of the pane. It may be HTML or XML. When a pane has sections, the Data page for the pane itself ("Weather Report" in Figure 34) contains information for the pane as a whole. Include the string "<!-- CONTENT -->" to indicate where the content from the sections should be placed. The data for the sections is concatenated and substituted for the Content comment.

The data for the pane as a whole and for each section can come from a variety of sources, shown in Table 1. The Help topic "Data Tab, Pane Customization Dialog Box" has more information on these choices.

Table 1 Sources for XML and HTML data and transformations—The data for a pane or its sections can be specified in a variety of ways. The same choices apply for specifying transformation of data.

Source Type	Description
Static Text	The content or transformation is specified as XML, HTML (or, for transformations, XSL) in an edit box on the page. A Modify button appears to let you open an editing window.
URL	A URL to the content or transformation is specified in a text box on the page.
Script	The content or transformation is returned from VFP code. The VFP code is specified in an edit box on the page. A Modify button appears to let you open an editing window.
File	The content or transformation is contained in a file, which you specify in a text box on the page.
Web Service	The content or transformation is supplied by calling a web service. You specify the details for the call on the page.

For the Weather Report pane itself, the default data for an XML pane works with just a small addition. Here's the Static Text specified:

<?xml version='1.0' encoding='utf-8' standalone='no'?>

<?xml:stylesheet type="text/xsl" href="weather.xsl"?>

<VFPData>

<!-- CONTENT -->

</VFPData>

The key change is the addition of a stylesheet reference. The specified stylesheet (weather.xsl) is used to convert the XML weather data to HTML for display. We'll take a look at it a little later on.

The sections each need to call the web service's GetWeather method, passing an appropriate zip code. Although many web service methods return an XML string as the result, the GetWeather method has a more complex result, which is returned as an object. This requires additional processing, so using a data source of Web Service isn't possible. Instead, VFP code calls the web service and processes the result. Since each section needs the same code, it's parameterized:

LPARAMETERS oContent, nZipCode

LOCAL loService AS "XML Web Service"

* LOCAL loService AS "MSSOAP.SoapClient30"

* Do not remove or alter following line. It is used to support IntelliSense

* for your XML Web service.

*__VFPWSDef__: loService = http://www.ejse.com/WeatherService/Service.ASMX?WSDL , ;

Service , ServiceSoap

LOCAL loException, lcErrorMsg, loWSHandler, cXML

TRY

loWSHandler = NEWOBJECT("WSHandler", ;

IIF(VERSION(2)=0,"",HOME()+"FFC\")+"_ws3client.vcx")

loService = loWSHandler.SetupClient( ;

"http://www.ejse.com/WeatherService/Service.ASMX?WSDL", "Service", "ServiceSoap")

* Call your XML Web service here. ex: leResult = loService.SomeMethod()

oXML = loService.GetWeatherInfo(nZipCode)

IF oXML.Length>0 AND NOT ISNULL(oXML.Item(0).ParentNode)

cXML = oXML.item(0).ParentNode.xml

ENDIF

* Remove XMLNS info

cRemove = STREXTRACT(cXML,"<GetWeatherInfoResult",'>')

cXML = STRTRAN(cXML,cRemove,"")

* Remove degree symbol

cXML = STRTRAN(cXML,CHR(176)," ")

CATCH TO loException

lcErrorMsg="Error: "+TRANSFORM(loException.Errorno)+" - "+loException.Message

DO CASE

CASE VARTYPE(loService)#"O"

* Handle SOAP error connecting to web service

CASE !EMPTY(loService.FaultCode)

* Handle SOAP error calling method

lcErrorMsg=lcErrorMsg+CHR(13)+loService.Detail

OTHERWISE

* Handle other error

ENDCASE

* Use for debugging purposes

MESSAGEBOX(lcErrorMsg)

FINALLY

ENDTRY

RETURN cXML

If only one section needed this code, we could specify a Data Source type of Script and paste the code into the edit box, substituting the appropriate zip code. Since every section of the pane uses it, it makes more sense to store the code as a PRG and call it from each pane. To add the PRG to the pane, choose the View Files option button in the Pane Customization window, which switches to the view shown in Figure 35. Use the Add button to add the PRG file. In Figure 35, the program has already been added; it's called GetWeather.PRG.

Figure 35: Pane Files—Choosing the View Files option button lets you see the files associated with (and stored with) your pane.

Each section of the Weather Report pane needs to make a call to the GetWeather program. To do this, specify the Data source as Script, and then use code like this (for New York) as the script:

LPARAMETERS oContent

LOCAL cOldPath, cXML

cOldPath = SET("PATH")

SET PATH TO (oContent.CacheDir)

cXML = GetWeather(oContent, 10001)

SET PATH TO &cOldPath

RETURN cXML

Note the oContent parameter. Scripts used on the Data page must be prepared to receive a single parameter, an object reference to the pane's content. In this case, we pass that parameter along to GetWeather, which uses it in case of a problem with the web service. The oContent parameter is also used to set the path, so the GetWeather program can be found.

In addition to any manipulation you perform in the code that creates the XML data, you have another opportunity to process the XML, using the Transform Data page. You can specify no transformation, an XSL transformation, or a VFP script. You have the same choices of source for either XSL or a VFP script as for the data itself, those listed in Table 1.

For the Weather Report pane, the XML returned from the GetWeatherInfo method is fine as it is, so the Transform Data type is set to None.

The pane itself (Weather Report) also has no transformation specified. However, we do need to convert the complete XML result to HTML. That's the role of the Weather.XSL stylesheet specified in the Data section of the pane:

<?xml version="1.0"?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >

<xsl:output method="html" />

<xsl:template match="/">

<xsl:apply-templates />

</xsl:template>

<xsl:template match="VFPData">

<HTML>

<HEAD>

</HEAD>

<STYLE>

BODY {

font-family:verdana;

font-size:9pt;

margin-top:0px;

margin-left:2px;

margin-right:2px;

margin-bottom:2px;

}

H3 {

margin-bottom:0px;

margin-top:0px;

font-weight: bold

}

TD {font-size:9pt}

a:link { color: #0033CC;text-decoration: none}

a:visited { text-decoration: none}

a:hover { color: #CC0000;text-decoration: underline}

A { text-decoration: underline; font-family: Verdana, Arial, Helvetica, sans-serif; color: #0066FF

}

TD.TableTitle

{

padding:2px;

background-color:#8080C0;

color:#FFFFFF;

}

A.toggle:link { color: #000000;text-decoration: none}

A.toggle:visited { text-decoration: none}

A.toggle:hover { color: #000000;text-decoration: none}

A.toggle { text-decoration: none; color: #000000}

</STYLE>

<BODY leftmargin="0" topmargin="0">

<TABLE width="100%" cellspacing="0" cellpadding="0">

<TR>

<TD class="TableTitle" width="100%" nowrap="nowrap"><h3>Weather Report for Selected Cities</h3></TD>

<TD align="left" valign="center"><img src="weather.gif" alt="" /></TD>

</TR>

<TR>

<TD colspan="2" height="10"></TD>

</TR>

</TABLE>

<br/>

<xsl:apply-templates select="GetWeatherInfoResult"/>

</BODY>

</HTML>

</xsl:template>

<xsl:template match="GetWeatherInfoResult">

<table width="100%">

<tr>

<td class="TableTitle">

<font size="3">Conditions in <xsl:value-of select="Location"/>

as of <xsl:value-of select="LastUpdated"/></font>

</td></tr></table>

<table width="100%">

<tr><td>Current temperature: <xsl:value-of select="Temprature"/></td>

<td>Feels like: <xsl:value-of select="FeelsLike"/></td></tr>

<tr><td>Forecast: <xsl:value-of select="Forecast"/></td>

<td>Wind: <xsl:value-of select="Wind"/></td></tr>

<tr><td>Barometric pressure: <xsl:value-of select="Pressure"/></td>

<td>Humidity: <xsl:value-of select="Humidity"/></td></tr>

</table>

<br/>

</xsl:template>

</xsl:stylesheet>

These settings give you everything you need for the Weather Report pane. In the version in the session materials, I've set up four cities (New York, Philadelphia, Redmond, and San Diego), but you can set up whatever list interests you. Figure 36 shows the Weather Report pane.

Figure 36: A custom XML pane—This pane shows the weather for selected cities, using a web service that provides the information.

This example doesn't demonstrate all the features an XML or HTML pane can have. The Default Data page of the Pane Customization window lets you specify initial contents for a web-based pane, in case no web access is available the first time the pane is displayed. Once a pane has been used once, the contents are cached and those cached contents displayed if no web access is available.

Far more interesting is the Handler Code page. Not only can pane content be dynamic, but it can run code, navigate to other panes, open a browser, and pretty much anything else you can write code for. By convention, any URL in a pane that begins with the string "vfps:" (presumably, for "Visual FoxPro script") executes the handler code. The rest of the URL is parsed to indicate what action to take and to provide parameters for that action.

The Task Pane engine provides a number of script actions; they're shown in Table 2. For example, clicking on a hyperlink that has this URL opens a browser to the DevCon web site:

vfps:linkto?url=http://advisorevents.com/CMX0409p.nsf

Table 2 Predefined script actions—You can use these actions in your pane without writing any code.

Action	Purpose	Parameters received
gotopane	Switch to the specified pane	uniqueid=cPaneUniqueID
help	Display the specified help topic	id=cTopicID or topic=cTopicName
linkto	Open a browser displaying the specified web page	url=cUrl
message	Display a message box	msg=cMessage
options	Display the Task Pane Options dialog with a specified pane chosen	uniqueid=cPaneUniqueID
refresh	Reload the current pane	None

In addition, you can write custom code and define your own actions. Handler code is VFP code. It receives four parameters, shown in Table 3. When you click the Modify button on the Handler Code page to begin writing handler code, the window that opens contains the necessary parameter declarations, along with explanatory comments.

Table 3 Parameters to handler code—Code called by a "vfps:" link receives these parameters.

Parameter	Meaning
cAction	The action specified in the link, such as "gotopane."
oParameters	A collection listing the parameters passed in the link. The collection has a GetParam method to return the value of a specified parameter.
oBrowser	An object reference to the Browser ActiveX object in which the pane is displayed.
oContent	An object reference to the content of the pane.

A number of the panes provided with VFP 8 use handler code, using both the built-in actions and custom actions. Exploring those panes in the Pane Customization window is a good way to get a feeling for what's possible.

Publishing Panes

While you can create panes just for your own use, it's easy to distribute your panes to others. The tool allows you to create an XML file that others can install in their own Task Pane Manager. To publish a pane, highlight the appropriate pane in the Pane Customization window and click Publish. The Publish Pane dialog (Figure 37) lets you indicate exactly what portion of the pane and its associated files should be included in the XML file.

Figure 37: Publishing task panes—The Publish Pane dialog lets you specify which portions of the pane and which associated files are included in the XML file.

You have two choices regarding pane content. You can publish the entire pane, or only selected sections. For files, you have several options. Check Publish files associated with the pane to ensure that all the files used by the pane (such as TransformWeather.XSL in the Weather Report example) are included. Check Publish Files common to all panes to distribute files used by