Developer Notes for HelloWorld Example 2 - Classes
---------- GENERAL COMMENTS -----------

The programming techniques discussed here are the recommended way
to develop web pages in a 'future-proof' manner since they
deploy the ERM supplied Classes which are updated with each
release of Image Web Server to handle any problems encountered
with cross-browser support etc.  

---------- NOTE 1 - JavaScript Include Files -----------

These Javascript include files add in a number of pre-programmed javascript functions that save you the trouble of duplicating in your code. The majority are stored in the path '/ecwplugins/lib/scripts/'off the root of your server
when your Image Web Server is installed.
---------- NOTE 2 - checking the plug-in version -----------

ECWCheckPlugin();

This code calls a function in the NCSCheck.js file which goes through a process of checking the Browser type to ensure that a supported browser version is being used. If not, it branches to the Sorry.htm page to advise the user which browsers are supported. If a valid version of browser is being used then the code proceeds to check the version of the ECW Plug-in against the version number embedded in the IMAGE_WEB_SERVER_VERSION constant stored in the NCSConstants.js file. If the current installed
version is older than this value the user will be directed to the DownloadPlugin.htm page and prompted to upgrade the plug-in for their browser type. 

---------- NOTE 3 - defining the image array -----------

var imageArray = new Array(
    "ecwp://" + document.location.host +
"/sampleiws/images/usa/sandiego3i.ecw",
    "ecwp://" + document.location.host +
"/sampleiws/images/usa/1metercalif.ecw",
    "ecwp://" + document.location.host +
"/sampleiws/images/australia/parramatta.ecw",
    "ecwp://demo.ermapper.com/images/usa/1metercalif.ecw",
    "ecwp://demo.ermapper.com/images/geodetic/world/landsat742.ecw");

The Toolbar Object supports a dropdown list of image urls which when selected unload the existing image and substitute in the new image. This code sets up the array of images which will be used when we define the toolbar object.    
---------- NOTE 4 - onload event handling -----------

    function onLoadCB() {
        tOnLoadTimer = setTimeout("LoadHandler()", 500);
    }
   
The onload="onLoadCB()" in the <BODY> tag sets up the call
to this function. A timer is then set to call the LoadHandler() function. This delay is important for Netscape browsers which do not honor the onLoad event in the BODY tag well in that they will fire the event before the ECW Control is fully initialised. The delay allows the Control to be ready  before we try to access it's method otherwise an error could result.
   
    function onUnloadCB() {
        deleteCookie("NCSPluginInstallMethod");
    }
The "onUnload="onUnloadCB()" in the <BODY> tag sets up the  call to this function. It's purpose is to delete the cookie that was set when the page started defining which type of install method we would use for the control (Native or Java).   
---------- NOTE 5 opening the ECW Image Layer -----------

function LoadHandler() {
    clearTimeout(tOnLoadTimer);
    if (document.ECWView1.AddLayer("ECW",
                                "ecwp://demo.ermapper.com/images/geodetic/world/landsat742.ecw",
                                "RasterLayer", "") < 0 ) {
        alert(document.ECWView1.GetLastErrorText());
    }
    document.ECWView1.SetBackGroundColor("#DDDDDD"); // sets the background color of the View control
}

This function loads up a mosaiced Landsat image of the world residing on the demo.ermapper.com Image Web Server using the AddLayer method of the Control. If an error occurs the AddLayer method returns a -1 which is trapped and raises an error message. If successful the the AddLayer returns the layer number that holds the image, starting at layer 0 as the bottom layer
---------- NOTE 6 -------------

