Contents Download Update-Site
You should first install the NiceXSL plug-in from the http://nicexsl.sourceforge.net/update-site by opening the Install/Update perspective from Window->Open Perspective... Then within the Install Features view, you may right click to New->Site BookMark... and configure it as:
NiceXSL Update Site
Eclipse update site
What "Name" you use and where you "Create in" is immaterial.
After clicking Finish, the additional book marked site appears. You should open it by clicking on the +. You may need to be slightly patient while Eclipse downloads the feature.jar file without giving any feedback to the user.
[If you are behind a firewall, don't forget to Window->Preferences->Install/Update to enable an appropriate HTTP proxy connection.]
Then open the NiceXSL category within the NiceXSL bookmark site to see the list of available feature releases. Select the most recent, and the NiceXSL overview should appear. Click on Install Now, acknowledge that you want to install NiceXSL, accept the CPL 1.0 license, and once again acknowledge that you want to install. Once you restart the workbench NiceXSL is available for use.
On Eclipse 2 (but not 3), the NiceXSL welcome page should appear automatically. to summarize the available functionality. It may be reactivated from Help->Welcome...
You may also confirm installation from Help->About where you should see the NiceXSL logo.
There is no explicit NiceXSL project; there is just a NiceXSL Nature which may be added to any project. You do not therefore need to take any action to be able to Reverse Engineer .xsl to .nxsl, or to manually compile .nxsl to .xsl within an existing Eclipse project.
If you do not yet have an Eclipse project, but do have some .xsl files you may create a Project to include them by File->New->Project...:Simple:Project then Next, Set Project name: to e.g. myxsl, deselect Use default and Browse... to somewhere just above all your files. If your files are all in .../Parent/xsl/*.xsl, select .../Parent as the project folder. Then click Finish to create the project.
If you do not yet have an Eclipse project or any .xsl files , you may create a Project by File->New->Project...:Simple:Project then Next, Set Project name: to e.g. myxsl, retain Use default and click Finish to create the project. You may use the NiceXSL plug-in as the source of some example .xsl files by dragging a copy of either src/XSL2NIceXSL.xsl, or tests/test.xsl from nicexsl_x_y_z.zip in a/the Eclipse plugins directory to your project.
You may reverse engineer individual .xsl files, or multiple .xsl files in the same folder by activating the XSLT to NiceXSL Actions sub-menu from the context sensitive menu for .xsl files in Navigator or Java Package Explorer views.
Decompile decompiles a single file and prompts for an output file.
Decompile... decompiles multiple file and prompts for an output folder to which all decompilations are written with the changed extension .nxsl.
Files with the .nxsl extension are edited by default with the NiceXSL syntax colouring. .nxsl files should have the smiley XSL logo. If the logo is not shown in Navigator or Package Explorer views, NiceXSL is not installed. If the syntax colouring is not shown, you are using the default text editor, so close the file and reopen explicitly with Open With...->NiceXSL editor.
Note that the syntax colouring is just based on keywords, so all XSLT, XPath and XQuery reserved words are highlighted regardless of context.
You may also create a new .nxsl file via the New-File->Other...NiceXSL wizard.
You may compile manually, using the NiceXSL to XSLT Actions sub-menu in exactly the same way as for reverse engineering. This is suitable for initial experiments, but you will soon tire of confirming that you want to overwrite the .xsl file.
You may compile automatically using an ANT script, however you will get no early indication of typographical errors. Be aware also that there is a memory leakage issue with ANT in Eclipse 2.x and so you may run out of memory every 25 or so ANT invocations.
Once you are ready to overwrite .xsl files more automatically, you may invoke Add NiceXSL Nature from the context-specific project menu of Navigator or Package Explorer views.
The NiceXSL Nature which may be added to any project to provide support for automated translation of .nxsl to .nxsl files within the project. This may well be a Java project, particularly if you provide Java extensions to XSLT. Additional notes on Java projects are given later.
The default source (.nxsl) and target (.xsl) paths for the NiceXSL compiler are blank, resulting in the .xsl files appearing alongside their .nxsl counterparts. You may separate these by specifying distinct prefixes in Window->Preferences->NiceXSL or Properties->NiceXSL Compiler for a project with a NiceXSL nature. Once the NiceXSL nature has been added, .nxsl files are automatically compiled whenever the file is saved and the project built. NiceXSL syntax errors are shown in the task window with markers at the sides of the source text. Hierarchical markers are also shown in the Java Package Explorer. Note that on Eclipse 2, this only occurs in response to an explicit Project->Build Project unless Window->Preferences->Workbench.Perform build automatically on modification has been selected so that a build occurs with each save. On Eclipse 3 automated build is controlled by the Project->Build Automatically setting.
The NiceXSL compiler detects NiceXSL and XPath syntax errors. It does not detect XSLT semantic errors, and so these will not be diagnosed until the XSLT is executed. Improved error checking, and integration of the .xsl within a multi-page editor will be provided in a future release.
[To terminate automated NiceXSL compilation you may Remove NiceXSL Nature.]
If you add the NiceXSL nature to a Java project, you should therefore be aware of some over-helpful behaviour by the standard Java builder.
By default, all non .java files are copied from src to bin folders, so your .nxsl and .xsl files may all have clones, and the redundant compilation of the bin clone of the .nxsl may encounter access anomalies. The easiest solution is to use a non-overlapping folder hierarchy for your .nxsl sources. Alternatively you may disable this behaviour by adding .nxsl and .xsl with comma separation to the list of Filtered Resources in Window->Preferences->Java->Compiler->Build Path.
The default settings for a full Java build results in the output folders being scrubbed, which is a little disappointing if the .xsl files have just been generated there. The easiest solution is to use a non-overlapping folder hierarchy for your .xsl sources. The alternative of disabling this scrub by clearing Scrub output folders on full-build in Window->Preferences->Java->Compiler->Build Path is not recommended.
Problems are highlighted by pop-ups, when they occur in the User Interface thread. All problems, are logged in the error log, which may be accessed by Window->Show View->Other...->PDE Runtime->Error Log. The error log often has a stack trace and rather more detail.
Edward D. Willink
25 July 2004