| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. --> |
| <!-- Use is subject to license terms.--> |
| <head> |
| <title>Editing JavaScript - NetBeans IDE Tutorial</title> |
| <meta name="description" |
| content="A document describing improved JavaScript editing features in NetBeans IDE."> |
| <link rel="stylesheet" href="../../../netbeans.css"> |
| |
| </head> |
| |
| <body> |
| <h1>Editing JavaScript</h1> |
| |
| <p>The NetBeans IDE provides enhanced JavaScript editing features |
| that are modeled on support already provided for Java, Ruby, and other languages. |
| This guide provides an overview of those features.</p> |
| |
| <div class="indent"> |
| <h3>Contents</h3> |
| |
| <p><img src="../../../images_www/articles/71/netbeans-stamp-71-72.gif" class="stamp" width="114" height="114" |
| alt="Content on this page applies to NetBeans IDE 7.1" |
| title="Content on this page applies to NetBeans IDE 7.1"></p> |
| |
| <ul class="toc"> |
| <li><a href="#basic">Basic Features</a></li> |
| <li><a href="#semantic_highlighting">Semantic Highlighting</a></li> |
| <li><a href="#mark_occurrences">Mark Occurrences</a> </li> |
| <li><a href="#instant_rename">Instant Rename</a></li> |
| <li><a href="#refactoring">Refactoring</a></li> |
| <li><a href="#quickfixes">Quick Fixes and Semantic Checks </a></li> |
| <li><a href="#tasklist">Tasklist</a></li> |
| <li><a href="#code_completion">Code Completion and Type Analysis </a></li> |
| <li><a href="#goto">Go To Declaration </a></li> |
| <li><a href="#documentation">Documentation</a></li> |
| <li><a href="#embedded_completion">Embedded Completion </a></li> |
| <li><a href="#embedding">Embedding</a></li> |
| <li><a href="#open_type">Open Type </a></li> |
| <li><a href="#jsdoc_support">JSDoc Support </a></li> |
| <li><a href="#basic_file_filtering">Basic File Inclusion Filtering </a></li> |
| <li><a href="#seealso">See Also</a></li> |
| </ul> |
| </div> |
| <h3 class="tutorial">Software Needed for the Tutorial</h3> |
| |
| <p><b>To complete this tutorial, you need the following software and resources.</b></p> |
| |
| <table> |
| <tbody> |
| <tr> |
| <th class="tblheader" scope="col">Software or Resource</th> |
| <th class="tblheader" scope="col">Version Required</th> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td> |
| <td class="tbltd1">7.0, 7.1, 7.2. 7.3</td> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Development Kit (JDK)</a></td> |
| <td class="tbltd1">6 or 7</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h2><a name="basic"></a>Basic Features</h2> |
| |
| <p>In this section we introduce the basic JavaScript editing features of the IDE.</p> |
| |
| <h3>Creating New Files</h3> |
| |
| <p>You can create a new JavaScript file in any project through the New File wizard. |
| Click New->Other to open the wizard. In the wizard, open the Other category |
| and select JavaScript file. A new JavaScript file is created from a template.</p> |
| |
| <p>If you want the JavaScript file to be visible in the Project Editor, create the |
| JavaScript file in an appropriate subfolder of the project, such as src.</p> |
| |
| <p>The default JavaScript template contains only licensing information. To add content |
| to the template, go to Tools -> Templates and open the JavaScript template in |
| the IDE.</p> |
| |
| <h3>Syntax highlighting</h3> |
| |
| <p>The IDE provides true <a href="#semantic_highlighting">semantic highlighting</a> |
| to distinguish methods and variables.</p> |
| |
| <h3>Code Folding</h3> |
| |
| <p>Method code can be folded or expanded. Within the editor, click the |
| <img src="../../../images_www/articles/72/ide/javascript/collapse_node.png" alt="fold"> |
| icon next to a method and it folds. Click the |
| <img src="../../../images_www/articles/72/ide/javascript/expand_node.png" alt="expand"> |
| icon next to a folded method and it expands. Folded code is denoted by an ellipsis box. |
| <img src="../../../images_www/articles/72/ide/javascript/ellipsis_box.png" alt="ellipsis box"> |
| Hold the cursor over the ellipsis box and the IDE displays the collapsed method.</p> |
| |
| <p><br><img border="1" src="../../../images_www/articles/72/ide/javascript/show_collapsed_method.png" alt="collapsed method being shown by holding cursor over ellipsis" title="Collapsed method shown by holding cursor over ellipsis"> |
| |
| <p>You can fold or expand all methods in the View -> Code Folds menu.</p> |
| |
| <h3>Navigation</h3> |
| |
| <p>The IDE's Navigator tab displays the JavaScript file structure. The Navigator |
| recognizes prototype-style class definitions and shows them as classes with methods.</p> |
| |
| <p><br><img border="1" src="../../../images_www/articles/72/ide/javascript/js_navigator.png" alt="navigator tab showing Javascript file structure" title="Navigator tab showing Javascript file structure"> |
| |
| <h3>Background parser</h3> |
| |
| <p>A parser runs in the background and provides detailed error messages.</p> |
| |
| <p><br><img border="1" src="../../../images_www/articles/72/ide/javascript/background_parser.png" alt="background parser showing error" title="Background parser showing error"> |
| |
| <h3>Bracket matching</h3> |
| |
| <p>Brackets automatically close. Typing a ', ", [, ( or { inserts a matching closing |
| symbol. Typing the closing symbol will type through the inserted one. Backspacing |
| the opening symbol removes the matching symbol.</p> |
| |
| <h3>Formatting</h3> |
| |
| <p>Pressing newline indents the caret based on where the next line is expected to be. Pressing a |
| <code>}</code> will outdent the line immediately. Reformatting a selection or the whole buffer |
| reindents the whole file.</p> |
| |
| <h3>JSON support</h3> |
| |
| <p>JSON files are treated as JavaScript. The background parser runs in a special JSON mode |
| where it allows only an object literal expression with no functions etc.</p> |
| |
| <h2><a name="semantic_highlighting"></a>Semantic highlighting</h2> |
| |
| <p>Method declarations are shown in bold (including prototype style method declarations |
| in object literals), global variables are shown in green, unused variables are shown |
| in gray underline.</p> |
| |
| <p><br> |
| <img border="1" src="../../../images_www/articles/72/ide/javascript/highlighting.png" alt="code snippet showing highlighting" title="code snippet showing highlighting"></p> |
| |
| <h2><a name="mark_occurrences"></a>Mark Occurrences</h2> |
| Placing the caret on a symbol highlights other uses of the same variable or call. Furthermore, placing the caret on a function keyword will highlight all the returns from that method (return, throw). This should also happen if you place the caret on a return. <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/mark_occurences.png" border="1" alt="highlighted returns" title="Highlighted returns"><br> |
| <br> |
| <h2><a name="instant_rename"></a>Instant Rename</h2> |
| <p>Press Ctrl-R/Command-R on a local variable and you can rename the symbol synchronously throughout the file. </p> |
| <p><br><img border="1" src="../../../images_www/articles/72/ide/javascript/instant_rename.png" alt="renaming variable synchronously" title="Renaming all instances of variable to 'number' throughout file"> |
| <br> |
| </p> |
| <h2><a name="refactoring"></a>Refactoring</h2> |
| <p>You can find all usages of a variable or operation within a product. After finding these usages, you can rename all occurrences of the variable or operation and refactor throughout the product. Before performing the refactoring, you can preview the changes in a split screen UI.</p> |
| <p><strong>To find and rename all usages of a variable or operation:</strong></p> |
| <ol> |
| <li>Select an occurrance of the variable or operation in the editor.</li> |
| <li>Select Edit->Find Usages (Alt-F7). You have the option of searching the comments as well as the active code. |
| The Usages view opens, showing a tree view of all usages of the variable or operation. |
| <p><br><img src="../../../images_www/articles/72/ide/javascript/find_usages.png" border="1" title="Finding all usages of variable Abstract" alt="finding all usages of selected variable"></p> |
| <li>Select the variable in the editor again and select Refactor -> Rename (Ctrl-R/Command-R). |
| A dialog box opens in which you type the new name.</li> |
| <li>Click Preview. The Refactoring view opens with a tree view of replacements on the left and a split screen of the original and refactored file on the right. <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/refactoring_preview.png" border="1" alt="preview of refactoring of all usages" title="Preview of refactoring of all usages"></p> |
| </li> |
| <li>You can choose not to rename the variable or operation in indiviual places. Deselect the individual renaming in the tree view on the left. |
| <p><br><img border="1" src="../../../images_www/articles/72/ide/javascript/unselected_individual_renaming.png" alt="individual renaming unselected" title="Individual renaming unselected"></p> |
| <li>After review, click Do Refactoring and the IDE refactors all files. |
| </ol> |
| <h2><a name="quickfixes"></a>Quick Fixes and Semantic Checks</h2> |
| The IDE performs many semantic checks on the JavaScript code and offers quick fixes. To display quick fixes, select Source -> Fix Code (Alt-Enter). The semantic checks include: |
| <ul><li>Reassigning a parameter </li> |
| <li>Anonymous function does not always return a value </li> |
| <li>Variable hides argument </li> |
| <li> Code which has no side effects (no calls, no assignments) |
| <p><br><img border="1" src="../../../images_www/articles/72/ide/javascript/nosideeffect.png" alt="code with no calls or assignments" title="Code with no calls or assignments"> </li> |
| <li>An assignment in a conditional (if x = y). This semantic error has several quickfixes associated with it, such as converting to an == expression, and adding double parentheses to turn off the warning. <br> |
| <p><br> <img src="../../../images_www/articles/72/ide/javascript/accidental_assignment.png" alt="menu of quick fixes for an assignment in a conditional" title="Menu of quick fixes for an assignment in a conditional" border="1"> </li> |
| <li> Inconsistent returns from a function (where some return expressions return a value, and some do not) <p><br> |
| <img border="1" src="../../../images_www/articles/72/ide/javascript/inconsistent_return.png" alt="inconsistent returns" title="Inconsistent returns"> |
| </li> |
| </ul> |
| <h2><a name="tasklist"></a>Tasklist</h2> |
| The background parser and the warning quick fixes are integrated with the tasklist. Open the tasklist (Window -> Tasklist) to view errors in any of your files that are associated with JavaScript. Double-click on a task in that list and the editor goes to the relevant line. |
| <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/tasklist.png" alt="tasklist showing quickfixes" title="Tasklist showing quickfixes"></p> |
| <h2><a name="code_completion"></a>Code Completion and Type Analysis</h2> |
| JavaScript code completion gives you a choice of the IDE's built-in JavaScript core classes to insert into your code. For example, you can write |
| <pre> x = "foo"; y = x; y. </pre> |
| <p>and code completion will show you the methods available for JavaScript strings. Code completion works with all the literal types in JavaScript. The type analysis and code completion machinery also knows about prototype style classes (regular functions only) and the new operator for constructing them.</p> |
| <p> NetBeans IDE consults type parameters for function parameters and return types (@type, @param). These types are shown in code completion: in the list, in the documentation, and in parameter hints (Ctrl-P). Return types are also shown in the code completion dialog after the function name, separated by a colon. </p> |
| <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/code_completion.png" border="1" alt="code completion" title="Code completion"> |
| <p> If you mark a method with <tt>@deprecated</tt>, it is struck through in the navigator and in code completion calls to this method. The accompanying deprecated description is shown in a separate section in the code completion documentation with a highlighted background. |
| |
| <p> NetBeans IDE can also determine the return type for many functions. This function is essential for JSQuery support. For example, methods which return true or false have a Boolean return type, those returning literal numbers have a Number return type, and so on. The IDE both infers types and explicitly tracks declared types via comments. The most important implication is that the IDE follows types through calls. If you have code like this:</p> |
| |
| <pre>"foo".big().charCodeAt(50).toExponential(fractionDigits);</pre> |
| |
| <p>NetBeans first sees that <tt>foo</tt> is a String, so it looks in the String class for the <tt>big()</tt> method. The <tt>charCodeAt(50)</tt> function on that String is of the Number type, so if you apply code completion on "to" here, you will see only the methods available on Number. |
| <p><strong>Note: </strong>Looking up return types involves a trip to the index, which can take time, so during type analysis the IDE looks at the clock and after a second or two has elapsed it aborts type computation. This can be relevant for large functions, or slow computers, or fast computers under a heavy work load. |
| <h2><a name="goto"></a>Go To Declaration</h2> |
| Press Ctrl and hold the cursor over a line of code. Left-click the variable name. When the IDE is not sure about the type of your variable (and therefore the target function) it offers you a popup menu of all declarations of the variable across your project: |
| <p><br> |
| <img border="1" src="../../../images_www/articles/72/ide/javascript/goto.png" alt="popup for going to variable declaration" title="Popup for going to variable declaration"><br> |
| <br> |
| <h2><a name="documentation"></a>Documentation</h2> |
| Code completion shows the API documentation for both the core javascript APIs and the DOM APIs. You can also view documentation for your own functions. Ctrl-pointing at calls also shows documentation (as a tooltip). <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/documentation.png" border="1" alt="Documentation tooltip" title="Documentation tooltip"> |
| <br> |
| <h2><a name="embedded_completion"></a>Embedded Completion</h2> |
| Code completion on element ids in the HTML works for the <tt>Prototype.js $("...")</tt> function. To see code completion on element ids, press Ctrl-Space within the quotation marks. For example, if you add <em>variable </em> = $("f<strong>|</strong>") and press Ctrl-Space with the cursor (<strong>|) </strong>immediately after the f, code completion shows all HTML element ids in the document that start with f. |
| <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/embedded_completion.png" alt="element id completion" title="Element id completion" border="1"><br> |
| <br> |
| |
| <h2><a name="embedding"></a>Embedding</h2> |
| JavaScript editing features work for JavaScript embedded in RHTML, HTML, and JSP files. <br> |
| <br> |
| <h2><a name="open_type"></a>Open Type</h2> |
| Press Ctrl-O/Command-O and quickly jump to any of your functions, across files. <p><br> |
| <img src="../../../images_www/articles/72/ide/javascript/find_type.png" alt="go to type dialog" title="Go to type dialog"><br> |
| <br> |
| <h2><a name="jsdoc_support"></a>JSDoc Support</h2> |
| <p>If you annotate a method with <tt>@private</tt>, it shows up in the navigator with a lock icon. If you annotate a function with <tt>@constructor</tt> it is shown as a constructor (and included in code completion after the "new" keyword), and you can use <tt>@class</tt> and <tt>@namespace</tt> to explicitly assign functions to given classes (though the type analyzer can often assign these functions automatically). Functions marked <tt>@ignore</tt> does not show up in code completion but is included in the index and can be used in a <a href="#goto">Go To Declaration</a>. </p> |
| <br> |
| <h2><a name="basic_file_filtering"></a>Basic File Inclusion Filtering</h2> |
| Code completion in HTML only includes code from referenced JavaScript files. Consider a project in which the file <tt>foo.js</tt> defines the function <tt>foo()</tt>, and the file <tt>bar.js</tt> defines the function <tt>bar()</tt>. If the file <tt>hello.html</tt> includes only <tt><script src="bar.js"></script></tt>, only the <tt>bar()</tt> function is shown in code completion for <tt>hello.html</tt>. <br> |
| <p><br> |
| </p> |
| |
| <div class="feedback-box" ><a href="/about/contact_form.html?to=3&subject=Feedback:%20JavaScript%20Editing%20in%20NetBeans%20IDE%206.1">Send Feedback on This Tutorial</a></div> |
| <br style="clear:both;"> |
| <!-- ======================================================================================= --> |
| <h2><a name="seealso"></a>See Also</h2> |
| <p>For more information about using NetBeans IDE to edit non-Java web languages, see the following resources: </p> |
| <ul> |
| <li>The JavaScript, Python, and Groovy sections of the <a href="../../trails/java-ee.html">JavaEE and Java Web Learning Trail</a> </li> |
| <li>The <a href="../../trails/php.html" >PHP Application learning trail</a>.</li> |
| </ul> |
| <p>To send comments and suggestions, get support, and keep informed on the latest |
| developments on the NetBeans IDE Java EE development features, <a href="../../../community/lists/top.html">join |
| the nbj2ee@netbeans.org mailing list</a>.</p> |
| </body> |
| </html> |
