IDE-IT Frontend

Introduction and User Manual

IDE-IT Frontend Team:

• Alyssa Ricketts
• Puja Ramanathan
• Rachel Zigman

Quick Links:

1 - Introduction | 2 - Installation | 3 - Using IDE-IT Frontend | 4 - API to Register Other Backends | 5 - Add Your Own Suggestions | 6 - Reproducing User Tests | 7 - Reporting Bugs

1 Introduction

1.1 Motivation

The Eclipse IDE provides helpful user interfaces and features for authoring, modifying, compiling, deploying, and debugging software. However, due to low accessibility and awareness of these tools and features, only a small number of these powerful IDE functionalities get used. Additionally, many developers find that many tools in their IDEs are not trivial to configure, and this prevents them from using the tool at all. The aim of the Integrated Development Environment - Intelligent Tutorials (IDE-IT) is to improve the discoverability of existing IDE tools and shortcuts, by providing developers non-invasive suggestions on Eclipse features that they may not be aware of. The suggestions take the form of hotkey tips and easy enabling/disabling of configuration settings. The hotkey suggestions are shown when the user is continually performing tasks manually that could be done with a hotkey and the enable/disable features appear periodically with configuration settings that other developers have found to be extremely useful but many are unaware of their locations within the menu or of their existence.

1.2 IDE-IT Frontend

This repository / plugin is specifically for the frontend service of IDE-IT. This is not designed to be a standalone plugin. It requires a the use of a backend service that tracks user action such as document changes, key presses, and mouse clicks, and then performs the evaluation of which hotkeys and configurations to suggest. We recommend the IDE-IT backend plugin, located at https://github.com/DavidThien/IDE-IT, as this framework is built specifically for IDE-IT. If you would like to use your own custom backend framework, see below on how to incorporate our service to your own plugin.

^{back to top}

2 Installation

This section provides the instruction for installing IDE-IT Frontend for development purposes. Please see Eclipse-IDE-IT for user installation.

2.1 Prerequisites

1. Java JDK version 1.8.0 or higher. See Oracle Java Downloads for more.
2. Apache Ant version 1.10.5 or higher. See Apache Ant Binary Distributions for more.
3. Eclipse IDE for RCP and RAP Developers 2018-12 or higher. See Eclipse IDE Downloads for more.

2.2 Build Project

1. Clone this repository to your local machine

2. Navigate into the IDE-IT-Frontend folder within the cloned IDE-IT-Frontend folder

3. Build the plugin locally using ant:

   $ ant build
   

2.3 Clone Project into Eclipse

1. Open Eclipse
2. From the menu choose: File | Import
3. Click the Projects from Git option under the Git folder and press Next
4. Select Clone URI as your repository source and press Next
5. Paste https://github.com/AlyssaRicketts/IDE-IT-Frontend in the URI textbox and press Next
6. Select the master branch and press Next
7. Choose a destination directory on your local machine for the project and press Next
8. Use the Import existing Eclipse projects wizard and continue
9. Select the Eclipse-IDE-IT project folder and press Finish

2.4 Run Project as Eclipse Application

To run the entire IDE-IT application with the backend, you will need to import the backend project into your Eclipse workspace as well. Clone the project using the same steps as listed under Section 2.3, just changing the URI link to the corresponding backend repository.

To test any development changes to IDE-IT-Frontend, right click the IDE-IT-Frontend project. Then, choose Run As | Eclipse Application. The new workspace should open in a new window.

^{back to top}

3 Using IDE-IT Frontend

To use this plugin, we recommend using the integrated repository located at https://github.com/pujaram/Eclipse-IDE-IT. Follow the installation instructions for the Eclipse-IDE-IT repository to install IDE-IT in your Eclipse workspace.

To start using IDE-IT, first make sure the IDE-IT window is visible in your IDE. If it is not visible finish the steps in Installation above. Once the window is visible, just begin working on your project. The window will update based on patterns in your keystrokes with hotkey tips and features you might want to enable or disable.

3.1 Window Appearance

Tool enable/disable suggestions appear with a checkbox next to a text description of the tool. Hotkey tips appear with a lightbulb icon next to a text description of the hotkey/shortcut.

3.2 Enabling/Disabling Suggested Configurations

Simply check or uncheck the box next to the tool you would like to enable or disable.

3.3 Using Suggested Hotkeys

Next to the lightbulb icons will be suggested hotkeys, these are keyboard shortcuts that might make your coding experience easier and quicker.

3.4 Removing Unwanted Suggestions

If you do not wish to see a hotkey tip or are not interested in an enable/disable feature, simply click the "X" on the right side of that tip or tool to remove the suggestion from the window.

