Orion/Documentation/User Guide/Getting started
This tutorial will get you started with using Orion, and provides step by step walk-through of some of the core functionality.
- 1 Getting Orion
- 2 Logging into Orion
- 3 Working with folders and files
- 4 Editing code
- 5 Searching
- 6 Working with git
- 7 Launching your project as a website
- 8 Extending Orion
You have two choices to get started with Orion. The first is to request an account on the public server at OrionHub. You can request an account here and once you have an account login to OrionHub here. The second method to get started is to download a stand alone version of the server. You can find instructions on the Install Orion on Localhost page.
Once you have successfully setup an account either way you can proceed to the next step.
Logging into Orion
When you first attempt to move beyond the welcome page on an Orion server, you'll be prompted for credentials.
Clicking Sign in will take you to the Login page. When running from your own server, you can create an account directly from the login page. If you are accessing a server hosted elsewhere, you may need to ask the server administrator to create an account for you. After a successful login you will be redirected back to the page you came from.
Working with folders and files
In Orion, each user has a virtual root folder where various folders and files can be created. These files are maintained on the Orion server. The Navigator page is used to browse and modify your files.
Creating folders and files
Once you've successfully logged into Orion, go to the Navigator page by clicking Navigator in the banner at the top of any page. This is where your files and folders will be shown. Because you haven't created any files or folders yet, the navigator is initially empty.
To start working with files and folders in Orion, create a folder using the New Folder button in the navigator toolbar:
To navigate the files, you can either expand the folders (using the twisties), or you can click on the folder links to drill into that folder. After you have drilled into a folder, the breadcrumb at the top of the page or the Go Up command in the toolbar allow you to navigate back up the tree.
The banner provides access to common operations in Orion. The main navigation links appear at the top left of the page banner, next to the Orion logo. The right side of the banner provides links to the user profile and an options menu containing settings, help, and other commonly used actions. Underneath, the page header describes the title of the page, the breadcrumb, and the name of the resource being manipulated. On the right of the page header are items that let you quickly find and mark pages that you commonly use. The star icon allows you to mark the current page as a favorite. The search box and Related pages menu allow you to quickly navigate to a new page.
Below the banner, the content of the page appears. Commands that operate on the content itself (such as New File, New Folder in the navigator) are located in the toolbar above the content.
Commands that apply to an individual file or folder are located in an actions menu next to the item in the navigator.
Files and folders may be selected by clicking the checkbox beside their name. Commands that operate on the selected items (such as move, copy, and delete) will appear on the navigator toolbar when a selection has been made.
Importing folders and files
There are many ways to import your files into Orion. You can upload a zip file, import via SFTP, or clone a Git repository.
To import files from your local file system into Orion, you must first zip up the files you wish to import. Choose this zip file in the file selection prompt offered in the import dialog available in the menu next to each folder.
The contents of the zip file will appear in your folder in the navigator.
Exporting folders and files
When you have worked with your code on Orion and are ready to export your work back to your local workstation, navigate to the folder you wish to export and choose the Export as Zip link.
The contents of the folder will be placed in a zip file, and that zip file will be downloaded using your browser's download manager.
You can use the Favorites icon in the page header or the favorites menu item to bookmark a folder or file in your navigator. A link to this folder or file will appear in your favorites list and can be used to navigate quickly to that file or folder.
Favorites are also suggested as move/copy targets.
They also appear in the Find File dialog.
Once you've navigated to the file you want to work with, click on its link to open the Coding page. You'll find that the editor supports the basics (cut/copy/paste, undo/redo) as well as your favorite text-editing features from Eclipse desktop (move up/down, copy up/down, go to line, find, incremental find). For now, most of these commands are accessible only through keyboard shortcuts, using the default key bindings in Eclipse desktop. To see a full list of available keyboard commands in the editor, press Ctrl+Shift+?. (Outside of the editor, you can get the same help on any page by pressing Shift+?.)
The editor will also match brackets when you click next to a bracket, perform auto indention, and provide source-code oriented key bindings for things like toggling comments and adding/removing block comments.
The Orion server is Firebug-savvy, so that recent alpha versions of Firebug, together with a Firebug extension, can invoke the Orion editor to make corrections. For details about this, see the Firebug wiki.
Syntax highlighting of CSS files is also supported, but no outlining support has been provided yet. A CSSLint Plugin can be installed to perform syntax validation on CSS files. As a proof of concept, Orion implements a very simple form of content assist. In Orion, our goal is to provide the plug-in points for things like content assist and outlining, allowing plug-in developers to enhance the functionality. For now, Orion supplies a content assist based on CSS keyword proposals. We hope to integrate existing source code analysis tools as plug-ins to enhance content assist support, outlining, and problem identification for many kinds of files.
A simple HTML outline is provided, based on DOM ids. Syntax highlighting is also available for HTML files.
Extending the editor with a Plug-in
We've also implemented pluggable editor actions which allow third-party developers to extend the behavior of the Orion editor on the fly. For example, we've developed an Orion plug-in based on the JSBeautifier code formatter so that source code can be easily beautified. The plug-in is located at http://mamacdon.github.com/0.2/plugins/beautify/jsbeautify.html . Once the plug-in is installed, reload an Orion editor to see a new command appear beside rest of the editor commands.
Once you are actively using Orion, you'll find that you want to move quickly between different files and folders. There are several ways to go about this. Orion uses Apache Lucene search to provide several different search functions.
Searching for file content
The search box in the Orion navigator will perform a search for content inside your files. The scope of the search depends on what page you are on. In the navigator, the search is scoped to your navigator root.
When a scope cannot be inferred from your current page, a global search is performed.
Results are shown in a Search Results page. From this page you can sort and filter the results, broaden or narrow your search results, and perform a global replace operation.
Finding a file by name
The Find File Named dialog can be opened by pressing Ctrl+Shift+F on your keyboard. This dialog lets you search for a file by name. Simple wildcard characters are supported. Matching files in your favorites list are shown first in the results list.
Searching inside the editor
You can also perform a global search on a highlighted phrase from inside the editor using the Ctrl + H shortcut.
A nice side effect of editing source code in browser pages is being able to use browser mechanisms, such as the history, to quickly find files. If you find yourself working in the same handful of files, opening a new browser tab and typing in the filename will quickly get you there.
Working with git
We intend to provide many different kinds of plug-ins for integrating Orion into open source and proprietary version control systems. Our first example in this area is a UI for working with Git repositories. For files and folders that are managed in a Git repository, you will see a menu for navigating to the Git status of the repository containing your file.
The Git Status page shows you all the files in your git repository that have changed, and allows you to stage, unstage, and commit changes. You can also compare the content of the files.
A side-by-side compare view is also provided.
The Git Status page shows also a list of recent commits on the active branch. You may open the Git Log page by clicking the Complete Log button and see the full list of commits on that branch. Click on a commit in the log page to open the Git Commit page for complete information about that commit.
You can also open the Compare page for each change in the selected commit.
Launching your project as a website
Orion can create "sites" for testing an application developed with Orion as a stand-alone website. Click the Sites link on the Orion toolbar. This takes you to the Sites page, where you can create, edit, delete, or launch web sites for testing. Sites will be launched either as a sub-domain of the Orion server, or at an alternate IP address when running the server locally.
Note that if you are running your own server, and you wish to set up hosting on a sub-domain, a different IP address, or if you're running Mac OS X, you'll have to supply some more information to the Orion server. See Configuring virtual host names for more detail.
You create a site by clicking the Create Site button and supplying a name for your site. Your new site will appear and you should fill in the path mappings for your project. In this example the "MyWork" project has an index.html in the root so just a basic path is required to mount that project at the root. Once done that step you select "Save". You have the option of starting the server from this page or refreshing the list of sites page to see your new site.
Assuming you are at the sites page you can press the "play" button to start the site. The result will be similar to the following image, showing the site running and the URL to get to the self hosted site.
Since our "MyWork" folder has an index.html file in it, we see the contents of that file when we visit the newly created site in our web browser.
At this point, we can do incremental development by using the Orion editor to change the files in our "MyWork" folder, and then simply reloading the site page to see the changes.
Orion allows developers to build plug-ins that add behavior to Orion pages. Let's learn about plug-ins by taking a look at a simple plug-in which extends the navigator.
To see what plug-ins are installed in your Orion system, open the Settings page from the Options menu at the top right of the Orion banner (next to the user name).
The plug-ins page shows what plug-ins you have installed, and allows you to install, reload, or remove plug-ins. You can see that several plug-ins that provide Orion functionality, such as file management, user management, git, jslint, are already installed. Plug-ins extend Orion by implementing new behaviors, or "extensions" to the system.
The orion.navigate.command extension point allows plug-ins to contribute commands that act upon files and folders in the navigator. These commands will be placed in the actions menu or selection menus. Each contributed command can specify how many and what types of files it can work with. Contributed commands will appear in the navigator item menus.
A sample plug-in that demonstrates the different kinds of commands you can contribute is located at http://orionhub.org/plugins/sampleCommandsPlugin.html. On the plug-ins page, you can click on "Install" and paste or type this URL into the text area and press Submit. When you reload the navigator page, you will see new commands in the item action menu.
You will also see new commands in the selection menu in the toolbar.