EditLive! for Java JavaScript API RaiseEvent Example

Introduction

The raise event functionality of EditLive! for Java can be used in a variety of situations to complement the existing functionality of the EditLive! for Java applet.  For example, if a custom toolbar or menu item within EditLive! for Java was to call a JavaScript function which, in turn, called the window.open() function the new window created, with the use of some program scripting, could be used to receive extra user input.  Thus, a user may be able to select an image or file from a list presented in a new window, submit their selection back to another function in the parent page (the page in which the EditLive! for Java applet is embedded) and have the result of their selection placed into EditLive! for Java via the InsertHTMLAtCursor EditLive! for Java JavaScript API function.

This example demonstrates how the raiseEvent functionality of EditLive! for Java custom toolbar buttons and custom menu items may be used to complement the functionality of the EditLive! for Java applet.  This example combines client-side JavaScript and the EditLive! for Java JavaScript API to insert content into EditLive! for Java from image file browser present in another Web Page.

Getting Started

System Requirements

This example requires a JavaScript capable browser and a Web server.

Required Skills

The following skills are required prior to working with this sample:

Overview

This example consists of two Web pages and an XML configuration file for EditLive! for Java.  When the example is started the user will first be presented with a Web page with EditLive! for Java embedded in it.  This page also contains two JavaScript functions one of which is used to launch a new browser window containing a image selector and the other to insert the relevant image back into the instance of EditLive! for Java.  The second of these two pages is used for selecting an image to insert into EditLive! for Java.  A list of images is present on this page, images can be selected from this list, previewed and inserted into EditLive! for Java.

The XML configuration file for this example contains XML specifying a custom menu item and a custom toolbar button.  Each of these uses the raiseEvent functionality of EditLive! for Java.  In this example the regular Insert Image toolbar button has been replaced with a custom toolbar button which triggers the raiseEvent functionality.  The custom menu item present in this example may be found in the Insert menu and is listed as Insert Image.  In this example each of activating either of these commands will have the same effect.

This sample demonstrates how to perform the following with EditLive! for Java and JavaScript:

Examination of raiseeventconfig.xml

The raiseeventconfig.xml file contains the configuration information for the example.  This file configures the custom menu item and custom toolbar button to use the raiseEvent functionality of EditLive! for Java.  

Note: The examination here is only of those XML tags which pertain to the configuration of the custom menu item and custom toolbar button.  For more information on how to create a complete EditLive! for Java XML configuration file and other XML elements please see the EditLive! for Java XML Reference.

  1. Create a menu bar for use with EditLive! for Java.

    <editLiveForJava>
        ...
        <menuBar>
        </menuBar>
        ...
    </editLiveForJava>
  2. Create a menu for the custom menu item to be placed in.  In this case the menu is called the Insert menu.

    <editLiveForJava>
        ...
        <menuBar>
            ...
            <menu name="Insert">
            </menu>
            ...
        </menuBar>
        ...
    </editLiveForJava>
  3. Create the custom menu item which uses the raiseEvent functionality of EditLive! for Java.  The value corresponding to the raiseEvent function is the name of the JavaScript event from the raiseeventexample.htm page which will be used.  In this case the function's name is launchWindow.  The custom menu item will appear in the Insert menu as the Insert Image item.

    <editLiveForJava>
        ...
        <menuBar>
            ...
            <menu name="Insert">
                ...
                    <customMenuItem
                        name="exampleItem"
                        text="Insert Image"
                        action="raiseEvent"
                        value="launchWindow"
                    />
                ...
            </menu>
            ...
        </menuBar>
        ...
    </editLiveForJava>

Examination of raiseeventexample.htm

