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.

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.
2. Ensure that the JSDT Eclipse plug-in has been installed. Click on Help | About Eclipse SDK | 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. Proceed with the installation.
   
   Restart Eclipse after installation. Give the same workspace path as before - C:\Sahi\SampleWorkspace.
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.
     
     
5. Let us now create a new JavaScript Project.
   
   Click on File | New | Project... Search for JavaScript Project in Wizards and click on Next Give a Project name of your choice. We have given it the name: SampleProject. Click Next 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 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.
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. 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 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. Refresh the project to see the copied files in your Eclipse IDE.
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. Now go to Javascript | Editor | Templates as shown in the figure and click on Import on the right. Select the templates file SahiEclipseEditorTemplates.xml that we downloaded above, and press Open. 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. Example: Type the first few letters of the for loop command and press Ctrl + Space to bring up template proposals related to for. Likewise you can expand other templates listed at the location below.
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.
   
   

Refactoring a script into functions

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 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. Now, to extract a function out of selected lines of code, do the following: Select the lines of code | Right Click | Refactor | Extract Function. A dialogue box would show up, write the function name, and press OK, as shown in the figure. 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:

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. Give a name to the parameter, beginning with $ and press OK. Here we have named the parameter as $java 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. We continue doing this for all the variables in our script. At this point, the script looks like this: We still have the temporary function we had made at the starting of Refactoring code, sampleApp. The script now looks like this: Let us now move the functions login, addAndAssertTotalCost and logout to a different file so that they can be included from multiple scripts. 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. 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

Renaming a function or variable name

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). You will be asked to enter a new name. Enter the new name addBooksAndAssertTotalCost and press Enter. The function name gets changed to addBooksAndAssertTotalCost. Open sampleFile.js. You will notice that the function name has been changed automatically in this file as well. If this function were to be included in other files, it would get modified at all these locations.

Navigate to functions

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.

• Press the Ctrl key and hover the mouse over the function that you want to open. The function name will appear as a link. Click on the link while keeping the Ctrl key pressed.
• Or select the function, Right Click | Open Declaration.
• Or select the function, and press F3.

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.