What the heck does this code do? Find out before you refactor

A common problem for developers is being able to work effectively with and understand large code bases. This problem can affect everyone on a team, whether you’re new or experienced. It’s hard to know every line, and everyone needs to find their way around the code base.

Better not refactor!

Refactoring JavaScript code can be intimidating, so many developers avoid it. Over time, they write code to fix bugs and implement features, and the code base grows. As it grows, it becomes harder to maintain. At the same time, team members with tribal knowledge leave and others come on board. The technical debt grows and grows.

Orion to the rescue

Imagine that you’re browsing a code base and you see a function call. You might ask yourself:

“Where is this function defined? Are there multiple declarations? Who else uses this thing? If I change the implementation, who is affected?”

Fortunately, Orion has a new feature to help in this scenario. It’s called “References.” To use it, click a code element, such as a function call, and select an option from the References menu:

Web IDE with References menu selected

A window opens to show each match, categorized and weighted:

References window, showing categories


In the window, you can browse by category to focus on the most important matches first. For example, “Function Declarations” and “Function Calls” are important and interesting categories. If a category doesn’t contain any matches, the category is not shown. All matches are categorized, including those that occur in comments and strings. In JavaScript, strings can be evaluated (don’t do this) and JSDoc contains valuable information.


Orion includes a type-inference engine that can determine the type and scope of a function or variable. This information is used to weigh the results.

Here is a handy legend:

  • Green check mark: Perfect match
  • Blue question mark (?): Potential match
  • Red (x): Not a match

Go ahead and refactor

It’s no accident that the user interface (UI) for the References feature looks like the UI for the Global Search feature. When you’re wondering how a function is used, you need to see the calls and declarations, but you also need more information. JavaScript is a dynamic language where strings can be evaluated and functions can be saved in properties and then called or even passed around as arguments. A function can be used in meta programming; you need to be aware of that when you refactor.

You can refactor the references that you found to the main() function to be main2() by clicking Preview:

References window, showing replacements

A simple rename consists of these actions:

  1. Finding all of the references
  2. Inspecting each reference by category, noting any checks and question marks
  3. Selecting or clearing the replacement check box
  4. Clicking Replace

Of course, refactoring is more than renaming, but the first step is to find and categorize each match.


You can use the new References feature in Orion to understand how a variable or function is being used. Understanding the code is the first necessary step towards refactoring.


Posted in General | Comments Off on What the heck does this code do? Find out before you refactor

New Support for ARIA Content Assist in Orion

Orion’s HTML Content Assist now supports WAI-ARIA attributes and their values.

For example, when typing attributes into the start tag of a div, you can type Ctrl+Space to pop up a list of all attributes that div supports, including ARIA attributes. Use the up or down arrow keys or type the initial character(s) of an attribute name to select it in the list and read its documentation. Type Enter to have the selected attribute inserted into your file at the caret location.

The screen snapshot below shows the aria-atomic attribute selected in the pop-up list of proposals, with its documentation from the W3 WAI-ARIA 1.0 Specification alongside.

Content Assist popup list showing ARIA attributes, with aria-atomic selected

If you resize the proposals list, you can see all of the ARIA attributes that the current HTML element supports (div supports all 36 of the ARIA 1.0 attributes). The snapshot below shows the full list with role selected. The documentation for the role attribute lists 61 possible values!

Content assist proposal list with role selected

Typing the initial characters of an attribute filters the list to make it easier to scan. The typed characters are also inserted into the file. The screen snapshot below shows only attributes that begin with “aria”.

Content assist proposal list showing only aria attributes, with aria-activedescendant selected

If you type the first few characters of an attribute name before typing Ctrl+Space, the list will be filtered when it is opened. If enough characters are typed to uniquely identify an attribute, then the list is not opened; instead, the completed attribute is inserted into the file immediately. Attributes are assigned the empty string when inserted, and the caret is placed between the quotes of the empty string, which is conveniently where it needs to be for you to type the attribute’s value. For example, role is the only attribute that starts with ‘r’, and it will be inserted as role="".

Typing r and invoking content assist inserts role="" into the text

If you need help remembering an attribute’s possible values, there’s Content Assist for that, too. Type Ctrl+Space while the caret is between the attribute value’s quotes, and a list of value choices will pop up. Alternatively, start typing a character or two of the value you want, and type Ctrl+Space to get a reduced list. This comes in handy with attributes like role, where typing a ‘t’ will reduce the list to “only” 10 values instead of 61!

