Eclipse configuration for Syntax Highlighting, Template proposals and Refactoring in Sahi scripts

You can use any text editor to write your sahi scripts. But Eclipse as an editor provides advantages like Syntax highlighting, Template proposals and Refactoring. This article explains how to use Eclipse as editor for Sahi scripts.

Sahi scripts - .sah Vs .js

Sahi scripts carry a .sah extension. But a .js extension can be used in place of .sah. Sahi treats a .js file the same as a .sah file.

To write scripts in Eclipse, one needs to have the JSDT Eclipse plug-in installed. The JSDT Eclipse plug-in provides native support for JavaScript (.js) files. One can add support for .sah files as well. But the JSDT plugin provides some additional features for .js files as compared to .sah files. Hence it is possible to rename .sah files as .js files and get better Eclipse support without losing any Sahi functionality.
danger We are looking at ways to make the script authoring experience easier and better for end users. At the time of writing this document, Sahi scripts carry a .sah extension by default. We are undecided on whether we will change the default extension to .js in a future release. We leave it to the end user to decide whether to use scripts with a .sah extension or change them to have a .js extension. This document explains how to deal with both extensions.
info If any configuration step is specific to .sah or .js files, it is explicitly mentioned. Unless explicitly mentioned, the step applies to both .sah and .js files.

This document explains features available for both .js and .sah files. If some feature is not available for .sah files, it is explicitly mentioned.
danger It is assumed that your scripts will either have a .sah or .js extension.
danger The steps have been documented for Eclipse Kepler (Eclipse Standard 4.3.1 - Windows 64 Bit version) version. It is possible that you may face difficulties with a different Eclipse version.

Eclipse configuration

  1. Open Eclipse. It will ask for the workspace path. We will assume that the workspace is (to be) created at the following location: C:\Sahi\SampleWorkspace. Specify the workspace path as indicated below, and click OK. Launch Workspace
  2. Ensure that the JSDT Eclipse plug-in has been installed. Click on Help | About Eclipse SDK | Installation Details.

    Eclipse Installation Details
  3. If not installed, click on Help | Install New Software. Use the settings displayed in the image below. If you are using an older version of Eclipse, you should see a corresponding update site in the Work with dropdown box. Install New Software Proceed with the installation.

    Restart Eclipse after installation. Give the same workspace path as before - C:\Sahi\SampleWorkspace. Launch Workspace
  4. Adding support for .sah files
    danger This step applies only if you are using .sah files. This is not needed for .js files.
    • Click on Windows | Preferences | General | Content Types
    • In Content types: section, select Text | JavaScript Source File and then in File associations: section, click on Add.
    • Make association for *.sah and click OK.

      Make Sahi Association
  5. Let us now create a new JavaScript Project.

    Click on File | New | Project... Create Project Search for JavaScript Project in Wizards and click on Next Create JS Project Give a Project name of your choice. We have given it the name: SampleProject. Click Next Give Project Name You should see the following two JavaScript Libraries in the Libraries tab
    1. ECMAScript Built-in Library
    2. ECMA 3 Browser Support Library
    Click on Finish JS Libraries If this is the first JavaScript project you created, an Open Associated Perspective dialog box will be opened, prompting you to use the JavaScript perspective.

    Click Yes. Open Associated Perspective
  6. You can create new files and folders under the project created. We will place all Sahi scripts inside a scripts folder. To create a new folder, right click on the project, and then click on New | Folder. Give the folder name as scripts and click on Finish. Create Folder To create a script file inside the scripts folder, right click on the folder, and then click on New | File. Give the new file its appropriate name and click on Finish. Let us name the file as sampleFile.js. If you intend to use .sah extension, name it as sampleFile.sah Create File You can copy your existing scripts into the scripts folder of the current project by pasting them at the appropriate location - C:\Sahi\SampleWorkspace\SampleProject\scripts. The screenshot shows scripts as .js files. If you intend to use .sah extension, the scripts will be .sah files. Move Files Refresh the project to see the copied files in your Eclipse IDE. Refreshed Project
  7. The JSDT plugin provides various templates for auto completion. Example: for, if etc.
    info These templates can be used in .js as well as .sah files.
    Sahi ships with a readymade template file, SahiEclipseEditorTemplates.xml that customizes some of these templates for better use in Sahi scripts. Download SahiEclipseEditorTemplates.xml to a folder location, say C:\Sahi\SampleWorkspace\EditorTemplates To install this templates file, click on Window | Preferences. Path to Preferences Now go to Javascript | Editor | Templates as shown in the figure and click on Import on the right. Import Templates Select the templates file SahiEclipseEditorTemplates.xml that we downloaded above, and press Open. Import Templates Press OK on the Templates window. SahiEclipseEditorTemplates.xml has now been successfully imported.

    To make use of any template, type the first few letters of the template and press Ctrl + Space to bring up the template proposal.

    Here are a few examples.

    Example: Type the first few letters of the template testcase and press Ctrl + Space to bring up the template proposal for _testcase. using testcase template Example: Type the first few letters of the for loop command and press Ctrl + Space to bring up template proposals related to for. using for template Likewise you can expand other templates listed at the location below. Import Templates
  8. Template functionality can also be added for Sahi APIs.
    info These templates can be used in .js as well as .sah files.
    • If you are using .sah extension, copy apis.sah from <SAHI_INSTALL_FOLDER>/userdata/scripts into the scripts folder in the project.
    • If you are using .js extension, copy apis.sah from <SAHI_INSTALL_FOLDER>/userdata/scripts into the scripts folder in the project and rename it as apis.js.
    Open any .js (or .sah) file from the JavaScript project, and you should be able to see Syntax highlighting.

    Type the first few letters of a Sahi function and press Ctrl + Space to bring up template proposals for Sahi APIs.

    View Intellisense

