# JavaScript Tutorial Komodo IDE only

## Overview

### Before You Start

This tutorial assumes:

- Some knowledge of HTML.
- You have the Firefox web browser installed.
- You have installed and configured the Komodo JavaScript Debugger Firefox extension.

Line numbers are referenced in this tutorial. To enable line numbering in the editor tabs, click View Line Numbers in the View menu.

### JavaScript Tutorial Scenario

This tutorial examines an HTML page that uses the Yahoo! User Interface Library and some additional JavaScript to create a special right-click context menu for an image map. In this tutorial, you will:

1. Open the JavaScript Tutorial Project.
2. Open jsdemo.html in Komodo and Firefox.
3. Analyze context-menu.js using the JavaScript debugger to see how it works.
4. Add dynamically generated links by manipulating DOM objects with JavaScript.

## Opening the Tutorial Project

On the Start Page under Tutorials and Documentation, click JavaScript Tutorial, or open the js_tutorial.kpf file from the samples/js_tutorials subdirectory of Komodo's user data directory

The tutorial project will open in the Projects sidebar.

### Overview of the Tutorial Files

The JavaScript tutorial project contains the following:

- jsdemo.html: This "City picker" demo is an HTML page that uses JavaScript to display special right-click context menus over an image map, and add the selected items to a table on the right.
- context-menu.js: A JavaScript file containing the functions used in jsdemo.html.
- YUI directory: A collection of Yahoo! User Interface JavaScript libraries used in the demo.

### Opening the City Picker

On the Projects sidebar, double-click jsdemo.html to open it in the Editor Pane.

If Firefox is not set as your default browser in Komodo's Web & Browser preferences, put the full path to jsdemo.html in Firefox's address bar to open the file.

If you have "Preview in external browser" specified in your Web & Browser preferences, and Firefox is your default browser, you can quickly open the file by clicking View|Preview in Browser ('Ctrl'+'K', 'Ctrl'+'V').

Try the application. Right-clicking over a country in the map brings up a country-specific context menu instead of Firefox's default context menu. Selecting a city from the menu adds that city under the appropriate country heading in the table to the right and removes it from the menu. Reloading the page resets the page to the initial view.

The context menu for Mexico is intentionally broken so that we can find the problem with the debugger later in this tutorial and fix it.

## Analyzing the JavaScript program

Look over jsdemo.html. Other than some inline CSS style for the YUI context menu, it's all HTML. The JavaScript that makes the page work is sourced from external .js files. The one we'll be working with is context-menu.js. Open it from the tutorial project.

The first thing we notice is the `cities` object. This is a list of the countries with nested lists of cities that belong to them. Next is the `demo` function, which contains the `onContextMenu` function that brings up the custom context menu, and the `onCitySelect` which controls the actions on that menu. The comments describe what is happening in the code.

Komodo Tip: To enable autocompletion for the YUI libraries, click Preferences... on the Code menu and select the YUI API Catalog in the Code Intelligence section.

## Debugging the Page Komodo IDE only

If you have not already done so, configure the JavaScript Debugger.

### Starting the Debugger

In Firefox refresh the City Picker page, click on Tools|Komodo JavaScript Debugger|Connect to Komodo Debugger, then move your mouse pointer over the image map.

If the debugger is configured correctly, the file event-min.js should open in a Komodo tab. Though you haven't set any breakpoints in this file, the debugger stops at the first line of JavaScript executed by the browser (in this case a YUI event handler). This gives you the opportunity to set breakpoints in the file if you want to, or step through the code with the Step In button.

To leave this event handler and start debugging context-menu.js, click the Go/Continue Debugging button in the main or debugging toolbar. Select the context-menu.js editor tab.

Set a breakpoint on line 62 of context-menu.js by clicking in the empty left margin. Breakpoints are displayed as an orange-red octagonal icon in the breakpoint margin.

Right-click over Mexico in the City Picker map.

Komodo Tip: While the JavaScript debugger is in a break state, clicking Interact on the Debug menu opens up a JavaScript shell where you can interact with the Firefox's JavaScript engine directly.

### Viewing and Changing Variables

As soon as the browser registers a right-click over Mexico on the image map, the debugger should stop on line 62 of context-menu.js. A yellow arrow icon indicating the current breakpoint will appear in the margin at that line.

One of the most useful things the debugger does is keep track of variables in the code. In the locals tab in the Output pane we can see a list of all variables in the current scope (i.e. variables in the `demo` function). The globals tab shows everything in the `window` object; you can see the DOM objects by expanding the `document` node in this list. The `instance` tab shows properties of the current object.

You may have noticed earlier that the context menu for Mexico is broken. The variables list in the locals tab can help us find out why.

The `curr_country` variable was set on line 61 and appears to have the value "Mexic" which doesn't match the `country` variable which is "Mexico".

We can modify this variable within the debugger while the it is in a break state. Double click on `curr_country` in the locals tab to bring up the Edit Variable Value dialog box. Change "`Mexic`" to "`Mexico`" and click "OK". Click the Go/Continue Debugging button to resume execution. The context menu for Mexico should appear in Firefox. (Note: The default context menu may appear initially because of how the debugger handles coming out of a break state. Clicking anywhere on the Komodo or Firefox windows will clear this and show the expected menu.)

That solved the problem for this debugging session only. We need to find out where that typo came from. Since the only appearance of the country's name in context-menu.js is spelled correctly on line 7, we can assume there's a problem in jsdemo.html. Since `curr_country` is taken from `e.target.id`, we can extrapolate that the "alt=" attribute of the image map area for Mexico is wrong.

Komodo Tip: If we didn't know where the `e.target.id` came from, we could use Komodo's Find... feature to locate the typo in jsdemo.html

## Adding Links

The cities are added to the country lists by manpulating the DOM. These are plain text `<LI>` elements, but it's fairly simple to turn these into useful links by creating an `<A>` element and populating it with a URL containing the selected city's name in an `href` attribute.

Wikipedia has a fairly simple URL syntax for topic names, and it has information on all of the cities in our lists, so we could easily use it for our link targets.

Lines 43 to 45 in context-menu.js handle creating the list elements and inserting the city name:

                var newItem = document.createElement("LI");
                newItem.appendChild(document.createTextNode(cityName));
                targetList.appendChild(newItem);

Insert the following after line 43 to create an `<A>` element:

                var newLink = document.createElement('A');

Wikipedia articles can be accessed by adding the subject name to the end of the base URL. To set the `href` attribute to a combination of the Wikipedia base URL and the selected city name, add the following line:

                newLink.setAttribute('href', 'http://en.wikipedia.org/wiki/' + cityName)

To insert this link in the list, modify the subsequent two lines to use `newLink` rather than `newItem`:

                newLink.appendChild(document.createTextNode(cityName));
                targetList.appendChild(newLink);

Save the file and reload the page. Selected cities will now appear as Wikipedia links.

## More JavaScript Resources

### Tutorials and Reference Sites

- W3 Schools JavaScript Tutorial: An easy to follow introduction to JavaScript and DOM.
- Mozilla's About JavaScript: An overview of the language with numerous links to reference material such as standards and proposals.
- W3C Document Object Model (DOM) page: Overview of the DOM interface with links to specifications.
- A re-introduction to JavaScript: A concice JavaScript tutorial/overview for programmers by Simon Wilson.
- Yahoo! User Interface Library: The example in this tutorial uses several "minified" versions of YUI libraries. The Yahoo! YUI pages have more readable, commented versions of these and other libraries along with documentation and examples.