Content assist proposal list showing role attribute values starting with 't', with tab selected

In the same way that attribute Content Assist provides documentation for the selected attribute, value Content Assist provides documentation for the selected value, complete with a link to the value’s description in the WAI-ARIA 1.0 spec.

Orion is an “Authoring Tool” according to the definition in the W3 ATAG Specification:

Authoring Tool: Any web-based or non-web-based application(s) that can be used by authors (alone or collaboratively) to create or modify web content for use by other people (other authors or end users).

One of the goals of an Authoring Tool is to:

…ensure that all authors are enabled, supported, and guided by the authoring tools that they use toward producing accessible web content (WCAG).

Orion’s new ARIA Content Assist is a step toward achieving that goal.

Posted in General | Comments Off on New Support for ARIA Content Assist in Orion

New Graphical Git Log on Orion Git Page

Orion now supports a graphical view of commit history, similar to the git log –graph command on the Git command line.

On the Orion Git page, you will notice this small icon has been added into the header of the commit list:


And as the tooltip says, it draws the graph. Toggle it, and you will see this graph merged beautifully into the original commit history container.


It also draws the history graph for outgoing and incoming items, based on their branch commit history:


And the drawing stretches with the commit information container.


Once you click for more commits, it will keep drawing the graph from its last seen state:




Posted in New & Noteworthy | Comments Off on New Graphical Git Log on Orion Git Page

New Support for GitHub Pull Requests in Orion

Orion now supports viewing and working with GitHub pull requests. Once a repository is cloned from a GitHub project, the associated pull requests can be viewed from the references dropdown menu under the expandable pull requests section.

Once the pull request section is opened under the references dropdown, you will see the pull requests associated with the repository. The source and destination branches of the pull request are shown, along with the title and request number.

There are two commands available for working with pull requests: checkout pull request and a link to the GitHub page.


The checkout command lets the user checkout the pull request like a normal branch and creates a new remote branch for the pull request, and can be viewed like any other branch in Orion. Once checked out, it will be in the state indicated by the references shown as the title of the pull request.



The link command opens a new tab in the browser for the GitHub page associated with the pull request, where the owner of the repository can choose to merge or reject the pull request.

Posted in New & Noteworthy | Comments Off on New Support for GitHub Pull Requests in Orion

Language Tooling in 10.0 – Moving at the furious pace of web development

The 10.0 release of Orion is now out in the wild.  A ton of work has gone into language tools since the last official release, but I hope you haven’t been waiting over 4 months to check it out.  This is a DevOps world, with fixes and improvements being delivered continuously.  Sign up for OrionHub or IBM Bluemix DevOps Services and use the latest and greatest in language tooling on the web.

Meshing HTML and JavaScript tooling

In the last release, our focus was improving our JavaScript tooling to be best in class, matching or exceeding what is being done on a desktop IDE. Orion provides a strong set of tools that could go beyond a single script file and understand your Node.js or RequireJS dependency graph.  For 10.0 we have extended this cross-file support for HTML pages.

If you add <script> blocks to your HTML you will have access to all of our excellent JS tooling.  Content assist, syntax highlighting, navigation hovers, ESDoc support, occurrences, etc.  This tooling works in embedded scripts as well as onLoad, onClick and other DOM event attributes.



We also enabled our CSS tooling for embedded CSS blocks.


The biggest change here is having tooling that is aware of your other scripts.  If you have a script block that points to an separate JS file, we will lookup the contents of that script.  You can navigate in-between files using tooltip hovers as well as Open Declaration and Open Implementation (more on this later).  Content assist proposals will list variables and functions you declared in other files, neatly organized by their source.



What if you have a project setup where you reference multiple files without a definitive <script src=…> link?  While not out for the 10.0 release, going forward we will allow you to customize your project setup.  Give you control over what scripts and pages should be connected to the tooling.  Currently this will be implemented using .tern-project files which can specify files to load or avoid in the tooling.

There are massive improvements to the tooling for writing HTML too.  The content assist got a complete rewrite and now the proposals you see are limited to what is valid in HTML 5.  There are proposals for attributes as well as element tags.  The tooltips for these proposals include descriptions of their purpose, annotations if they have been deprecated in the ongoing HTML 5 spec, and links for more information.  Moving forward we are investigating htmllint as a validator and adding accessibility tooling as well.



