MyEclipse Logo

MyEclipse JavaScript Development and Debugging Tutorial

Outline

  1. Preface
  2. Requirements
  3. Introduction
  4. Installing the Sample Application
  5. Working with JavaScript Source
    1. Creating JavaScript files
    2. Editing JavaScript files
    3. Validating JavaScript source
  6. Debugging Local JavaScript Applications
    1. Setting JavaScript breakpoints in HTML
    2. Launching and Debugging your HTML/JavaScript Source
    3. Stepping through JavaScript code
    4. Inspecting Variables
  7. Debugging JavaScript Applications From a Server
  8. Debugging JavaScript Applications With No Local Source Files (a.k.a. Instant-On Debugging)
  9. Known Limitations
  10. Summary
  11. User Feedback
  12. Resources

1. Preface

This document was written using MyEclipse 6.0 GA, Sun Java 5, and Eclipse 3.3. All screenshots are based upon the default user interface settings for MyEclipse Enterprise Workbench, Eclipse, and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.

2. Requirements

Below is a list of requirements for this Tutorial:

  1. MyEclipse 4.1 GA or greater (see Resources for a download link)
  2. Java 2 SDK, Standard Edition 5 or later installed (see Resources for a download link)
  3. Eclipse 3.3 SDK (see Resources for a download link)

3. Introduction

MyEclipse Enterprise Workbench ships an innovative set of technologies collectively known as the MyEclipse AJAX Tools Platform™ (W2TP). This tutorial introduces the basic features, concepts, and techniques for getting started with MyEclipse W2TP JavaScript development and debugging facilities. A simple web application known JS_Mario is provided as the context for introducing JavaScript development features in this document. It is assumed that you are familiar with the JavaScript language and concepts as they are very different from Java's object-oriented concepts. For questions and concepts not fully covered in this tutorial, we refer you to the Resources section for a list of JavaScript resources.

Specifically this document presents how to:

  • Use the MyEclipse JavaScript editor to create and modify JavaScript source code
  • Validate JavaScript source code and resolve errors
  • Use the MyEclipse JavaScript debugging facility to debug local and deployed JavaScript resources. This includes:
    • Set breakpoints in JavaScript, HTML and JSP files
    • Launch a JavaScript debugging session
    • Perform the debug actions: Step into, Step over, Resume, Terminate
    • Step from HTML documents into JavaScript files
    • View the JavaScript exception stack and inspect variables at breakpoint execution context
  • Use the MyEclipse JavaScript Debugging facility to debug remote JavaScript resources

Note-1 : Completion of the Web Project Tutorial is recommend before debugging JavaScript resources deployed as part of a web application.

Note-2: Please familiarize yourself with the known limitations of the MyEclipse JavaScript development tools. Of special note JavaScript debugging in MyEclipse 5.0 GA is only supported on the Windows an Linux platforms. Mac support is still under development.


Figure 1: MyEclipse JavaScript Debugger

4. Installing the Mario Web Project

A simple MyEclipse web application named JS_Mario is used to demonstrate the MyEclipse JavaScript development features. Mario consists of a single webpage that uses JavaScript to animate an image of the Nintendo™ Mario character on an HTML web page. Installing the project is a simple two step process.

Step 1: Download the JS_Mario Project

Select the following link to begin downloading the js_mario.zip archive containing the JS_Mario web project. Save the archive to your local file system and proceed to Step-2.

Step 2: Import JS_Mario Project into MyEclipse workspace

  1. From the MyEclipse menubar select File > Import > General > Existing Projects into Workspace.
  2. Choose the "Select archive file" option and browse to the location of the downloaded js_mario.zip archive and select it.
  3. Choose OK to complete the import process.


Figure 2: Importing JS_Mario project using the Project Import Wizard

Step 3: Verify Project Installation

Upon completion of step-2 open the Navigator view or the Java Package Explorer view and verify that your imported project is consistent with Figure 3.


Figure 3: Newly imported JS_Mario project structure