function ECWToolbarCB(uid, value)
{
    if (uid == "UID_VIEW_PAN")
    {
        document.ECWView1.SetPointerMode(0);
    ............
   
This function is called whenever the user clicks on a button on the Toolbar. The parameters passed in are 'uid', which define which button was clicked and 'value' which is exclusive or non-exclusive. Depending on the uid assignment the Control's SetPointerMode is called to change the pointer mode accordingly or for the reset the SetExtentsAll() method is used to return the map view to it's full image extents.
---------- NOTE 7 -------------

else if (uid == "UID_IMAGE_COMBO")
    {
        document.ECWView1.DeleteAllLayers();
        if (document.ECWView1.AddLayer("ECW", value, "RasterLayer", "") < 0 ) {
            alert(document.ECWView1.GetLastErrorText());
        }
    }

This code is called if a new image is selected from the dropdown combo box. The existing image layer is cleared using the .DeleteAllLayers method. Then the new image url supplied by the 'value' parameter is opened and the return value tested for -1 to trap and alert an error if it occurred.  
---------- NOTE 8 -------------

    setCookie("NCSPluginInstallMethod", "NATIVE");
   
The NCSCreateView() function handles installing a control into your page. Two types of controls are supported as follows:
   
NATIVE - This is an ActiveX Control which is used for Internet Explorer browsers and a Plug-in for Mozilla type browsers

JAVA - NCSCreateView will embed a JAVA Applet into your page if this cookie is set to "JAVA" instead of "NATIVE"
---------- NOTE 9 -------------

    setCookie("NCSPluginInstallMethod", "NATIVE");
    <body onLoad="onLoadCB();" onUnload="onUnloadCB();" border=20>
   
    See Note 3 for explanation of what these calls do.
---------- NOTE 10 ------------

   var ECWToolbar1 = new NCSToolbar("UID_VIEW_TOOLBAR", null, false, -1);
   
    This is a declaration for a new Toolbar object which is defined in the include javascript files. The parameters passed to the object are as follows:
    var ECWToolbar1
        - The name of this Toolbar Object
    "UID_VIEW_TOOLBAR"
        - This is a unique id (uid) for this html element
    null
        - ojectID - write code to page directly when null specify HTML object if not null
    false
        - bShowStatusBar shows a text status bar under the toolbar, when you hover over a toolbar item its description is shown.
   -1 
        - nCols specifies the number of colums before the toolbar wraps, -1 means no wrap.
---------- NOTE 11 ------------

    ECWToolbar1.addButton("Pan around the image by click-dragging the hand on the image",                      "/ecwplugins/lib/bitmaps/buttons/roam.png", "/ecwplugins/lib/bitmaps/buttons/roamSelect.png", true, ECWToolbarCB, "UID_VIEW_PAN");

    The .addButton method is used to add a new toolbar button to the Toolbar Object defined in Note 6. The paramaters that get specified are as follows:
   "Pan around the image by click-dragging the hand on the image"
         - description button displayed in status bar & ALT
   "/ecwplugins/lib/bitmaps/buttons/roam.png"
         - The path for button image when this tool not selected
    "/ecwplugins/lib/bitmaps/buttons/roamSelect.png"
         - The path for button image when this tool is selected
   true   
         - Boolean value (true = exclusive & false = non exclusive)
   ECWToolbarCB
         - Function to call when user clicks the button
   "UID_VIEW_PAN"
         - The Constant value passed to called function as 'uid'
---------- NOTE 12 ------------

  ECWToolbar1.addPopdownCombo ("", imageArray, ECWToolbarCB, "UID_IMAGE_COMBO");
   
    This code uses the .addPopdownCombo method of the Toolbar class to create a dropdown combo box holding the images  defined in the imageArray above. The parameters passed are as follows:
   
    ""  
        - description of the object, same as the addButton() call (no name reqd)
   imageArray                  - the imageArray which was populated in Javascript on startup
   ECWToolbarCB                 - the function to call when a new image is selected from the combo box
    UID_IMAGE_COMBO             - the 'uid' name which is passed to the ECWToolbarCB function
---------- NOTE 13 ------------

   document.writeln(ECWToolbar1.rebuild());
        ECWToolbar1.setCurrentItem("UID_VIEW_PAN");
        ECWToolbar1.getTable().border=0;
        ECWToolbar1.getTable().cellSpacing=2;
        ECWToolbar1.getTable().cellPadding=0;
           
We have not created a Toolbar Object called ECWToolbar1 and added buttons to the object. The .rebuild method places the toolbar onto the webpage using 'document.writeln'. You will notice that all of this toolbar code is enclosed within a table cell <td></td> and this defines the position for the toolbar. The parameters defined are as follows:
   
    ECWToolbar1.setCurrentItem("UID_VIEW_PAN");         - controls which button is selected on startup
    ECWToolbar1.getTable().border=0;                 - controls the border of the surrounding table
    ECWToolbar1.getTable().cellSpacing=2;             - controls the cellSpacing of the surrounding table
    ECWToolbar1.getTable().cellPadding=0;             - controls the cellPadding of the surrounding table    
---------- NOTE 14 ------------

  NCSCreateView("ECWView1", "100%", "400", PARAM_VIEW_ONPERCENTCOMPLETE, "ECWProgressBar.setProgress(value);");
   
    This code calls a function defined in the javascript include files to create a Layered View Control Object. This object is used to display images in a "stack" of images. These are the parameters passed to the NCSCreateView function:
    "ECWView1"                           - The name of this Control
  "100%"                               - The width of the View Control (can be in percent as shown or pixels)
    "400"                                 - The height of the object (can be in pixels as shown or in percent)
    PARAM_VIEW_ONPERCENTCOMPLETE         - This sets up a callback (event) which is fired whenever the views '% loaded' changes
   "ECWProgressBar.setProgress(value);" - This calls the setProgress method of the ECWProgressBar object (defined below) to update display.
---------- NOTE 15 ------------

    ECWProgressBar = new NCSProgressbar("NCS_UID_PROGRESS", null, 70, true);
       
This code creates a new Progressbar object named 'ECWProgressBar'. The parameters passed are as follows:
        NCS_UID_PROGRESS             - defines the object type
       null                         - null means write the html to the page directly
        70                            - the width of the progressbar object in characters
        true                         - controls whether to display a text readout of percentage value
               
    ECWProgressBar.label = "Progress : ";
       - Defines the label to display to the left of the progress bar object
    document.writeln(ECWProgressBar.build());
       - code to place the progressbar object on the html page