Innovative JS

Many of the Orion developers have a background in Java development using Eclipse.  Developers in Eclipse have many features at their fingertips for navigation and refactoring.  These operations are key to speeding up development, but the nature of JavaScript makes it difficult to provide them.

Open Declaration (F3) and Open Implementation (Ctrl-F3) are now available in the Orion editor.  Open Declaration will jump you to where an expression was defined, anywhere in the dependency graph.  No need to explore the file system or do a global text search to figure out who defines the function you are using.  Open Implementation operates similarly but goes an extra step, following the right hand side of assignment expressions until a final ‘code’ stopping point.  Rather than jumping you to a require() call or the define statement of a RequireJS module, Open Implementation will take you to the implementation of the function.


Currently Orion allows you to perform a rename command.  This will find all references to the selected type and rename them.  This is much faster than Search and Replace.


Right now this is limited to a single file, but there is a huge new feature coming shortly that will change this!


The Orion language tools have support for ES6 constructs.


No single blog post is going to cover everything we have done for 10.0 and new functionality is getting released daily.  Here are a few other ways we are improving the user experience:

  • Speeding up common operations: New quick fixes are available, there is a context menu for the editor, and shortcuts were added to editor settings.
  • Let the user know what it going on: There is progress reporting as the tooling starts or as longer operations run and more detailed explanations are shown when a command doesn’t work.
  • Fixing bugs: If you found a case where the tools just didn’t work, try it again.  We are constantly making fixes and we updated to the newest versions of the libraries we use to pick up all of their hard work (escope 2.0.4 Tern 0.10.0 then 0.12.0 Acorn 2.0.4).  The language tooling has over 1800 unit tests to check for regressions as we deliver new features.
Posted in New & Noteworthy | Comments Off on Language Tooling in 10.0 – Moving at the furious pace of web development

Announcing Orion 10.0

The tenth release of Orion was made available this week. You can check it out now on OrionHub, or download the server to run your own instance. In numbers, this release contains 255 fixes and enhancements, in 650 commits, by 33 unique authors. Thanks to all contributors for your work on this release!

This release contains significant enhancements to both JavaScript and HTML tooling. In JavaScript tooling, there is a new Open Implementation command that will traverse across references to find the declaration of a function, including traversal across source files. HTML tooling now includes content assist for the full set of both HTML tags and attributes, including hover documentation to help you make sure you are using the right attributes. Stay tuned for a future blog post going into more detail on the language tooling improvements in Orion 10.

Another major new feature in Orion 10 is support for working with Git sub-modules. Read our detailed blog post and user guide for more details.

The Orion user interface has had a number of nice improvements, outlined in a recent blog by Eric Moffat. There has also been good progress on the Node implementation of Orion, which has gained support for global search, as well as early support for working with Git.

Enjoy the release!

Posted in Announcements, New & Noteworthy | 1 Comment

Implementation Details – Git Submodule Support

Here are some implementation details about the Git Submodule support which is now available in the Orion Web IDE. If you have not already read about the features, please check the Git Submodule Support post. A Detailed User Guide is also available.

Remove submodule

There are two ways to entirely remove a submodule from its parent repository. The old way involves manually changing all the configuration files and removing the actual submodule directory. It can also be done by using the deinit command, available since git 1.8.3 (April 22, 2013).

Since JGit does not yet support the deinit command, we have to use the previous method to do the job. Here is a list of operations the remove command will do for you:

  1. Remove the corresponding submodule entry in the .gitmodules file, if there is no more entries left, remove the file itself.
  2. Remove the corresponding section in the .git/config file. It will look like this.
  3. Run git rm –cached path/to/submodule.
  4. Delete the .git/modules/name_of_submodule folder.
    rm -rf .git/modules/name_of_ submodule
  5. Use git rm on the submodule directory, so it removes the submodule’s work tree from that of the parent repository and the gitlink from the index.
    rm -rf path/to/submodule

A lengthy but standard procedure. If it is different from what you are used to do for submodule removal, you might have to tweak the configurations yourself afterwards.

Regretting removing a submodule?

The Orion Git page has a convenient way of undoing changes. What it is actually doing is calling git checkout on specific paths to undo the changes in those paths. It works in most cases, but, it might work differently from what you expect it to do.