5. Working with JavaScript Source

5.1 Creating JavaScript Files


To create a new JavaScript source file do the following:

  1. From the MyEclipse menubar select File > New > Other > MyEclipse > Web > JavaScript. This will launch the New JavaScript wizard.
  2. Navigate to the destination project and folder location
  3. Enter the new file name with the .js extension
  4. Select Finish to complete the process

Figure 4a: Launching New JavaScript file wizard
Figure 4b: Entering the New JavaScript file name

5.2 Editing JavaScript Files

The MyEclipse JavaScript Editor provides advanced language specific editing features such as:

  • Smart code assist for built-in and custom objects with browser compatibility details
  • Syntax highlighting
  • Validation and style checking
  • Outline view with content filtering and selection synchronization
  • Quick comment toggling

Content-Assistance
 To view JavaScript code-assist proposals place your cursor in a context for which a completion proposal is desired and then press the Ctrl+Space key combination. If code completion proposals are available they will be presented in a popup window. Each proposal includes a small graphic indicator of whether the JavaScript proposal is supported by IE and Netscape/Mozilla/Firefox. If a browser compatibility indicator is grayed out then the proposal is not supported by that browser.


Figure 5: JavaScript content-assist example

JavaScript Outline View
The outline view depicts a structured view of the functions and variables of a JavaScript Editor. The variables in the list may be filtered using the "Show Variables" action from the view's menubar.


Figure 6: Outline view with activated menu

Quick Comment Toggle
To toggle on or off one or more single line comments select the region to comment and enter Ctrl+Shift+C .


Figure 7a: Mark region to comment
Figure 7b: Commented region after Ctrl+Shift+C

5.3 Validating JavaScript Source

The MyEclipse source-code validation system supports validation of JavaScript files. When enabled, validation will occur when you manually validate the project, save & build the project, and while you type.

Enable JavaScript Validation

  1. Open the MyEclipse validation preferences, Window > Preferences > MyEclipse > Validation
  2. In the list of validators select the JavaScript Validator
  3. Select OK to save and apply these changes


Figure 8a: Configuring JavaScript source validation

You can also set the validator preferences on a per-project basis by selecting a project, right clicking, and selecting the properties action.  In the properties dialog select the MyEclipse-Validation property page.  You must activate the Override validation preferences option and then you can configure the JavaScript Validator specifically for your project.


Figure 8b: Configuring JavaScript source validation on a per-project basis

Validating JavaScript Files

Once JavaScript source code validation is enabled the validator will be executed while typing, each time a JavaScript file is saved, or when the validator is executed manually. To manually execute the validator, select one or more JavaScript files and then from the context-menu (right-click menu) select the MyEclipse > Run Validation action.

Viewing Validation Problems

Validation problems are indicated as warning markers in the JavaScript Editor, Problems view and in the Package Explorer view. To view problem details, in the JavaScript fly-over a warning marker in the left margin as shown in Fig. 9.


Figure 9: Viewing JavaScript validation errors

6. Debugging Local JavaScript Applications

The MyEclipse JavaScript Debugging System is integrated into the Eclipse debugging architecture and is an integral part of the MyEclipse Web 2.0 Tools Platform (W2TP). In this section we will present a JavaScript debugging scenario that involves:

  • Setting breakpoints in an HTML file and its included JavaScript source file
  • Launching the HTML file as a JavaScript Application that will execute and halt at JavaScript breakpoints
  • Stepping from a JavaScript breakpoint in an HTML file into a JavaScript source file
  • Inspecting the debug stack and variables

6.1 Setting JavaScript Breakpoints in HTML


JavaScript breakpoints can be set in the JavaScript editor, the HTML Web Designer or the JSP Web Designer. Within any of these editors, JavaScript breakpoints are set in the left-hand margin (often referred to as the editor gutter) by double-clicking next to the source line or by right clicking and selecting Toggle Breakpoints.