^{back to top}

4 API to Register Other Backends

This plugin requires a back-end service that tracks document changes within the Eclipse IDE to provide a list of feature suggestions to this plugin. The recommended back-end service for this plugin is the IDE-IT back-end plugin. If you would like to use a different back-end service, please continue reading.

The front-end depends on a FeatureSuggestionObserver abstract class and a FeatureSuggestionInterface abstract class. You should include these abstract classes within your project when you implement your own observers. You must implement a FeatureSuggestion class which extends FeatureSuggestionInterface. This class should call the notify function in the FeatureSuggestionObserver class to send the feature ID that uniquely identifies each Eclipse feature to the front-end.

If the feature suggestions you implement are included within the current features, you should use the same feature IDs as listed in this file. To add additional features, add the unique feature ID along with the Suggestion into the suggestions map in the Controller. For adding configurations specifically, there will need to be additional implementation to enable or disable the specified configuration.

To connect your plugin, export your project as a jar file named as 'backend_plugin.jar' and place the jar file in the IDE-IT-Frontend/IDE-IT-Frontend/lib folder. This will include your plugin as a dependency, so the project can be built and run. The backend plugin should also be open in the workspace in order to test the plug-in with the backend functionalities.

^{back to top}

5 Add Your Own Suggestions

5.1 Adding Hotkey Suggestions

1. In Controller.java, add the desired string identifier and corresponding Suggestion object to the suggestionsMap

   a. Suggestion object should include string identifier, the text to be displayed, HOTKEY as the type field, and true for the display field. See Suggestion.java for more information.

   b. If the hotkey varies for different operating systems, add the corresponding text for each operating system, and put each Suggestion in the map under the corresponding branches for the operating systems.

^{back to top}

5.2 Adding Preference Suggestions

1. In Controller.java, add the desired string identifier and corresponding Suggestion object to the suggestionsMap

   a. Suggestion object should include string identifier, the text to be displayed, CONFIG as the type field, and true for the display field. See Suggestion.java for more information.

2. In ConfigDisplayComposite.java:

   a. At the bottom of the document, create a new method with an input parameter Button checkBox and no return values

   b. In this method, follow the pattern of the other methods here, by calling

    checkBox.addSelectionListener(new SelectionAdapter() {
        @Override
        public void widgetSelected(SelectionEvent event) {
            Button btn = (Button) event.getSource();
            if(btn.getSelection()) {
                **Insert selection code here**
                try {
                    prefs.flush();
                } catch (org.osgi.service.prefs.BackingStoreException f) {
                    f.printStackTrace();
                }
            } else {
                **Insert deselection code here**
                try {
                    prefs.flush();
                } catch (org.osgi.service.prefs.BackingStoreException f) {
                    f.printStackTrace();
                }
            }
        }
    }
   

   c. Where the Insert selection/deselection code here is, insert the following:

    IEclipsePreferences prefs = <YourScope>Scope.<YourScope>.getNode(<YourNode>);
    prefs.put(<NodeName>, <value>);
   

   <YourScope> should be replaced with the specific scope you are interested. I.e. Instance, Configuration, Default, or BundleDefaults. See here for more information.

   <YourNode> should be replaced with the preference node of interest.

   <NodeName> should be replaced with the name of the preference of interest.

   <Value> should indicate the value you want this preference to be set to upon check/uncheck.

   d. Add a new else if branch where the Suggestion object ID is checked against the desired string identifier

   Use s.getID().equals(<insert string identifier>)

   e. In this branch, call the newly created method, passing the parameter checkBox to it

^{back to top}

6 Reproducing User Tests

Our method of user testing is described in detail in our project report which can be found in the most recently updated folder in our reports folder. If you are interested in reproducing our user tests the process is rather simple. Follow the above instructions on cloning and starting up the plugin and find participants within your target group to test the plugin. Then provide them with the following link which will take them to the survey we provided to our users: https://goo.gl/forms/TeKRrIywe8EfxUWr1. However, this link would send our team the results from the survey so if you are interested in analyzing the results yourself you would need to make a new google form following the same format as our survey and then provide your participants with that link instead. By doing this you will be able to sign into your google account and view the results of the survey. In the results section you are able to view each individual survey that has been submitted as well as graphs representing all of the data from the submitted surveys.

^{back to top}

7 Reporting Bugs

If you find any bugs in our plugin, please submit an issue to our GitHub page: https://github.com/AlyssaRicketts/IDE-IT-Frontend/issues with the following information:

• Eclipse Version located by going to Eclipse | About Eclipse.
• A brief description of the bug.
• Specific steps to recreate the bug.
• (Optional) A screen shot of the bug.

^{back to top}