Adding support for a new Ajax library

From Aptana Development

An Ajax library is added to Aptana Studio in the same manner as any other Eclipse plugin. We've provided a number of extension points to let you add library (.js) files, documentation, samples, snippets, AptanaMonkey scripts, custom views, and content assist metadata in a declarative manner. If you are familiar with Java and Eclipse plugin development, you can also customize your integration by writing Java code.

This document covers the extension points you can take advantage of without additional Java coding, and the content that can be provided for each point.

Contents

Testing the sample library plugin

A complete sample library is available at: http://www.aptana.com/downloads/ajax_library_plugin_sample.zip. To see how the various parts of this sample library show up in Studio, do the following:

  1. Quit Studio, if it's running.
  2. Unzip the archive.
  3. Select all files and folders inside org.library.name.0.1 folder (*not* the org.library.name.0.1 folder itself) and create a new .zip archive, naming it org.library.name.0.1_0.0.0.00001.zip.
  4. Change the .zip extension to .jar, and say Yes/OK when the OS asks if you're sure you want to do this.
  5. Drag the .jar to the Aptana Studio/plugins folder.
  6. Launch Studio.

You should now see a LibraryName Samples node in the Samples view, and LibraryName should be one of the Import JavaScript Library options when you create a new project. (The Snippets and Scripts included in the sample library are grouped with existing categories, so they won't be easy to spot.)

Creating your own library plugin

At this point you could just replace all instances of LibraryName, libraryname, and OrganizationName with the actual uppercase and lowercase names of your library and your organization name, respectively, and then follow the instructions above for testing the newly-renamed plugin in Studio—and, in fact, that's what this document used to tell you to do. What you'll have in that case, however, is a plugin that's different in name but identical in content to the sample plugin, which is not what you want.

Instead, take a moment to consider what kinds of support you want to add for your Ajax library. You can add as much or as little support as you want, so you may not need all of the following information. Start by reading Understanding MANIFEST.MF and plugin.xml and then skip around to the sections that apply to your circumstances.

Understanding MANIFEST.MF and plugin.xml

MANIFEST.MF and plugin.xml are the files that make your plugin a plugin; they're at the top level of the folder containing your plugin's supporting files. MANIFEST.MF is, as its name suggests, a manifest file for the plugin. It gives the name and version of the plugin, its dependencies, and its provider. The four lines that you will need to modify are as follows:

Bundle-Name: LibraryName Bundle-SymbolicName: org.library.name.0.1;singleton:=true Bundle-Version: 0.1.0.00001 Bundle-Vendor: OrganizationName

Bundle-Name can be just the name of the library (e.g., Ext JS or jQuery), or it can be a more descriptive string, such as Aptana Support for Dojo. Bundle-Vendor is you or your company; if we were providing the plugin, for example, the Bundle-Vendor would be Aptana, Inc. If it's you as an individual, just put your name.

The Bundle-SymbolicName and the Bundle-Version are the most important pieces of information, as they control whether the plugin is loaded properly. When you named your .jar file org.libary.name.0.1_0.0.0.00001 in the instructions above, you were combining the data from these two fields. Generally the pattern for the SymbolicName is reverse domain name plus library name plus major and minor version (for example, org.dojotoolkit.dojo.1.2 or com.yahoo.yui.2.6). Sometimes the domain name and the library name are the same, and in this case only the domain name is necessary (for example, com.jquery.1.2).

The Bundle-Version consists of a repeat of the major and minor versions, as well as a mini version and a build number. The build number refers to the build of the plugin, and should be padded with leading zeros to make 5 digits. Most plugins have a build number of 00001, but if it takes a few tries to get it right, the build number could advance to 00005 or 00006. If your library has no mini version (for example, jQuery 1.3), then enter 0. The Bundle-Version for the 1.2 release of Dojo was 1.2.0.00001; for 1.2.6 of jQuery, it was 1.2.6.00002.

plugin.xml contains information about the extension points the plugin is taking advantage of and where to find the supporting files for each. The supporting files and extension points are described in more detail below. If you don't want to provide certain types of support (for example, samples or snippets), just remove or comment out the corresponding extension point in the plugin.xml file.

Adding library files (and getting code completion)

Aptana Studio will automatically offer code completion for your library when you supply the .js file or files for the library. The .js files should go in libraries/lib/libraryName (e.g., libraries/lib/jquery).

Once you've copied the files, edit the com.aptana.ide.documentation.library extension point in the plugin.xml file with the name of the library and the path to a 16x16 icon for the library (drop the .png, .jpg, or .gif file in the icons folder):

<extension point="com.aptana.ide.documentation.library"> <libraryinfo directory="libraries" iconFile="icons/libraryName_small.png" name="Library Name #.#" /> </extension>

Adding Code Assist

If you want to go a step beyond code completion and add Code Assist, there are a few ways to do it:

If you are not the author of the library, check to see whether a ScriptDoc or OAA Metadata file is already available for the library (it might be in an SDK download or in the code repository). If no metadata file is availabe, check whether the documentation for the library is available as an XML file. You may be able to create an XSL transformation from the documentation XML format to the ScriptDoc or OAA Metadata formats.

If your .js library files are annotated with ScriptDoc, you don't need to add an extension point for content assist; the annotations will be picked up automatically when the .js files are parsed.

If you have a separate .sdoc file, copy it to the libraries/lib/libraryName folder along with the .js library files, and then add the following extension point to plugin.xml:

<extension point="com.aptana.ide.editor.js.scriptdoc"> <js-file icon="icons/libraryName_small.png" path="libraries/lib/libraryName/libraryName.sdoc" user-agent="Library Name #.#"/> </extension>

If you have a ScriptDoc or OAA Metadata file, you'll use the same com.aptana.ide.editor.js.scriptdoc extension point, but with an <xml-file> child instead of a <js-file> child. Also, you'll need to copy the XML file to a folder called support instead of putting it in with the libraries. The filename of the XML file can be anything, though to be considered valid by the OpenAjax Alliance, OAA Metadata files must end in _oam.xml.

<extension point="com.aptana.ide.editor.js.scriptdoc"> <xml-file path="support/filename.xml" user-agent="LibraryName #.#" icon="icons/libraryName_small.png" /> </extension>

Adding Samples

If you have sample files you'd like to include with the library, each sample or group of related samples should go in its own folder inside a samples folder. For example, if you have a stacked container sample and a tabbed panel sample, you might put the files in folders called stackedContainer and tabbedSample, respectively, inside the samples folder. Libraries like YUI often have 10 or more examples of a particular technique, so a folder called animation inside samples might have 10 different HTML files demonstrating various animations. Anoter library might have a single file containing 10 different examples. Either way, the file or files need to be in a discrete folder inside samples.

The sample files will certainly depend on library .js files; for example, a jQuery sample will include a reference to jquery.js (or one of its versioned or compressed variations). In order to allow for previewing samples within Aptana Studio and importing the sample as a project, the references to the library .js files in the samples should be changed to point to the library file(s) inside lib/libraryName.

For example, 

<script src="../../ext-all.js" ...></script>

would be changed to 

<script src="lib/ext/ext-all.js" ...></script>

Once you've updated your script references, you won't need to include any library .js files in the samples folder or sub-folders. The <include> tag in the com.aptana.ide.samples.samplespath extension point takes care of that.

<extension point="com.aptana.ide.samples.samplespath"> <samplesinfo directory="samples" iconFile="icons/libraryName_small.gif" infoFile="samples/index.html" name="LibraryName #.# Samples" previewHandler="com.aptana.ide.documentation.samples.AjaxSamplesPreviewHandler"> <!-- This include path tells Aptana Studio how to resolve the 'lib/libraryname/' references. --> <include path="libraries/lib"/> <!-- If you have additional files that are shared among samples, you can put the shared folder inside libraries and tell Aptana Studio where to find them. If you don't, you can remove this include tag. --> <include path="libraries/shared"/> <nature id="com.aptana.ide.project.nature.web"/> </samplesinfo> </extension>

Adding Documentation

You can add offline HTML documentation to your library by dropping files in a docs folder, adding an index.xml file that outlines the topics available, and including the org.eclipse.help.toc extension point in plugin.xml. There are a few things to keep in mind:

  • The Help is local, not running on a webserver, so XHR and other Ajax tricks will not work properly.
  • Try to minimize absolute http:// references so as not to penalize users who are working without an Internet connection.
  • Generally, Help opens in XULRunner (or Firefox on the Mac, if it is installed). The XULRunner that ships with Eclipse 3.3 and later on Windows uses an XML parser that will choke on docs that do not validate as XML. We recommend using an XHTML Strict doctype for this reason, and running your pages through a validator to ensure conformance.

The format of the index.xml file, which determines what shows up in the left (contents) column of the Help browser, is as follows: 

<!-- The toc label doesn't show up anywhere (afaik). The link_to attribute determines where in the toc
     this Help node appears; the value "../com.aptana.ide.documentation/tocreference.xml#libraries" says "under the 
	Aptana Studio documentation, in the reference section, under Ajax Libraries." -- >
<toc label="<b>LibraryName #.#</b> Reference" link_to="../com.aptana.ide.documentation/tocreference.xml#libraries">

     <!-- This is the label that shows up in the toc in the left column. The index.html file should contain the
	    first page of the docs, and introduction to the docs, or an index/alphabetical listing of entries. -- >
	<topic label="<b>LibraryName #.#</b>"  href="docs/index.html"> 

	    <!-- This is the first sub-category under LibraryName #.#. If you have no subcategories, only a flat list
           of topics, you can skip this container and just list your topics as empty topic tags. If this tag has
           no href attribute, a blank page will be shown when it is clicked in standalone Studio, but in Eclipse 3.3
           and later, a toc of subtopics may be generated and shown automatically. -- >
		<topic label="Core">

		    <!-- Individual topics (these ones are from jQuery 1.2). Note that all href values in this document
                   are relative to the plugin.xml file, and thus include the docs/ directory in the path. 
                   The #anchors are not necessary; they just happen to be used in the jQuery help. -->
			<topic href="docs/j.html#link-jQuery-html" label="jQuery(html)"></topic>
			<topic href="docs/j.html#link-jQuery-elements" label="jQuery(elements)"></topic>
			<topic href="docs/j.html#link-jQuery-callback" label="jQuery(callback)"></topic>
			<topic href="docs/j.html#link-jQuery-expressioncontext" label="jQuery(expression, context)"></topic>
			<topic href="docs/e.html#link-each-callback" label="each(callback)"></topic>
			<topic href="docs/e.html#link-eq-position" label="eq(position)"></topic>
			<topic href="docs/g.html#link-get-" label="get()"></topic>
			<topic href="docs/g.html#link-get-index" label="get(index)"></topic>
			<topic href="docs/i.html#link-index-subject" label="index(subject)"></topic>
			<topic href="docs/l.html#link-length-" label="length"></topic>
			<topic href="docs/s.html#link-size-" label="size()"></topic>
			<topic href="docs/j.html#link-jQueryextend-object" label="jQuery.extend(object)"></topic>
			<topic href="docs/j.html#link-jQueryfnextend-object" label="jQuery.fn.extend(object)"></topic>
			<topic href="docs/j.html#link-jQuerynoConflict-" label="jQuery.noConflict()"></topic>
			<topic href="docs/j.html#link-jQuerynoConflict-extreme" label="jQuery.noConflict(extreme)"></topic>
		</topic>
		<!-- Additional sub-topics can go here -->
     </topic>
</topic>
</toc>

Adding Snippets

If there are common coding patterns for your library, or if you have factory methods for which you need ScriptDoc comments to help determine the datatype returned, you may want to add snippets to your your plugin. To include these in the library plugin, copy the files to a snippets folder and add the com.aptana.ide.snippets.snippetspath extension point to plugin.xml: 

<extension point="com.aptana.ide.snippets.snippetspath">
	<snippetsinfo directory="snippets"/>
</extension>

Adding Web views

If you have additional HTML resources that you want to include with your library, you can include them in one or more web views. Web views show up just like any other panel in Aptana Studio, and can contain content that would normally run in a web browser. The same rules as with adding documentation apply; XHR is not likely to work, and remote URLs will cause problems for users who are offline.

Drop all the files associated with your view in a views folder, and include the org.eclipse.ui.views extension point in plugin.xml. If you have more than one view, you'll need a separate <view> child tag for each one.

<extension point="org.eclipse.ui.views"> <view category="com.aptana.ide.documentation" class="com.aptana.ide.core.ui.views.browser.DefaultBrowserView" icon="views/viewname/images/view_icon.png" id="com.aptana.ide.documentation.libraryname.viewname" name="View Name"> <!-- example of a valid description: bundleresource://com.jquery.1.2/views/visual_jquery/1.2.6.htm --> <description>bundleresource://pluginfoldername/views/viewname/filename.html </description> </view> </extension>

Adding Aptana Monkey/Eclipse Monkey Scripts

If you are familiar with Eclipse Monkey scripting and want to let the user perform library-specific tasks, you may want to add a scripts folder and a org.eclipse.eclipsemonkey.scriptpath extension point to your plugin.xml file. (If this sounds too vague, you probably don't need a scripts folder or extension point.) 

<extension point="org.eclipse.eclipsemonkey.scriptpath">
	<scriptpath directory="scripts"/>
</extension>

Testing your plugin

When you have all the supporting files in their proper subfolders, the plugin.xml file modified to include the proper extension points and folder/file locations, and the MANIFEST.MF file updated with the name and version of your library, it's time to test.

  1. Quit Studio, if it's running.
  2. Select all files and folders inside the library (e.g., com.myorg.mylib.3.5) folder—*not* the library folder itself—and add them to a .zip archive, naming it according to the conventions described in Understanding MANIFEST.MF and plugin.xml, above (e.g., com.myorg.mylib.3.5_3.5.0.00001.zip).
  3. Change the .zip extension to .jar, and say Yes/OK when the OS asks if you're sure you want to do this.
  4. Drag the .jar to the Aptana Studio/plugins folder.
  5. Launch Studio.

Test each piece that you've added, starting with creating a new project. Your library should be listed among the Ajax libraries to be included in the project, and when you've finished creating the project, you should get a lib/mylib/ folder in your project that contains the library .js files.

If you added samples, you should see them in the Samples view; test right-clicking each folder and choosing Preview sample and Import sample as project. Note that samples that include PHP or other dynamic markup, or that include XHR calls, may not preview properly; if you've included the library files properly in the sample files and plugin.xml, all others should.

Choose Help > Help Contents and expand the Aptana Studio Help > Reference > Ajax Libraries node to see your documentation, if you added some. Click the links to make sure it shows up properly. If you see what looks like an error log, chances are your page(s) contain invalid XHTML. If the layout is messed up, chances are the CSS is too complex or relies on JavaScript that the Help browser cannot execute. Try simplifying the code.

If you added any views, you should be able to find them under Window > Show View > Other... Aptana Library Views, or under Aptana > View if you are running Aptana Studio 1.2 or later.

Promoting your plugin

When you've got a plugin you find useful, it's likely others will find it useful, too. Let us know about your creation so we can promote it on our website.

Versioning your plugin

If you share your plugin with others and then need to make a change to it, be sure to increment the build number (00001 -> 00002, for example). If you need to update your plugin for a mini release (e.g., mylib 3.5.1), you can use the same plugin folder and just increment the mini number in the MANIFEST.MF and .jar file. If you need to update for a minor or major release (e.g., mylib 3.6 or mylib 4.0), you'll want to create a new plugin folder.

Retrieved from "http://docs.aptana.com/dev/index.php/Adding_support_for_a_new_Ajax_library"