In Orion the Git component, submodules are treated similarly as in Git command line, this means that the parent repository will not have any knowledge of what is going on inside the submodule, and when it tries to remove a submodule, it will simply remove the whole folder without checking the contents inside it. Because of this, when undoing the removal, the content of the folder can never be recovered as it is never recorded in the first place.

Undoing the removal at this point will only bring back the empty folder and the config changes, the submodule will be treated as an uninitialized submodule and you need to init and update it to fetch the content from the remote URL.

Add submodule

Adding a submodule is basically the same as git submodule add command in the command line, where you can specify the path of which the submodule is going to be contained.

Also it has the same problem as in the command line, that is, when you clone, sync or update, you have the –recursive flag to make the operation affect submodules at all levels. But add submodule command does not have that, it only initializes the first level submodule for you. Consider this scenario:

  1. Create repository “subrepo” and add submodule “submodule” into it
  2. Create repository “mainrepo” and add submodule “subrepo” into it

Now in the “mainrepo”, “subrepo” will be initialized, but “submodule” will just be an empty folder inside of “subrepo” since it is not initialized.

You will have to update the nested submodules by yourself.

Update submodule

To make the user’s life easier, update and init command for submodule are combined into one single command. When you invoke the update command, it runs the equivalent of git submodule update –init for you.

If you have used submodules intensively in the past, you would probably be using git submodule update –init –recursive a lot. But since JGit does not have native recursive flag support, we consider the recursive flag not essential and we do not have it for update at this point.

Until nested repositories containing hundreds of layers of submodules becomes common, if you have nested submodules, you will be to update them one layer at a time.

Sync submodule

Sync is the kind of operation that has to be there but nobody really uses it. It mimics git submodule sync command, and due to the reason mentioned above, sync does not have recursive flag either.

Undoing Changes

Submodules are pretty messy to work with if you do not follow a strict workflow. If you have been using submodules, I would assume that there were times you hope that you did not press update, since it nukes all the changes you have in the submodules, and the name of the command does not suggest the nuclear nature of it at all.

Unfortunately as I have mentioned the parent repository has no ideas about the content of the submodules, and there is no undoing after it is done.

Posted in General, Integrations | 1 Comment

Git Submodule Support

The upcoming Orion 10 release includes support for Git submodules, providing features very similar to the ones offered in the Git command line. Git command line logic was used with the JGit plugin to integrate the features outlined below.

Adding a submodule

Submodule support allows the addition of new submodules to a repository. This can be a plugin you are using from a third party or any repository you would like to include in the project. We have added an add submodule button to the repository dropdown list. This will trigger a tooltip to provide the specified clone URL of the submodule you wish to add.


It is basically the same as git add submodule command in the command line, where you can specify the path to the submodule.

The cloned submodule, will appear nested in the tree view of the repository, present in both the editor and repository dropdown list. A .gitmodules file will also be generated in the repository.

Initializing a submodule

When cloning a submodule with nested submodules, the nested submodule’s contents will not be cloned and shown as an unknown repository in the repository dropdown. This is because it is uninitialized. Similarly to Git, submodules nested further than the first order will not be initialized.

Two new buttons, sync and update, have also been added to the repository dropdown menu, at the occurrence of a repository containing submodules. The sync and update functionality initializes and updates immediate submodules.

Commit and Push Changes

If a change is made in a submodule, the change needs to be pushed to the submodule and all higher level repositories containing it.

To push a change, a branch needs to be checked out, because the newly cloned submodule will be in Detached Head state, pointing to the latest commit. The changes can then be committed and pushed usual. These changes will now be reflected in the immediate parent, and can be committed and pushed. Similarly, for any other parents in the hierarchy.

**Note: There may be working directory changes reflected in parents other than the immediate parent of the changed submodule, but these cannot be committed until the changes are committed bottom up from the submodule.

**Note: You can also add submodules to submodules using the add submodule button for the submodule you wish to be the parent repository and commit the changes, as explained above.

Removing a submodule

There is now a trash icon beside every submodule indicating delete submodule.


Deleting a submodule will delete all content in the submodule as well as nested submodule repositories from the project.

Cloning a project with submodules

When cloning repositories, there is now a new feature in the more options popup, for recursive cloning of submodules. By default, this is set to true and will recursively clone all nested submodules. If unchecked, the repository will be cloned with its immediate submodules uninitialized. In the editor view, this will appear as empty folders. If you later want to clone the contents of the submodules, then they can be initialized with sync and update.


For more information, visit the Detailed User Guide or Implementation Details.