Note within an HTML or JSP file, JavaScript breakpoints can only be set on JavaScript source lines nested in a <script> element.

  1. Open the runmario.html file in the MyEclipse HTML Web Designer by double-clicking it in the Package Explorer or Navigator view or use the context-menu Open With... action to select the editor
  2. In the editor on the left margin at line #9, right-click and select Toggle Breakpoints or double-click to create a JavaScript breakpoint.


Figure 10: Setting a JavaScript breakpoint

Figure 11, below illustrates a JavaScript breakpoint set on line #9. To remove a JavaScript breakpoint simply double-click the breakpoint image or use the context-menu Toggle Breakpointsaction to remove the breakpoint.


Figure 11: Fly-over of JavaScript breakpoint

6.2 Launching and Debugging HTML/JavaScript Source


There are multiple options for initiating a JavaScript debugging session. In this section we demonstrate launching a debug session directly from the HTML Web Designer.

  1. Open the the runmario.html file in the HTML Web Designer
  2. From context menu select Debug As > JavaScript Application ...


Figure 12: Launching an HTML file as a JavaScript Application

  1. The MyEclipse JavaScript Debugger is launched along with the MyEclipse AJAX Web Browser. The browser loads and begins executing the runmario.html file
  2. The onload() method calls the runMario() JavaScript function. This activates the breakpoint set on line #9 and launches into the Eclipse Debug perspective...
  3. The Debug perspective includes a Call Stack view, a JavaScript Variables view and source editors opened while viewing activated breakpoints.


Figure 13: JavaScript breakpoint hit during execution

6.3 Stepping Through JavaScript Code


When halted at a breakpoint the following actions are available from the toolbar of the Debug View

Resume execution; runs to next breakpoint or end of program

Terminate debug process

Step Into next executable source line

Step Over next function

Step to Return of current function



We continue with our debugging scenario:

  1. Choose the Step into. .. action (see Figure 14) to move the execution context to the next executable source line. In this example line #9 transfers control to the enableAnimation() function in the mario.js file.

Figure 14: Initiate "Step into" debug action
  1. The debugger opens the mario.js file in the JavaScript editor and steps into it.


Figure 15: Debug context opens the mario.js source file

  1. Before we advance, set a breakpoint in the makeRun() function of mario.js
  2. Hit Resume to run to the next breakpoint
  3. The Debugger stops in the makeRun() function


Figure 16: Debugger stopped at makeRun() function

  1. Select Resume to continue execution. Notice the animation


Figure 17: Animated Mario

  1. Select the Terminate action to terminate JavaScript debugging session
  2. The MyEclipse AJAX Web Browser closes and the JavaScript process is terminated in the Debug view


Figure 18: Terminating the JavaScript debug session

6.4 Inspecting Variables


When stopped at a breakpoint or stepping through JavaScript execution, JavaScript variable values may be inspected using the Variables view. This view allows you to expand functions that are in scope and browse their properties and corresponding values. As you step through JavaScript functions the Variables view dynamically updates and refreshes its variable values as they change in order to provide you an accurate view of the execution state of your application.


Figure 19: Variable view of breakpoint state

7. Debugging JavaScript Applications From a Server

In the prior section we covered JavaScript debugging basics using the application files directly. In this section we'll be using the same example to demonstrate how to configure a advanced launch configuration to execute deployed web application resources that contain JavaScript breakpoints.

Since the Mario example from the prior sections is a MyEclipse Web Project, the first step to remotely debugging the example is to deploy it on your chosen application server. The detailed instructions to accomplish this are in section 7.1 of the Working with Web Project Tutorial here. In this specific example we'll be using Tomcat 5 as the server.

Once deployed, your server must be launched and allowed to load the application. Details on configuring an application server for use with MyEclipse are contained in section 4 of the Application Server Tutorial while instructions for launching the server are detailed in section 7.1 of the same tutorial.

