Orion News

As a quick follow up to the last post, we thought it would be worthwhile to mention 2 ways on how to embed the Orion editor in your blog. Depending on whether you want to make the editor always available for use on your blog, you can select to add the code either in the header or run it inline.

Header

If you are planning on posting lots of code to your blog, you might be better off in including your code in the header of your site. This is what we did for the planetorion.org site – which is a WordPress blog. We will also take a look at how to embed it in a Blogger site.

WordPress

To add the editor to you WordPress blog (assuming you have the necessary permissions to modify the blog), from the Dashboard select Appearance>Editor.

This will bring you to the Edit Themes page. From the Templates list on the right hand side, select “Header”. This will bring up the header.php code where we will insert the code for the editor.

Locate the last php tag before the closing </head> tag in the header.php – the php tag will contain the call to wp_head() – the orion editor code should be copied before the php tag.

Here is the code we used:

<!-- Orion Editor start-->

<!-- Global version -->
<link rel="stylesheet" type="text/css" href="http://eclipse.org/orion/editor/releases/3.0/built-editor.css"/>
<script src="http://eclipse.org/orion/editor/releases/3.0/built-editor.js"></script>
<script>
	if (window.addEventListener) {
		window.addEventListener('load', function() {
			require(["orion/editor/edit"], function(edit) {
				edit({className: "editor"});
			});
		}, false);
	}
</script>

<!-- AMD version -->
<!--
<link rel="stylesheet" type="text/css" href="http://eclipse.org/orion/editor/releases/3.0/built-editor.css"/>
<script src="http://requirejs.org/docs/release/2.1.4/minified/require.js"></script>
<script>
	require(["http://eclipse.org/orion/editor/releases/3.0/built-editor-amd.min.js"], function(edit) {
		edit({className: "editor"});
	});
</script>
-->

<style>
pre.editor{
	padding: 0px;
	border: 1px solid lightgrey;
}
</style>
<!-- Orion Editor end-->

Two quick comments on the code. First of all we reference the 2.0 release in the code as it is the current stable release. If you want to live on the cutting edge, you can replace the 2.0 with 3.0 in all places to get the latest good build from the development stream. Second, notice that both versions of the build are included in the above snippet (although one is commented out) – use whichever one you prefer. You can also choose to modify the classname to something else – you just have to make sure to use the new name. For example if you change the classname in the header to:

//...snip ...
edit({className: "orionEditor"});
//... snip ...

all uses of the editor in your blog posts would then need to use this new name:

<pre class="orionEditor" data-editor-lang="js">
/*
 * This is an Orion editor sample.
 */
function() {
}
</pre>

Blogger

The same idea applies to Blogger blogs – if you want to be able to use the editor in all of your posts, you should put the code in the header. To get to the right place, select Template from the right hand side, and then click on the Edit HTML button to bring up the template.

We used the exact same code that we put in the WordPress header and we pasted it right before the closing </head> tag.

Using the Editor

Once you have added the editor code to your header files, you can use it anywhere in your blog by simply adding the class="editor" attribute to either a pre or div in your code that contains the code you want displayed in the editor.

Inline

If you just want to get a standalone snippet that you can use in your blog or on a page, Ken wrote a useful plugin you can install into your OrionHub account that will generate a standalone snippet for you right from your editor.

To install it, click on Get Plugins in the top Orion bar, and then click Install next to the Snippet plugin.

Once it’s installed you can open an editor instance and you will see a new Snippet button at the top of the editor. Select the code that you want to paste into your blog, hit the Snippet button and you will get a piece of selected code that’s ready to be copied into your blog (don’t forget to hit Ctrl+Z afterwards to get back your original editor contents).

- Bogdan & Silenio

The Orion 1.0 Shell page provided a basic mechanism for plugging custom commands into a shared command line environment.  Shell page enhancements for Orion 2.0 have focused on formalizing new parameter types that provide access to files in the Orion workspace, and enabling commands to return result values beyond plaintext.  Additionally, users can now redirect command output to workspace files.  The implementation of zip and unzip commands will be used to demonstrate these new capabilities.