The raiseeventexample.htm file contains the main page for this example.  An instance of EditLive! for Java is embedded within this page.  Also contained with this page are two JavaScript functions which launch the gallery.htm page in a new browser window and insert the selected image into the instance of EditLive! for Java in this page.

  1. Include the EditLive! for Java JavaScript function library.

    <html>
        <head>
            <!--Include the EditLive! for Java JavaScript library file-->
            <script src = "../../../../redistributables/editlivejava/editlivejava.js" language="JavaScript" ></script> 
  2. Define the JavaScript function to launch the image gallery page (gallery.htm).

            <!--Define the JavaScript functions to interface with EditLive! for Java-->
            <script language="JavaScript">
            <!--
                //Called by the raiseEvent functionality in EditLive! for Java.
                //Launches a new window with the image selector (gallery.htm)
                function launchWindow(){
                    var remote=null;
                    //Open a new browser window with the properties defined
                    remote = window.open("gallery.htm",'Preview','width=' + 800 + ',height=' + 600        +',status=no,resizable=yes,scrollbars=no,location=no,toolbar=no');
                }

    The window.open function opens a new browser window containing the gallery.htm page.  The title of the page is set to Preview, the width and height to 800 and 600 pixels respectively.  The window is set so that it is resizable but without any scrollbars, location bar or toolbars.  When opening this new window it is assigned the reference remote in the current page (raiseeventexample.htm) this will allow us access to the fields in the new window from the original window.
  3. Define a JavaScript function to retrieve information from the image gallery page (gallery.htm) and place it into EditLive! for Java.  Note that this function is a direct continuation of the script above and as such both functions exist within the same <SCRIPT> tag.

                //Inserts the selected image from gallery.htm back into EditLive! for Java by
                //calling the InsertHTMLAtCursor function from the EditLive! for Java JavaScript API
                function insertImage(src){
                    editlivejava.InsertHTMLAtCursor(escape("<img src=\"" + src + "\">"));
                }
            -->
            </script>
        </head>
        <body>

    In this function editlivejava is the name given to the instance of the EditLive! for Java applet in the page.  The InsertHTMLAtCursor function is part of the EditLive! for Java JavaScript API.  The parameter src contains the file name of the image to be inserted into EditLive! for Java.  This value is passed in from the gallery.htm page when the user makes their selection.
  4. Create a form to place an instance of EditLive! for Java in.

            <form name = myForm>
  5. Create an instance of EditLive! for Java inside the form.

                <script language="JavaScript">
                <!--
                    //Create an instance of EditLive! for Java
                    var editlivejava;
                    editlivejava = new EditLiveJava("ELJApplet",640 , 400);
                    editlivejava.setDownloadDirectory("../../../../redistributables/editlivejava");
                    editlivejava.setLocalDeployment(false);
                    editlivejava.setXMLURL("raiseeventconfig.xml");
                    editlivejava.setDocument(escape('<html><body><p>EditLive! for Java Custom Functionality Example</p></body></html>'));
                    editlivejava.show();
                -->
                </script>
            </form>
        </body>
    </html>

Examination of gallery.htm

The gallery.htm file contains the image selector for this example.  This page has a <SELECT> list and a image preview as well as Insert Image, Preview Image and Cancel buttons.  The page also contains two JavaScript functions, one to assist with the insertion of the selected image into EditLive! for Java and the other to allow for the previewing of images.

  1. Define a JavaScript function which allows for the previewing of the selected image when the Preview button is pressed.

    <html>
        <head>
            <script language="JavaScript">
            <!--
                //This function displays the image in the Web page
                function previewImage(){
                    document.images[0].src = document.forms[0].imageList.options[document.forms[0].imageList.selectedIndex].value;
                }

    This function gets the URL representing the image location from the image list and stores it in the correct place in the Web page's DOM, thus displaying the image in the Web page.
  2. Define a JavaScript function which interacts with the raiseeventexample.htm page so as to place the image within EditLive! for Java.  Note that this function is a direct continuation of the script above and as such both functions exist within the same <SCRIPT> tag.

                //This function sends the selected image's details back to the parent
                //window so that it can be inserted into EditLive! for Java
                function insertImage(){
                    var parentWindow;
                    parentWindow = window.opener;
                    //Call the insertImage function of the parentWindow, the parameter is the URL for the image
                    parentWindow.insertImage(document.forms[0].imageList.options[document.forms[0].imageList.selectedIndex].value);
                    window.close();
                }

            -->
            </script>
        </head>
        <body>
            <form>

    This function retrieves the URL representing the image location from the image list and passes it as a parameter to the insertImage function in the raiseeventexample.htm page.
  3. Specify the image list.  Each image listed has a relative URL associated with it.  This URL represents the location of the image file on the server.  For this example to function correctly the URL, if relative, must be correct for both the raiseeventexample.htm and gallery.htm pages.

                <!--List the images, note that value for each option corresponds to
                the URL for the image relative to this page-->
                <select size=5 name="imageList">
                    <option value="eljlogo.jpg" selected>EditLive! for Java Logo
                    <option value="sample.jpg">Sample image
                    <option value="newimac.gif">New iMac
                    <option value="ibm_thinkpad.gif">IBM Thinkpad
                    <option value="applecomp.jpg">Apple Mac
                </select>
  4. Create the HTML buttons to access the relevant JavaScript functions as defined earlier in this page.

                <!--Buttons to call the JavaScript funtions defined above-->
                <input type="button" value="Preview Image" onclick="previewImage();">
                <input type="button" value="Insert Image" onclick="insertImage();">
                <input type="button" value="Cancel" onclick="window.close();">
            </form>
  5. Set the initial image and create a space in the page for the image.  The value of the src attibute of this tag will be edited by the previewImage function defined above in step 1.

            <!--Set the initial image-->
            <img src="sample.jpg" alt="Preview">
        </body>
    </html>

Partial XML Configuration