Once you've followed the tutorials to deploy the test application and have started the server, debugging can begin. As in section 6, we'll need to configure a JavaScript Application launch configuration. However, since we're going to be performing server-based debugging we'll need to provide a custom configuration that will specify the correct URL for the page as referenced from the server. There are multiple options for initiating a JavaScript debugging session. Here we demonstrate launching a debug session directly from the HTML Web Designer.

  1. Open the the runmario.html file in the HTML Web Designer
  2. From context menu select Debug As > Debug...


Figure 20: Launching an HTML file as a remote JavaScript Application

  1. Once the configuration dialog displays, select 'JavaScript Application' from the list of configurations and select the New Launch Configuration button. A new configuration will be created which will look like the following one.


Figure 21: Initial Mario Launch Configuration

  1. Next, we need to modify the default configuration by changing the 'Launch URL' to point to the remotely served page, rather than the local file. For this example the application has been deployed on Tomcat so the correct remote URL for it is http://localhost:8080/JS_Mario/runmario.html, as shown below.


Figure 22: Corrected remote Mario Launch Configuration

  1. Once the name and URL have been updated, select the 'Debug' button to launch the MyEclipse AJAX Web Browser to begin debugging, just as we did in section 6 while debugging the file locally.

From this point, debugging JavaScript in pages served from an application / web server behaves identically to the 'file based' debugging that was detailed in section 6. Additionally, although this particular server debugging example used an HTML file, a JSP file that contained or referenced JavaScript would be handled the same way, as long as the URL in the launch configuration is updated appropriately.

8. Debugging JavaScript Applications With No Local Source Files (a.k.a. Instant-On Debugging)

Some JavaScript frameworks, for example DWR, generate JavaScript based on another description language .  Debugging these applications, as well as other applications for which there is no local source requires special tactics.  The Instant-On debugging feature allows you to debug these applications as well as investigate existing JavaScript applications to determine how they work without having to make a local copy.

We will use Google Maps to illustrate this feature.

Start by opening a new MyEclipse AJAX Web Browser. In the Address bar enter http://maps.google.com. Now click the instant-on JavaScript debugging button located in the toolbar next to the New MyEclipse AJAX Web Browser action.

Note: You must use the MyEclipse AJAX Web Browser to navigate to the web page you'd like to debug. The other web browsers currently do not support instant-on debugging.


Figure 23: Instant-on JavaScript Debugging Button

In the Debug Perspective you will see that a JavaScript debug session has been started for Google Maps. But a debug session alone doesn't help us understand the application.  We still need to be able to set breakpoints and view the JavaScript scripts that comprise Google Maps. To facilitate this bring the JavaScript Scripts Inspector View into focus. It has been added to the default Debug Perspective, so if you don't see it you can select Window > Reset Perspective to open it.

In the JavaScript Scripts Inspector View you will see the script files that comprise the Google Maps application. If you select one of these scripts and expand the tree you will see the individual functions that make up this file. By double clicking or seletcing one of the top level files or methods you can open an editor on that method or file.

Once you have an editor open on the remote script you can add breakpoints to it like you would for a local JavaScript application.


Figure 24: Using the JavaScript Scripts Inspector to open JavaScript scripts in the editor

9. Known Limitations

  • Below is a list of Eclipse debugging actions that are not yet available in MyEclipse 5.0 GA.
    • Run-To-Line capability
    • Conditional breakpoints
    • Setting source path lookup for Launch configurations
    • Exceptions in the Variables View
    • Variables sorting in Variables View
  • Multiple JavaScript Debug sessions, MyEclipse 5.0 GA only allows one debug session to be running at a time
  • Concurrent JavaScript context serialization
  • Stepping off JavaScript stack frame doesn't resume debug session
  • Alert, Password, Certificate dialogs may not open with the correct default size

10. Summary

This concludes your introduction to JavaScript Development and Debugging using MyEclipse. Additional Tutorial documents are available that introduce working with the Database Explorer, Struts, JSF, Web Projects, editing, application server configuration, EJB development, and enterprise application projects. For more information visit the MyEclipse Tutorial library.

11. User Feedback

If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum.

12. Resources