Difference between revisions of "Orion/Documentation/User Guide/Getting started"

From Eclipsepedia

Jump to: navigation, search
(Working with git)
(45 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This tutorial will get you started with using Orion, and provides step by step walk-through of some of the core functionality.
+
This tutorial will get you started with using Orion, and provides a step by step walk-through of some of the core functionality.
 +
 
 +
==Getting Orion==
 +
You have two choices to get started with Orion.  The first is to create an account on the public server at OrionHub. To do this, visit [http://orionhub.org/ OrionHub], click '''Create a new account''' and enter your information. An email will be sent to confirm your address. Once confirmed, return to [http://orionhub.org/ OrionHub] and log in.
 +
 
 +
The second method to get started is to download a standalone version of the server. For instructions, see [http://wiki.eclipse.org/Orion/How_Tos/Install_Orion_on_Localhost Install Orion on Localhost].
 +
 
 +
Once you have successfully set up an account, you can proceed to the next step.
  
 
==Logging into Orion==
 
==Logging into Orion==
When you first attempt to move beyond the welcome page on an Orion server, you'll be prompted for credentials.
+
When you attempt to access a page that requires logging in, you'll be redirected to the Login Page and prompted for credentials.
 +
 
 +
[[Image:Orion-0-3-login.png|Login Page]]
 +
 
 +
On your first visit to the login page, you can sign in using either of these ways:
 +
 
 +
* [[Image:Orion-login.png|left|Sign in with existing Orion account]] Sign in using the username and password of your Orion account.<br clear="left">
 +
* [[Image:Orion-login-Persona.png|Sign in with Mozilla Persona]] Sign in using a [https://persona.org Mozilla Persona]. To do this, your Persona email address must be the same as the email address you chose when creating your Orion account. You can sign up for a Persona [https://persona.org here].<br clear="left">
 +
 
 +
Later on, after you've logged into Orion and [[Orion/Documentation/User_Guide/Reference/Settings_page|linked a Google account]] to your Orion account, you'll be able to sign in with Google:
 +
* [[Image:Orion-login-google.png|Sign in with associated Google account]] Sign in with a linked Google account. To link a Google account, use Orion's [[Orion/Documentation/User_Guide/Reference/Settings_page|Settings page]].
  
[[Image:Orion-0-3-login.png]]
+
If you are accessing a server other than OrionHub or localhost, the server administrator may have disallowed you from creating an account on the Login Page. In that case, you'll have to ask the server administrator to create one for you.
  
Clicking <b>Sign in</b> will take you to the [[Orion/Documentation/User_Guide/Reference/Login_page|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.
+
After a successful login, you will be redirected back to the page you came from.
  
 
==Working with folders and files ==
 
==Working with folders and files ==
Line 12: Line 29:
  
 
===Creating folders and files===
 
===Creating folders and files===
Once you've successfully logged into Orion, go to the [[Orion/Documentation/User_Guide/Reference/Navigator_page|Navigator page]] by clicking <b>Navigator</b> 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.
+
Once you've successfully logged into Orion, make sure you're at the [[Orion/Documentation/User_Guide/Reference/Navigator_page|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.
  
[[Image:Orion-navinitial.png]]
+
[[Image:Orion-navinitial.png|Orion Initial Navigator State]]
  
 
<!-- For demo purposes, we currently populate every user's root folder with two folders that contain some of the Orion client source code.  Once you've successfully logged into Orion, you should see two folders: -->
 
<!-- For demo purposes, we currently populate every user's root folder with two folders that contain some of the Orion client source code.  Once you've successfully logged into Orion, you should see two folders: -->
To start working with files and folders in Orion, create a folder using the '''New Folder''' button on the left side of the dark bar in the banner:
+
To start working with files and folders in Orion, create a folder using the '''New > Folder''' action in the navigator toolbar:
  
[[Image:Orion-navbreadcommands.png]]
+
[[Image:Orion-navbreadcommands.png|Navigator Toolbar]]
  
To navigate the files, you can either expand the folders (using the triangles), 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 allows you to navigate back up the tree.
+
To navigate the files, you can either expand the folders (using the &#9658; twisties), or you can click on the folder's name to drill into that folder. After you have drilled into a folder, you can use the breadcrumb at the top of the page, or your browser's '''Back''' button, or a keyboard command (Alt+&#8593;) to navigate back up the tree.
  
[[Image:Orion-navbreadcrumb.png]]
+
[[Image:Orion-navbreadcrumb.png|Navigator Breadcrumbs]]
  
 
=== Using the common banner ===
 
=== Using the common banner ===
  
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 <tt>Related pages</tt> menu allow you to quickly navigate to a new page.
+
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 a '''user 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 folder (or in general, the ''resource'' you're currently viewing) as a favorite.  The '''search box''' allows you to quickly search the contents of the current folder. Next to the search box is the '''search options''' menu, which lets you set advanced options such as regular expression search and access saved searches. The '''Related pages''' menu lets you quickly navigate to another Orion page relevant to the folder you're viewing (for example, if you're viewing a folder inside a Git repository, you can navigate straight to the Git Log page for the folder).
  
Below the banner, the content of the page appears. Commands that operate on the content itself (such as <tt>New File</tt>, <tt>New Folder</tt> in the navigator) are located in the toolbar above the content.
+
Below the banner, the content of the page appears. The page toolbar contains commands. The '''New File''' and '''New Folder''' act on the current folder (unless you've made a selection in the file tree).
  
[[Image:Orion-topbanner.png]]
+
[[Image:Orion-topbanner.png|Common Banner]]
  
Commands that apply to an individual file or folder are located in an actions menu next to the item in the navigator.
+
Commands that apply to an individual file or folder are located in the '''Actions''' menu next to the item in the navigator.
  
[[Image:Orion-navactions.png]]
+
[[Image:Orion-navactions.png|Navigator actions]]
  
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.
+
Files and folders may be selected by clicking their row, or by using the Ctrl and arrow keys on the keyboard. Once a selection has been made, commands that operate on the selected items (such as move, copy, and delete) will be available in the Actions menu.
  
 
===Importing folders and files===
 
===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.
 
There are many ways to import your files into Orion. You can upload a zip file, import via SFTP, or clone a Git repository.
  
[[Image:Orion-navimport.png]]
+
[[Image:Orion-navimport.png|Import files]]
  
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.
+
To import files from your local file system into Orion, select one or more files on your computer and drag them on to the Import dialog:
  
[[Image:Orion-navimportdialog.png]]
+
[[Image:Orion-navimportdialog.png|Import from zip dialog]]
  
The contents of the zip file will appear in your folder in the navigator.  (If you are working on the Orion demo server, you will also notice a folder associated with git inside your new folder.  To configure this feature on your own localhost version of Orion, see the [[Orion/Server admin guide#Automatic_git_projects|server administration guide]].) 
+
The dialog only accepts files, not folders, so to import a folder, you'll have to zip it first. Then drag the .zip file into the dialog, ensuring that the '''Unzip *.zip files''' option is checked, and the contents of the zip file will appear in your folder in the navigator, like this:
  
[[Image:Orion-navimportcontent.png]]
+
<!-- (If you are working on the Orion demo server, you will also notice a folder associated with git inside your new folder.  To configure this feature on your own localhost version of Orion, see the [[Orion/Server admin guide#Automatic_git_projects|server administration guide]].)  -->
 +
 
 +
[[Image:Orion-navimportcontent.png|Imported zip contents]]
  
 
===Exporting folders and files===
 
===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.
 
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.
  
[[Image:Orion-navexport.png]]
+
[[Image:Orion-navexport.png|Export as zip]]
 +
 
 +
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.
  
 
===Creating favorites===
 
===Creating favorites===
Line 61: Line 82:
 
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.  
 
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.  
  
[[Image:Orion-favorites.png]]
+
[[Image:Orion-favorites.png|Favorites]]
  
 
Favorites are also suggested as move/copy targets.
 
Favorites are also suggested as move/copy targets.
  
[[Image:Orion-copymove.png]]
+
[[Image:Orion-copymove.png|Favorites as copy / move targets]]
  
 
They also appear in the '''Find File''' dialog.
 
They also appear in the '''Find File''' dialog.
  
[[Image:Orion-findfile.png]]
+
[[Image:Orion-findfile.png|Favorites in find file]]
 
+
===Extending the navigator===
+
We've implemented an extension point that allows a plug-in to add commands to the navigator's toolbar and local item actions.  To see what plug-ins are installed in your Orion system, open the [[Orion/Documentation/User_Guide/Reference/Settings_page|Settings page]] from the <b>Options</b> menu.
+
 
+
[[Image:Orion-pluginregistry.png]]
+
 
+
The registry shows what plug-ins you have installed, and allows you to add plug-ins by typing the URL of a plug-in in the text box.  You can see that the several plug-ins that provide Orion functionality, such as file management, user management, git, jslint, are already installed.  Plug-ins provide different kinds of new behaviors, or "extensions", to the system. 
+
 
+
The [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.navigate.command|orion.navigate.command]] extension point allows plug-ins to contribute commands to the navigator. 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.  You can paste or type this URL into the registry page and press the '''Install''' button.  When you reload the navigator page, you will see new commands in the item and toolbar menus.
+
 
+
[[Image:Orion-sampleCommands.png]]
+
 
+
See [https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.core/web/plugins/sampleCommandsPlugin.html sampleCommandsPlugin.html] for the source code.
+
  
 
==Editing code==
 
==Editing code==
Once you've navigated to the file you want to work with, click on its link to open the [[Orion/Documentation/User_Guide/Reference/Coding_page|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+L'''. (Outside of the editor, you can get the same help on any page by pressing '''Shift+?'''.)
+
Once you've navigated to the file you want to work with, click on its link to open the [[Orion/Documentation/User_Guide/Reference/Coding_page|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 '''Alt+Shift+?''' (Ctrl+Shift+? on Mac OS). Outside of the editor, you can get the same help on any page by pressing '''Shift+?'''.
  
 
===JavaScript development===
 
===JavaScript development===
If you are working with JavaScript (a *.js file), the editor will syntax highlight your code.  You will also see an outline of the functions in your JavaScript, as well as markers for problem areas in your code.  Integration with existing web tools is an important goal in Orion, so we have implemented a plug-in that runs [http://www.jslint.com/ JSLint] on JavaScript files in order to produce the outline and problem markers.  The familiar Eclipse problem UI is used to display the problems in the editor. You'll see problem markers by each line of code in the left hand ruler, red underlining under the problematic text, and overview problem markers on the right side. These last markers allow you to navigate quickly to a problem in a part of the file that's not currently displayed.  
+
If you are working with JavaScript (a *.js file), the editor will syntax highlight your code.  You will also see an outline of the functions in your JavaScript, as well as markers for problem areas in your code.  Integration with existing web tools is an important goal in Orion, so we have implemented a plug-in that runs [http://www.jslint.com/ JSLint] on JavaScript files in order to produce the outline and problem markers.  The familiar Eclipse problem UI is used to display the problems in the editor. You'll see problem markers beside each offending line of code in the left-hand ruler, red underlining under the problematic text, and overview problem markers to the right-hand side of the editor. These last markers allow you to navigate quickly to a problem in a part of the file that's not currently displayed.
  
 
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 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.
  
Orion allows multiple kinds of code outline views to be plugged in. For example you can install the [http://johnjbarton.github.com/outliner/nonymousPlugin.html nonymous plugin] that provides a hierarchical JavaScript outline view. If you have multiple outline views installed, a drop down menu at the top of the outline pane allows you to switch between them.
+
Orion allows multiple kinds of code outline views to be plugged in. For example you can install the [http://johnjbarton.github.com/outliner/nonymousPlugin.html nonymous plugin] that provides a hierarchical JavaScript outline view and an advanced way of naming anonymous JavaScript functions. If you have multiple outline views installed, a drop-down menu at the top of the outline pane allows you to switch between them.
  
[[Image:Orion-editjs.png]]
+
[[Image:Orion-editjs.png|Editing JavaScript screenshot]]
  
 
===Firebug Integration===
 
===Firebug Integration===
Line 102: Line 108:
  
 
===CSS development===
 
===CSS development===
Syntax highlighting of CSS files is also supported, but no outlining support has been provided yet. A [http://mamacdon.github.com/0.3/plugins/csslint/csslintPlugin.html 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.   
+
Syntax highlighting of CSS files is also supported. Orion uses CSSLint to validate and check for problems in CSS files. An outline view is also provided, which shows the list of rules in your file and allows you to quickly navigate between them. As a proof of concept, Orion provides 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.   
  
[[Image:Orion-editcss.png]]
+
[[Image:Orion-editcss.png|Editing CSS screenshot]]
  
 
===HTML development===
 
===HTML development===
 
A simple HTML outline is provided, based on DOM ids.  Syntax highlighting is also available for HTML files.
 
A simple HTML outline is provided, based on DOM ids.  Syntax highlighting is also available for HTML files.
  
[[Image:Orion-edithtml.png]]
+
[[Image:Orion-edithtml.png|Editing HTML screenshot]]
  
 
===Java development===
 
===Java development===
Line 115: Line 121:
  
 
===Extending the editor with a Plug-in===
 
===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 [http://jsbeautifier.org 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.  
+
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 [http://jsbeautifier.org the JSBeautifier code formatter] so that source code can be easily beautified. The plug-in is located at http://mamacdon.github.com/0.5/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.  
  
[[Image:Orion-editorplugin.png]]
+
[[Image:Orion-editorplugin.png|Plugins can contribute commands to the editor]]
  
==Search support==
+
==Searching==
Once you are actively using Orion, you'll find that you want to move quickly between different resources.  There are several ways to go about this.  We've integrated Apache Lucene search with the Orion server and exposed it in the Orion client in several ways.
+
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.
===Global search===
+
The search box in the Orion navigator will perform a global search on everything in your user workspace. Results are shown in a [[Orion/Documentation/User_Guide/Reference/Search_Results_page|Search Results page]]. From this page you can sort and filter the results, and initiate a global replace operation.
+
  
[[Image:Orion-globalsearch.png]]
+
===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. 
  
 +
[[Image:Orion-scopedsearchbox.png|Scoped search box]]
 +
 +
When a scope cannot be inferred from your current page, a global search is performed.
 +
 +
Results are shown in a [[Orion/Documentation/User_Guide/Reference/Search_Results_page|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.
 +
 +
[[Image:Orion-globalsearch.png|Search results page]]
 +
 +
===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.
 
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.
  
[[Image:Orion-openresource.png]]
+
[[Image:Orion-openresource.png|Open resource dialog]]
  
 +
===Searching inside the editor===
 
You can also perform a global search on a highlighted phrase from inside the editor using the '''Ctrl + H''' shortcut.
 
You can also perform a global search on a highlighted phrase from inside the editor using the '''Ctrl + H''' shortcut.
  
[[Image:Orion-searchineditor.png]]
+
[[Image:Orion-searchineditor.png|Global search in editor]]
  
 
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.
 
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.
  
[[Image:Orion-browserbar.png]]
+
[[Image:Orion-browserbar.png|Using the browser history to find files]]
  
 
==Working with git==
 
==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 [http://git-scm.com/ 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.
+
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 [http://git-scm.com/ Git] repositories. For files and folders that are managed in a Git repository, you will see a menu allowing you to navigate to various Git views dealing with the file or folder:
  
[[Image:Orion-gitmenu.png]]
+
[[Image:Orion-gitmenu.png|Git commands are in the actions menu]]
  
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.
+
The Related pages menu will also give you contextually appropriate links to various Git pages, including the top-level of your Git repository.
  
[[Image:Orion-status-page-overview.png]]
+
[[Image:Orion-relatedpages-git.png|Git commands in the Related pages menu]]
  
A side-by-side compare view is also provided.
+
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.  
  
[[Image:Orion-gitsidebyside.png]]
+
[[Image:Orion-status-page-overview.png|Git status page]]
  
The [[Orion/Documentation/User_Guide/Reference/Git_Status_page|Git Status page]] shows also a list of recent commits on the active branch. You may open the [[Orion/Documentation/User_Guide/Reference/Git_Log_page|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 slide out the <b>Commit details</b> panel to see more information.
+
Click the twistie arrow next to a changed file to show a comparison of what changed in the file.
  
[[Image:Orion-gitlog.png]]
+
[[Image:Orion-git-status-compare.png|Git status compare]]
 +
 
 +
If you prefer, you can view the changes in a side-by-side comparison:
 +
 
 +
[[Image:Orion-gitsidebyside.png|Side by side compare]]
 +
 
 +
The [[Orion/Documentation/User_Guide/Reference/Git_Status_page|Git Status page]] shows also a list of recent commits on the active branch. You may open the [[Orion/Documentation/User_Guide/Reference/Git_Log_page|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 [[Orion/Documentation/User_Guide/Reference/Git_Commit_page|Git Commit page]]
 +
for complete information about that commit.
 +
 
 +
[[Image:Orion-git-log-overview.png|Git log overview]]
  
 
You can also open the [[Orion/Documentation/User_Guide/Reference/Compare_page|Compare page]] for each change in the selected commit.
 
You can also open the [[Orion/Documentation/User_Guide/Reference/Compare_page|Compare page]] for each change in the selected commit.
Line 159: Line 183:
 
==Launching your project as a website==
 
==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 [[Orion/Documentation/User_Guide/Reference/Site_Configurations_page|Site Configurations 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.
+
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 [[Orion/Documentation/User_Guide/Reference/Sites_page|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 [[Orion/Server_admin_guide#Configuring_virtual_host_names_for_launching_sites|Configuring virtual host names]] for more detail.
 
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 [[Orion/Server_admin_guide#Configuring_virtual_host_names_for_launching_sites|Configuring virtual host names]] for more detail.
  
You create a site by clicking the '''Create Site Configuration''' button and supplying a name for your site. Your new site will appear in the table, with commands for starting, stopping, or editing the site.
+
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 "My Work" 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.
 +
 
 +
[[Image:Orion-sites.png|Sites page]]
 +
 
 +
Assuming you are at the sites page you can click the '''Start''' button to start the site. The result will be similar to the following image, showing the site running and the URL showing where the site can be accessed.
 +
 
 +
[[Image:Orion-site-started.png|A started site]]
 +
 
 +
Upon visiting the site's URL, success! — We see the listing of the "My Work" directory we added.
 +
 
 +
[[Image:Orion-site-dir-index.png|Site showing files]]
 +
 
 +
Now browse to index.html:
 +
 
 +
[[Image:Orion-site-landingpage.png|Site on Orion server]]
 +
 
 +
At this point, we can do incremental development by using the Orion editor to change the files in our "My Work" folder, and then simply reloading the site page to see the changes.
 +
 
 +
==Extending Orion==
 +
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 [[Orion/Documentation/User_Guide/Reference/Settings_page|Settings page]] from the '''Options''' menu at the top right of the Orion banner (next to the user name). Then click the '''Plugins''' category on the left-hand side of the screen.
  
[[Image:Orion-sites.png]]
+
[[Image:Orion-pluginregistry.png|Plugin page]]
  
Click on the new site to go to the [[Orion/Documentation/User_Guide/Reference/Edit_Site_page|Edit Site page]]. Under the '''Mappings''' table, click the '''Add...''' button.  This will give you a row in which you can define a mapping from a folder in your Orion user workspace to the location on the server where the folder will be deployed. The following screenshot shows us mapping the "MyWork" folder to the root of our new site.
+
The Plugins page shows what plug-ins you have installed, and allows you to install, reload, or remove plugins. You can see that several plugins that provide Orion functionality, such as file management, user management, Git, JSLint, are already installed. Plugins extend Orion by implementing new behaviors, or ''extensions'' to the system. Places where "extensions" may be contributed are often called ''extension points''.
  
[[Image:Orion-siteedit.png]]
+
===Extending the Navigator===
 +
The [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.navigate.command|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. Each contributed command can specify how many and what types of files it can work with.
  
Click on the '''Save''' button to save the site configuration. Go back to the list of site configurations and click the '''Start''' button ([[Image:Orion start icon.gif]]) next to your new site configuration. Now you should be able to view your site at the address shown in the '''Status''' column.
+
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 Plugins 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.
  
[[Image:Orion-site-started.png]]
+
[[Image:Orion-sampleCommands.png|New commands in the action menu]]
  
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.
+
The "Bulk item command" can act on more than one item, so it will appear in the Actions menu when you select more than one item in the navigator.
  
[[Image:Orion-site-landingpage.png]]
+
[[Image:Orion-sampleSelectionCommands.png|New commands in the section menu]]
  
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.
+
===Learning more===
 +
More information about plug-ins and extensions can be found in the [[Orion/Documentation/Developer_Guide/Architecture|architecture]] section in the [[Orion/Documentation/Developer_Guide|Orion Developer Guide]].  See [https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.core/web/plugins/sampleCommandsPlugin.html sampleCommandsPlugin.html] for the source code.

Revision as of 14:17, 30 October 2012

This tutorial will get you started with using Orion, and provides a step by step walk-through of some of the core functionality.

Contents

Getting Orion

You have two choices to get started with Orion. The first is to create an account on the public server at OrionHub. To do this, visit OrionHub, click Create a new account and enter your information. An email will be sent to confirm your address. Once confirmed, return to OrionHub and log in.

The second method to get started is to download a standalone version of the server. For instructions, see Install Orion on Localhost.

Once you have successfully set up an account, you can proceed to the next step.

Logging into Orion

When you attempt to access a page that requires logging in, you'll be redirected to the Login Page and prompted for credentials.

Login Page

On your first visit to the login page, you can sign in using either of these ways:

  • Sign in with existing Orion account
    Sign in using the username and password of your Orion account.
  • Sign in with Mozilla Persona Sign in using a Mozilla Persona. To do this, your Persona email address must be the same as the email address you chose when creating your Orion account. You can sign up for a Persona here.

Later on, after you've logged into Orion and linked a Google account to your Orion account, you'll be able to sign in with Google:

  • Sign in with associated Google account Sign in with a linked Google account. To link a Google account, use Orion's Settings page.

If you are accessing a server other than OrionHub or localhost, the server administrator may have disallowed you from creating an account on the Login Page. In that case, you'll have to ask the server administrator to create one 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, make sure you're at 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.

Orion Initial Navigator State

To start working with files and folders in Orion, create a folder using the New > Folder action in the navigator toolbar:

Navigator Toolbar

To navigate the files, you can either expand the folders (using the ► twisties), or you can click on the folder's name to drill into that folder. After you have drilled into a folder, you can use the breadcrumb at the top of the page, or your browser's Back button, or a keyboard command (Alt+↑) to navigate back up the tree.

Navigator Breadcrumbs

Using the common banner

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 a user 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 folder (or in general, the resource you're currently viewing) as a favorite. The search box allows you to quickly search the contents of the current folder. Next to the search box is the search options menu, which lets you set advanced options such as regular expression search and access saved searches. The Related pages menu lets you quickly navigate to another Orion page relevant to the folder you're viewing (for example, if you're viewing a folder inside a Git repository, you can navigate straight to the Git Log page for the folder).

Below the banner, the content of the page appears. The page toolbar contains commands. The New File and New Folder act on the current folder (unless you've made a selection in the file tree).

Common Banner

Commands that apply to an individual file or folder are located in the Actions menu next to the item in the navigator.

Navigator actions

Files and folders may be selected by clicking their row, or by using the Ctrl and arrow keys on the keyboard. Once a selection has been made, commands that operate on the selected items (such as move, copy, and delete) will be available in the Actions menu.

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.

Import files

To import files from your local file system into Orion, select one or more files on your computer and drag them on to the Import dialog:

Import from zip dialog

The dialog only accepts files, not folders, so to import a folder, you'll have to zip it first. Then drag the .zip file into the dialog, ensuring that the Unzip *.zip files option is checked, and the contents of the zip file will appear in your folder in the navigator, like this:


Imported zip contents

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.

Export as zip

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.

Creating favorites

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

Favorites are also suggested as move/copy targets.

Favorites as copy / move targets

They also appear in the Find File dialog.

Favorites in find file

Editing code

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 Alt+Shift+? (Ctrl+Shift+? on Mac OS). Outside of the editor, you can get the same help on any page by pressing Shift+?.

JavaScript development

If you are working with JavaScript (a *.js file), the editor will syntax highlight your code. You will also see an outline of the functions in your JavaScript, as well as markers for problem areas in your code. Integration with existing web tools is an important goal in Orion, so we have implemented a plug-in that runs JSLint on JavaScript files in order to produce the outline and problem markers. The familiar Eclipse problem UI is used to display the problems in the editor. You'll see problem markers beside each offending line of code in the left-hand ruler, red underlining under the problematic text, and overview problem markers to the right-hand side of the editor. These last markers allow you to navigate quickly to a problem in a part of the file that's not currently displayed.

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.

Orion allows multiple kinds of code outline views to be plugged in. For example you can install the nonymous plugin that provides a hierarchical JavaScript outline view and an advanced way of naming anonymous JavaScript functions. If you have multiple outline views installed, a drop-down menu at the top of the outline pane allows you to switch between them.

Editing JavaScript screenshot

Firebug Integration

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.

CSS development

Syntax highlighting of CSS files is also supported. Orion uses CSSLint to validate and check for problems in CSS files. An outline view is also provided, which shows the list of rules in your file and allows you to quickly navigate between them. As a proof of concept, Orion provides 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.

Editing CSS screenshot

HTML development

A simple HTML outline is provided, based on DOM ids. Syntax highlighting is also available for HTML files.

Editing HTML screenshot

Java development

Java syntax highlighting is also supported. However, we have not implemented any outlining or content assist. Since we are building an integrated web-based toolset, we felt it important to target first the web client languages such as JavaScript, CSS, and HTML, so we can attract members of the JS community to Eclipse. Since we are self hosting Orion development in Orion, we need the JS features first.

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.5/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.

Plugins can contribute commands to the editor

Searching

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.

Scoped search box

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.

Search results page

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.

Open resource dialog

Searching inside the editor

You can also perform a global search on a highlighted phrase from inside the editor using the Ctrl + H shortcut.

Global search in editor

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.

Using the browser history to find files

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 allowing you to navigate to various Git views dealing with the file or folder:

Git commands are in the actions menu

The Related pages menu will also give you contextually appropriate links to various Git pages, including the top-level of your Git repository.

Git commands in the Related pages menu

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.

Git status page

Click the twistie arrow next to a changed file to show a comparison of what changed in the file.

Git status compare

If you prefer, you can view the changes in a side-by-side comparison:

Side by side compare

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.

Git log overview

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 "My Work" 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.

Sites page

Assuming you are at the sites page you can click the Start button to start the site. The result will be similar to the following image, showing the site running and the URL showing where the site can be accessed.

A started site

Upon visiting the site's URL, success! — We see the listing of the "My Work" directory we added.

Site showing files

Now browse to index.html:

Site on Orion server

At this point, we can do incremental development by using the Orion editor to change the files in our "My Work" folder, and then simply reloading the site page to see the changes.

Extending Orion

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). Then click the Plugins category on the left-hand side of the screen.

Plugin page

The Plugins page shows what plug-ins you have installed, and allows you to install, reload, or remove plugins. You can see that several plugins that provide Orion functionality, such as file management, user management, Git, JSLint, are already installed. Plugins extend Orion by implementing new behaviors, or extensions to the system. Places where "extensions" may be contributed are often called extension points.

Extending the Navigator

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. Each contributed command can specify how many and what types of files it can work with.

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 Plugins 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.

New commands in the action menu

The "Bulk item command" can act on more than one item, so it will appear in the Actions menu when you select more than one item in the navigator.

New commands in the section menu

Learning more

More information about plug-ins and extensions can be found in the architecture section in the Orion Developer Guide. See sampleCommandsPlugin.html for the source code.