The following is a partial XML configuration file.  The configuration listed here would facilitate the creation of a custom menu item and custom toolbar button for this example.  However, the following XML listing would not be sufficient to correctly configure an instance of EditLive! for Java.   For more information on how to create a complete EditLive! for Java XML configuration file and other XML elements please see the EditLive! for Java XML Reference.

<editLiveForJava>
    ...
    <menuBar>
        ...
        <menu name="Insert">
            ...
                <customMenuItem
                    name="exampleItem"
                    text="Insert Image"
                    action="raiseEvent"
                    value="launchWindow"
                />
            ...
        </menu>
        ...
    </menuBar>
    ...
</editLiveForJava>

Complete HTML and JavaScript

The following is the completed code for the pages listed above.  Note, some changes have been made from the steps listed above.  The changes only effect the page formatting not the functionality.

raiseeventexample.htm

<html>
    <head>
        <title>EditLive! for Java JavaScript API Example</title>
        <link rel="stylesheet" href="stylesheet.css">
        <!--Include the EditLive! for Java JavaScript library file-->
        <script src = "../../../../redistributables/editlivejava/editlivejava.js" language="JavaScript" >
        </script>
        <!--Define the JavaScript functions to interface with EditLive! for Java-->
        <script language="JavaScript">
        <!--
            //Called by the raiseEvent functionality in EditLive! for Java.
            //Launches a new window with the image selector (gallery.htm)
            function launchWindow(){
                var remote=null;
                //Open a new browser window with the properties defined
                remote = window.open("gallery.htm",'Preview','width=' + 800 + ',height=' + 600 +',status=no,resizable=yes,scrollbars=no,location=no,toolbar=no');
            }

            //Inserts the selected image from gallery.htm back into EditLive! for Java by
            //calling the InsertHTMLAtCursor function from the EditLive! for Java JavaScript API
            function insertImage(src){
                editlivejava.InsertHTMLAtCursor(escape("<img src=\"" + src + "\">"));
            }
        -->
        </script>
    </head>
    <body>
        <!--Form to contain the instance of EditLive! for Java-->
        <form name = myform>
            <script language="JavaScript">
            <!--
                //Create an instance of EditLive! for Java
                var editlive1;
                editlivejava = new EditLiveJava("ELJApplet",640 , 400);
                editlivejava.setDownloadDirectory("../../../../redistributables/editlivejava");
                editlivejava.setLocalDeployment(false);
                editlivejava.setXMLURL("eljjsexample.xml");
                editlivejava.setDocument(escape('<html><body><p>EditLive! for Java Custom Functionality Example</p></body></html>'));
                editlivejava.show();
            -->
            </script>
        </form>
    </body>
</html>

gallery.htm

<html>
    <head>
        <title>EditLive! for Java Raise Event Example</title>
        <!--Define the JavaScript functions to interact with the raiseeventexample.htm page-->
        <script language="JavaScript">
        <!--
            //This function displays the image in the Web page
            function previewImage(){
                document.images[0].src = document.forms[0].imageList.options[document.forms[0].imageList.selectedIndex].value;
            }

            //This function sends the selected image's details back to the parent
            //window so that it can be inserted into EditLive! for Java
            function insertImage(){
                var parentWindow;
                parentWindow = window.opener;
                //Call the insertImage function of the parentWindow, the parameter is the URL for the image
                parentWindow.insertImage(document.forms[0].imageList.options[document.forms[0].imageList.selectedIndex].value);
                window.close();
            }

        -->
        </script>
        </head>
        <body>
            <h1>Image Gallery</h1>
            <p></p>
            <table>
                <tr><td valign="top">
                <form>
                    <!--List the images, note that value for each option corresponds to
                    the URL for the image relative to this page-->
                    <select size=5 name="imageList">
                        <option value="eljlogo.jpg" selected>EditLive! for Java Logo
                        <option value="sample.jpg">Sample image
                        <option value="newimac.gif">New iMac
                        <option value="ibm_thinkpad.gif">IBM Thinkpad
                        <option value="applecomp.jpg">Apple Mac
                    </select>
                    <br>
                    <!--Buttons to call the JavaScript funtions defined above-->
                    <input type="button" value="Preview Image" onclick="previewImage();">
                    <input type="button" value="Insert Image" onclick="insertImage();">
                    <input type="button" value="Cancel" onclick="window.close();">
                </form>
            </td>
            <td>
                <!--Set the initial image-->
                <img src="sample.jpg" alt="Preview">
            </td></tr>
        <table>
        </p>
    </body>
</html>

Summary

The raiseEvent functionality of EditLive! for Java may be used in differing situations to complement the existing functionality of the EditLive! for Java applet.  Custom toolbar buttons and menu items can call JavaScript functions which can perform developer defined functionality.  The results of such functions can be placed back into EditLive! for Java using one of the methods provided by the EditLive! for Java JavaScript API as demonstrated in this example.

See Also