Refactoring a script into functions

info This feature is available in .js as well as .sah files.
Once you have a recorded script, Eclipse can help in refactoring the linear script into functions.

We have taken the following script to demonstrate refactoring using Eclipse Original Script Refactoring in Eclipse requires the code to be part of a function. Since the recorded script is not part of any function, we will first create a function surrounding our original code.

Select all the lines of code, Right Click | Surround With | function (function) as shown in the figure. Give the function an appropriate name (we have named it sampleApp). We will remove this function at the end of the Refactoring. Original Script Now, to extract a function out of selected lines of code, do the following: Select the lines of code | Right Click | Refactor | Extract Function. Original Script A dialogue box would show up, write the function name, and press OK, as shown in the figure. Original Script Repeat the same steps for all the lines of code you want to extract out as functions. At the end of this exercise, our script now looks like this: Original Script
    You can see the following changes in the script:
  1. The selected lines of code have been replaced by functions and calls to the respective functions.
  2. The refactored function code may not be formatted correctly. If so, you will have to format it manually.
  3. The created functions do not have any parameters. We will fix this in the next step.
To convert a value inside the function into a function parameter, do the following. Select the value | Right Click | Refactor | Introduce Parameter. Right Click On Variable Give a name to the parameter, beginning with $ and press OK. Here we have named the parameter as $java Give Variable Name You can see that the value has been extracted out as a parameter and function calls have been modified to pass a value for the parameter. Observe Changes We continue doing this for all the variables in our script. At this point, the script looks like this: Observe Changes We still have the temporary function we had made at the starting of Refactoring code, sampleApp. The script now looks like this: Observe Changes Let us now move the functions login, addAndAssertTotalCost and logout to a different file so that they can be included from multiple scripts.
warning The functions have to be moved manually.
Add a new file called sampleLib.js (or sampleLib.sah if you are using .sah extension). Copy the functions to this file. This will have to be done manually. SampleLib file Remove the functions from sampleFile.js (or sampleFile.sah if you are using .sah extension). Include sampleLib.js (or sampleLib.sah) using _include manually. sampleFile.js now looks like this Sample script with include

Renaming a function or variable name

info This feature is available in .js as well as .sah files.
danger However, it appears that it is more reliable in .js files than in .sah files.
There are times when one needs to rename a variable or function name. On doing so, the name should get changed at all places of usage, in all scripts.

Eclipse allows for such refactoring. Let us see how to rename a function name. We will rename the function addAndAssertTotalCost to addBooksAndAssertTotalCost.

To do this, open sampleLib.js, select addAndAssertTotalCost, Right Click | Refactor | Rename (or select addAndAssertTotalCost and press Alt + Shift + R). Launch Refactor - Rename You will be asked to enter a new name. Enter the new name addBooksAndAssertTotalCost and press Enter. Rename function The function name gets changed to addBooksAndAssertTotalCost. Sample lib after refactoring Open sampleFile.js. You will notice that the function name has been changed automatically in this file as well. Sample script after refactoring If this function were to be included in other files, it would get modified at all these locations.

Navigate to functions

danger This works only for .js files and not for .sah files.
One often needs to open a function declaration to view its contents. The function declaration could be present inside another script altogether. For example, let us try and look at the function declaration of addBooksAndAssertTotalCost from inside sampleFile.js.

One can open a function declaration in the following ways. You will be navigated to the function declaration in the appropriate script file. In this case, you will be navigated to addBooksAndAssertTotalCost in sampleLib.js. Function navigated to