Posted in Announcements, New & Noteworthy | 1 Comment

Orion 9.0 Code Edit Widget With Language Tooling

Orion 9.0 was just announced with greatly enhanced javascript language tooling features. In addition to using Orionhub.org as an IDE, developers have been demanding that they can embed the Orion editor into their web pages with all the features that the Orion editor offers. Now Orion 9.0 comes with a new widget called “Code Edit”.

Consuming the Code Edit widget is very simple. You just need to go to the Orion 9.0 download page and download the widget build named built-codeEdit.zip.


After downloading the build you can host the unzipped files into your web server and start to consume it in your web page. The Code edit wiki page describes how to consume it but as a quick start you can use the run-able html example to launch it. It only takes you several minutes to do so. We’ve also hosted a demo page where you can try the widget right now!


While Orion 9.0 announcement describes some new tooling features in 9.0, there are existing features like syntax highlighting, problems validation, quick fixes, etc. You can find a quick guide from the feature list on the demo page.

The demo page only demos a javascript file but the widget supports more languages such as css, html and most of the web languages. Refer to the list of supported file types for syntax highlighting. You can also theme the editor’s syntax highlighting and other visual parts. The editor theming  describes more on these.

As the Code Edit widget is part of the Orion build, we are actively adding features and doing bug fixes for the widget. Stay tuned with the post 9.0 stable builds!

As part of the future plan, we will allow users to inject their own plugins to the widget. For example, this will allow users to add new language syntax highlighting, add more editor commands, add their own file systems for multiple file reference on language tooling, etc.


Posted in General | 1 Comment

Announcing Orion 9.0

With the continuous delivery model of the Orion cloud IDE you may have already tried many of the awesome new features in the latest release.  The official release of Orion 9.0 provides an excellent time to review and promote what the project has been up to.

Try them now at Orionhub.org!

JavaScript front and center

JavaScript tooling was the focus throughout the release.  The plugin back-end was restructured to load faster and run in a web worker.  The engine powering content assist and hover information was replaced with Tern, a code analysis tool running on our existing Esprima based parser.  The front end client got expanded capabilities in tool-tips, context menus, split editors and commands to provide access to all the great new functionality.

Tern in Orion

The single largest change made this release was adding a Tern server for code analysis.  As soon as you start editing code we are feeding Tern information about what you are working on.  Beyond the file you are editing we follow dependencies and add their information to Tern as well.  This includes Node libraries linked through require() calls, AMD modules linked via define() calls and embedded scripts in HTML files.  Further to that, Orion includes Tern readable indexes containing type information for common libraries including ECMAScript, Node.js, Redis, MySQL and others.

Tern performs code analysis on all of the scripts available and returns highly accurate and context specific content assist proposals (Ctrl+Space to activate).  We have a large library of code templates as well to help you code faster.


Tern also returns us in-depth descriptions for the types and functions you use.  We deliver this information in the form of tool-tips (hover with the mouse or press F2).  Use tool-tips to help understand the arguments in your API calls.  In many cases we provide a link to the MDN spec where you can continue to learn more.


Take your IDE a step further by navigating the tree of dependencies.  You can already hover over require/define dependencies to navigate to those files.  Now you can Jump to Declaration (F3 or the Tools menu) from anywhere in your code to immediately navigate to the declaraction of a function or variable.  This includes jumping to other scripts.

Find yourself constantly navigating between files?  Use the split editor view (drop down menu at the top right) to display multiple files on the same page in whatever layout works for you.


Use the information Tern has collected to perform some refactoring.  The Rename Element command (Shift+Alt+R or the Tools menu) will let you choose a new name and have Tern figure out all the places needing changes.



More to discover

Of course many more enhancements and bug fixes have gone into the release.  New versions of our third party libraries (ESLint 0.15.1, ESTraverse 1.9.0, Esprima 2.0) are included.  New validation rules no-shadow-global, no-proto, no-undef-init, no-with and missing-nls along with new quickfixes have been added.  The editor tool-tips have much smarter placement and sizing logic while allowing scrolling and resizing for large JSDoc entries.  The JavaScript Validation settings are now split up into categories for easier browsing.  You can see what Tern libraries are installed on a settings page as well.  Nearly 200 bug reports were fixed relating to the language tooling.

Don’t wait, use Orion to code, deploy and run in the cloud.

Posted in Announcements, New & Noteworthy | Comments Off on Announcing Orion 9.0