Developing a new Chameleon Widget

What follows here is a step-by-step set of instructions to develop a new widget from a template widget file. By following these steps, you will build a new, fully functional widget that is Utterly Useless biggrin. But it will show you how to get started on your own new widgets!

The widget we will be making is called the Utterly Useless Widget - or UUW as we will refer to it in the code. It does very little that is useful, but it does highlight most of the features of a widget including how to access information about the current state of the map through mapscript.

Download the files attached to this page by clicking the attachments link at the top and then downloading each file.

Although I presented this at MUM3, most of the credit should actually go to Bill who put the template widget together and developed this little tutorial. Of course, with the credit also goes the blame for any mistakes biggrin

Prerequisites: A working Chameleon application with a MapDHTML widget and an ErrorReport? widget. You can use the UUW Application attached to this page.

1. Extract WidgetTemplate?.tar.gz and copy template folder to the "/htdocs/widgets/" directory and rename it "UUW".
2. Copy the "utils.inc.php" file to the new "UUW" folder.
3. Open the new "UUW" folder and rename "WidgetTemplate?.dbf" to "UUW.dbf" and "WidgetTemplate?.widget.php" to "UUW.widget.php".
4. Open "UUW.widget.php" in any text editor and replace all occurrences of "WidgetTemplate" with "UUW".
5. Save changes.
6. Open a working Chameleon template and add the new widget. The definition should look something like this:

<cwc2
   type="UUW" 
   imagetip="Info" 
   image="icons/icon_query.png" 
   styleresource="NavButtons" 
   imagewidth="25" 
   toolset="nav">
     <image state="normal"/>
     <image state="hover"/>
     <image state="selected"/>
</cwc2>

7. Run the Chameleon application. You should see a navtool button for your new widget. It doesn't do anything at the moment.
8. Add a report member variable to store our output.

var $mszReport;

9. Add code to initialize the report member variable and to make the map respond to mouse clicks. Add the following block of code to the "InitDefaults()" function:

// init the widget defaults
$this->SetNavCommand('UUW');
$this->mszReport = '';

10. Save your changes and test the application. The map should now respond to mouse clicks.
11. Now lets add some code to check the URL to see respond to the "UUW" navigation command. Add the following block of code to the "ParseURL()" function:

// work some magic
if ( $this->isVarSet( "NAV_CMD" ) &&
                           $this->getVar( "NAV_CMD" ) == 'UUW' )
{
   $this->mszReport = 'My Report Test';   
}

12. Now we're generating a report when the "UUW" command is used. We still need to output the results. To do this, we'll create a javascript function to present the report. Enable the "GetJavascriptFunctions()" function by deleting the line "/** REMOVE THIS LINE TO USE THIS FUNCTION" (approximately line 331).
13. Add the following block of code to create a "showReport()" javscript function:

// show the report
$szShowReport = strlen( $this->mszReport ) > 0?"alert('".$this->mszReport."')":"";
$szJsFunctionName = "showReport";
$szFunction = <<<EOT
function {$szJsFunctionName}()
{
   {$szShowReport};
   return true;
}
EOT;
$aReturn[$szJsFunctionName] = $szFunction;

14. Now we need to make this function execute after the page has loaded to present the user with the report. Enable the "GetJavascriptOnLoadFunctions ()" function by deleting the line "/** REMOVE THIS LINE TO USE THIS FUNCTION" (approximately line 410).
15. Add the "showReport()" javascript function to the list of functions to be run after the page has loaded by adding the following block of code to the "GetJavascriptOnLoadFunctions()" function:

// show report
$aReturn['showReport' = "showReport();\n";

16. Save your changes and test the application. You should see a javascript alert report.
17. Add a line to include some misc. utilities to help with the report. Add the following code to the top of the file just below the "NavTool.php" file inclusion statement:

// include supporting widget specific functions
include( 'utils.inc.php' );

18. Add some code to return some information in your report. This code makes use of the functions you included from the "utils.inc.php" file. Revisit the "pasrseURL()" function and remove the following line:

$this->mszReport = 'My Report Test';

and replace it with the following code block:

// get the mapfile and generate report on layers
$oMap = &$this->moMapNavigator->oSession->oMap;
           
// get the x and y pix coords
$nPixX = ( $this->isVarSet( "MAP_CURSOR_POS_X" ) ) ?
                                 $this->getVar( "MAP_CURSOR_POS_X" ):0;
$nPixY = ( $this->isVarSet( "MAP_CURSOR_POS_Y" ) ) ?
                                 $this->getVar( "MAP_CURSOR_POS_Y" ):0;
                                       
// report pixel coords
$this->mszReport .= reportPixelCoords( $nPixX, $nPixY );
               
// report the x and y geo coords
$this->mszReport .= '-------------------\n';
$this->mszReport .= reportGeoCoords( $nPixX, $nPixY, $oMap );
           
// report layer status
$this->mszReport .= '-------------------\n';
$this->mszReport .= reportLayerStatus( &$oMap );

19. Save your changes and test the application. You should now see a much more informative report.
20. Now let's add some attributes to the widget to control the output. Add two new member variables to the widget class object just below the "$mszReport" member variable you added in step 8 (approximately line 52):

var $mszCoords;
var $mbLayerStatus;

21. Now let's add two new attributes to the widget. We'll add a String attribute called "COORDS" that will indicate which coordinates will be reported, pixel coordinates, geographic coordinates, or both. The attribute will be limited to ‘pix', "geo", and "both" values. The other attribute will be a Boolean attribute called "LAYERSTATUS". It will indicate whether or not to show the status of all layer. Add the following code block to the constructor of the widget (approximately line 89):

    // add attributes
    $this->maAttributes['COORDS'] =
    new StringAttribute( 'COORDS', true, array( 'pix','geo','both' ) );
       $this->maAttributes['LAYERSTATUS'] = 
       new BooleanAttribute( 'LAYERSTATUS', false );
    

22. In order to use the attribute values, we need to read them and push them into the two member variables we created in step 20. Add the following code block to the end of the "InitDefaults()" function (approximately line 127):

    // set the values from the attributes
    $this->mszCoords = isset( $this->maParams['COORDS'] )?
                                           $this->maParams['COORDS'] : '';
    $this->mbLayerStatus = isset( $this->maParams['LAYERSTATUS'] ) &&
                                           $this->maParams['LAYERSTATUS'] == "true";
    

23. Save your changes and test the application. You will see that the widget is broken and it will appear as red text in the application. If you have the ErrorReport? widget in your application you will see a message indicating that the required attribute "COORDS" is missing. This is correct because we have made the "COORDS" attribute mandatory, but not the "LAYERSTATUS" attribute.
24. Update your widget tag in your template to include the two new attributes we have just created. The updated widget tag should look something like this:

<cwc2
   type="UUW" 
   coords="pix"
   layerstatus="true"
   imagetip="Info" 
   image="icons/icon_query.png" 
   styleresource="NavButton" 
   imagewidth="25" 
   toolset="nav">
    <image state="normal"/>
     <image state="hover"/>
     <image state="selected"/>
</cwc2>

25. Save your template and test your application. You should now have a working application that does not yet respond to the new attribute values.
26. Now let's add the logic to respond to the attribute values. This will be done in the "parseURL()" function. Update the code from step 18 to look like the following:

// get the mapfile and generate report on layers
$oMap = &$this->moMapNavigator->oSession->oMap;
           
// get the x and y pix coords
$nPixX = ( $this->isVarSet( "MAP_CURSOR_POS_X" ) ) ?
                                  $this->getVar( "MAP_CURSOR_POS_X" ):0;
$nPixY = ( $this->isVarSet( "MAP_CURSOR_POS_Y" ) ) ?
                                  $this->getVar( "MAP_CURSOR_POS_Y" ):0;
                                       
// report pixel coords if necessary
if ( $this->mszCoords == 'pix'
$this->mszCoords == 'both' )
$this->mszReport .= reportPixelCoords( $nPixX, $nPixY );
// report the x and y geo coords if necessary
if ( $this->mszCoords == 'geo'
$this->mszCoords == 'both' )
{
   // add divider if necessary
   if ( strlen( $this->mszReport ) > 0 )
       $this->mszReport .= '-------------------\n';
   $this->mszReport .= reportGeoCoords( $nPixX, $nPixY, $oMap );
}
      
// report layer status
if ( $this->mbLayerStatus )
{
   // add divider if necessary
   if ( strlen( $this->mszReport ) > 0 )
       $this->mszReport .= '-------------------\n';
   $this->mszReport .= reportLayerStatus( &$oMap );
}

27. Save your changes and test the application. You should now have a fully functional widget. Try different values in the attributes and be sure that they are working correctly.


List of attached files

name	uploaded	size	dls	desc
PaulSpencerChameleonWidgetPresentation.ppt	Thu 08 of Sep, 2005 [13:58 UTC] by pspencer	134.66 Kb	460	my presentation at MUM3
utils.inc.php.tar.gz	Thu 08 of Sep, 2005 [13:40 UTC] by pspencer	3.85 Kb	799	some helper functions used by the UUW
UUWApplication.tar.gz	Thu 08 of Sep, 2005 [13:39 UTC] by pspencer	1.68 Kb	904	Simple Application to test the UUW
WidgetTemplate.tar.gz	Thu 08 of Sep, 2005 [13:37 UTC] by pspencer	3.35 Kb	909	Template for a new widget

Created by: pspencer last modification: Tuesday 13 of November, 2007 [16:40:32 UTC] by nsavard

Printer Friendly

Contact Information

Chameleon Users List