There are two new command parameter/return types:

• blob: A blob is just a JS blob object representing binary data (for example, an ArrayBuffer).
• file: A file represents a file or folder in the Orion workspace, and has the following shape:

  {
      path: (string, relative to CWD, no trailing '/'),
      isDirectory: (optional boolean, if absent implies false),
      blob: (optional blob, the file's content, absent if isDirectory is true)
  }

Command parameters of type file can be configured to give the desired file selection/autocompletion behaviors.  The configurable attributes are booleans that default to false if absent, unless noted otherwise:

• directory: true if directories should be selectable
• file: true if files (files that are not directories) should be selectable
• multiple: true if multiple directories/files should be selectable (setting this to true enables the use of wildcards)
• recurse: true if directory descendents should be recursively selected (only relevant if directory and multiple are true)
• exist: true if a selected/typed directory or file must exist, or false if it must be non-existent.  If undefined, the default behavior is to allow both existing and non-existing files to be selected/typed.
• content: true if content should be retrieved for selected existing files (only relevant if file is true)

Example: zip command

The following plug-in implementation of a zip command uses JSZip, a public JS library, to do the hard work.

<html>
<head>
<title>Shell 'zip/unzip' Plugin</title>
<script src="/orion/plugin.js"></script>
<script src="https://raw.github.com/Stuk/jszip/v1.0.0/jszip.js"></script>
<script src="https://raw.github.com/Stuk/jszip/v1.0.0/jszip-load.js"></script>
<script>
window.onload = function() {
    var zipProperties = {
        name: "zip",
        description: "Archive files into a .zip",
        parameters: [{
            name: "files",
            type: {name: "file", file: true, directory: true, exist: true, multiple: true, content: true, recurse: true},
            description: "The files to add to the .zip"
        }],
        returnType: "blob"
    };
    var zipImpl = {
        callback: function(args) {
            var zip = new JSZip();
            var files = args.files;
            files.forEach(function(file) {
                var segments = file.path.split("/");
                var current = zip;
                var dirSegmentCount = segments.length - (file.isDirectory ? 0 : 1);
                for (var i = 0; i < dirSegmentCount; i++) {
                    var segment = segments[i];
                    if (segment !== ".") {
                        current = current.folder(segment);
                    }
                }
                if (!file.isDirectory) {
                    current.file(segments[dirSegmentCount], file.blob);
                }
            });
            return zip.generate({type:"blob"});
        }
    };

    var provider = new orion.PluginProvider();
    provider.registerServiceProvider("orion.shell.command", zipImpl, zipProperties);
    provider.connect();
};
</script>
</head>
<body></body>
</html>

Use of some new Shell page features can be seen in the zipProperties object.  The “files” parameter specifies that workspace files and directories should be selected recursively, and the new returnType command attribute specifies that the returned value will be a blob (the return type defaults to string in the absence of this attribute).  The details of zipImpl are not worth examining here, other than to notice that its returned value is a blob.  Running command “zip ui” in the Shell page (where “ui” is the name of a directory in the cwd) gives the following output:

A destination was not specified for the resulting blob, so the default destination is the Shell page’s output area.  However the Shell page will not attempt to write returned blob content to its output since it’s unlikely to be readable, hence the not-too-useful output of “(1 blobs)”.  It’s up to the user to redirect a command’s output to a workspace location of their choice by providing a value for the optional output argument that is now added to all contributed commands.  So running command “zip ui –output ui.zip” successfully writes the returned blob content to file ui.zip.

Example continued: unzip command

The unzip command can be added within the same plug-in file as the zip command above, so details like its <script> inclusions are omitted here.

    var unzipProperties = {
        name: "unzip",
        description: "Extract the files from a .zip archive",
        parameters: [{
            name: "file",
            type: {name: "file", file: true, exist: true, content: true},
            description: "The .zip to extract from"
        }],
        returnType: "[file]"
    };
    var unzipImpl = {
        callback: function(args) {
            var zip = new JSZip(args.file.blob);
            var files = zip.files;
            var newFiles = [];
            for (var name in files) {
                if (name.lastIndexOf("/") === (name.length - 1)) {
                    /* represents a directory */
                    newFiles.push({path: name.substring(0, name.length - 1), isDirectory: true});
                } else {
                    var file = zip.file(name);
                    newFiles.push({path: name, blob: file.asArrayBuffer()});
                }
            };
            return newFiles;
        }
    };
    // ...
    provider.registerServiceProvider("orion.shell.command", unzipImpl, unzipProperties);

Since unzip’s return type is [file], the user-provided –output value will represent the directory that the resulting files are written to.  Values of type file are always resolved in terms of a directory since a file has a path attribute, while values of type blob are always written to a file since a blob is just raw data.

String value processing

Another enhancement to command return values is the processing of string values for markdown-formatted links.  Result strings written to the Shell page now have any contained URLs that are formatted as [link text here](link.address.here) replaced with live anchor elements.  As an example, command return value “Visit [Eclipse](http://www.eclipse.org), or literally [](http://www.eclipse.org)” renders as shown below.

What’s Next?

The piece that’s missing from this updated picture is a means of chaining commands, or at least specifying a custom input source (analagous to the new –output parameter).  The absence of these is the reason that the example unzip command takes a file as its input, rather than a blob, which would have made it symmetrical with the zip command.  Blobs are currently only usable as command return values, not as parameters. The ability to chain commands is dependent on GCLI adding support for this functionality, but adding something like an –input parameter is an interim step that the Shell page could take for 3.0.

If there are more Shell page features that your plug-in needs then please log Enhancement Requests in Orion’s Bugzilla.

Lastly, thanks are due to Stuart Knightley for his JSZip utility that made implementing the zip/unzip example trivial.

The Orion editor has been packaged into 2 standalone builds to help make it easier to use. These are available from the Orion build page in the most recent 2.0 builds.

Here is how you can get the latest release and embed it in your Javascript code:

Step 1: Add the following lines somewhere in your head section to get the built css and editor files:

<link rel="stylesheet" type="text/css" href="http://eclipse.org/orion/editor/releases/2.0/built-editor.css"/>
<script src="http://eclipse.org/orion/editor/releases/2.0/built-editor.min.js"></script>
<script>
	require(["orion/editor/edit"], function(edit) {
		edit({className: "editor"});
	});
</script>

Step 2: Add the editor class and some data attributes to the HTML element containing the code you want to display in the editor.

<pre class="editor" data-editor-lang="js">
/*
 * This is an Orion editor sample.
 */
function() {
    var a = 'hi there!';
    window.console.log(a);
}
</pre>

Done!

The editor features can be customized by passing in data attributes. Here is the current available list with the defaults:

/**
	 * @class This object describes the options for edit.
	 * @name orion.editor.EditOptions
	 *
	 * @property {String|DOMElement} parent the parent element for the view, it can be either a DOM element or an ID for a DOM element.
	 * @property {Boolean} [readonly=false] whether or not the view is read-only.
	 * @property {Boolean} [fullSelection=true] whether or not the view is in full selection mode.
	 * @property {Boolean} [tabMode=true] whether or not the tab keypress is consumed by the view or is used for focus traversal.
	 * @property {Boolean} [expandTab=false] whether or not the tab key inserts white spaces.
	 * @property {String} [themeClass] the CSS class for the view theming.
	 * @property {Number} [tabSize=4] The number of spaces in a tab.
	 * @property {Boolean} [wrapMode=false] whether or not the view wraps lines.
	 * @property {Function} [statusReporter] a status reporter.
	 * @property {String} [title=""] the editor title.
	 * @property {String} [contents=""] the editor contents.
	 * @property {String} [lang] the styler language. Plain text by default.
	 * @property {Boolean} [showLinesRuler=true] whether or not the lines ruler is shown.
	 * @property {Boolean} [showAnnotationRuler=true] whether or not the annotation ruler is shown.
	 * @property {Boolean} [showOverviewRuler=true] whether or not the overview ruler is shown.
	 * @property {Boolean} [showFoldingRuler=true] whether or not the folding ruler is shown.
	 */

To customize your editor, simply add data attributes prefixed with “data-editor-”. Since HTML attributes are case insensitive, camel case letters are prefixed by a dash. For example to create a Javascript editor with only the line ruler showing, you would create the editor like this:

<pre class="editor" data-editor-lang="js" data-editor-show-annotation-ruler="false" 
data-editor-show-overview-ruler="false" data-editor-show-folding-ruler="false"
>
/*
 * This is a orion editor sample.
 */
function() {
    var b = 'no rulers here!';
    window.console.log(a);
}
</pre>

Here is what this will look like:

/*
 * This is an Orion editor sample.
 */
function() {
    var b = 'no rulers here!';
    window.console.log(a);
}

Stay tuned for more posts on the Orion editor – for more info on the new builds check out the editor build wiki page.

This post is for fellow Eclipse committers who have recently migrated their Eclipse project web sites to Git. With your web site stored in Git, you can now use Orion to maintain your web site directly from your browser without installing any tools. Here is a quick primer to get you started.

1. Create an OrionHub account

If you don’t already have one, the first step is creating a new account at orionhub. Simply go to orionhub.org and follow the directions to create a new account. You will receive a confirmation email, and you need to click the link in that email to confirm your account.

2. Setup

Although not strictly needed, there are some setup steps you can do with your new account to smooth your Orion experience. Once logged in, click your username in the top right corner, and navigate to the Settings page.

On the User Profile tab, enter your Git email address and user name to be used when creating new commits. If you want, you can also select Enable Storage to allow Orion to cache your Git password or ssh keys in the local browser storage. This saves you from having to enter it on every push and pull. Finally, at the very bottom of this page under Linked Accounts, you can associate your Orion account with a Persona or OpenId (google) account. This is entirely optional, but means in the future you can log into Orion with your Persona or Google credentials, and not have to worry about another password to remember.

Since Eclipse web sites tend to be PHP-happy, you will probably also want to install a plug-in to provide PHP syntax highlighting. By default Orion only highlights HTML, CSS, and JavaScript, but you can teach it to highlight other file types using plug-ins. In the top banner, click Get Plugins to visit the Orion plugin catalog. Find the CodeMirror plug-in, and click Install. This will bring you back into Orion, where you need to click Submit to complete the installation.

3. Get the code

Now we’re ready to pull your web site into Orion. Go to the Repositories page, and click Clone Repository. Paste in the ssh URL of your Git repository, and click Submit.

Once the clone completes, you will see the web site repository added to your repositories list:

4. Edit the site

Click Show in Navigator next to your repository to reveal your site in the Navigator page. From here you can browse around, create/delete/rename files and directories, and import content. Click any file to open it in the Orion editor:

5. Commit your changes

Once you have finished making your changes, you’ll want to commit them. The Related menu is the easiest way to navigate between different Orion pages that focus on the same file or directory. From either the editor or navigator page, open the Related menu, and select Git Status. The status page shows you something similar to git status on the command line, except it shows you a rich compare editor that lets you easily browse between your changes.

All the usual git commands for manipulating your working directory or Git index are available here, such as Stage, Unstage, Commit, Checkout, Reset, etc. The Commits section at the bottom shows any local commits that have not yet been pushed to the remote, and any fetched commits that have not yet been merged into your local working copy.

Simply stage, commit, and push your changes, and you’re done! Visit your web site and bask in the glory of browser-based development. Now that you’re all setup, you can easily maintain your web site from any connected PC or tablet from anywhere in the world. The downside is you now have no more excuses for why your Eclipse project page is always so out of date…