OverviewOfUmpleOnline

Introduction

This is an overview of UmpleOnline to help guide developers when making changes or adding features to UmpleOnline. It gives the responsibilities of individual, notable files on UmpleOnline. It also describes the current testing implementation and gives some general suggestions on how to improve UmpleOnline.

Responsibilities by File

This is split into two parts. The backend and frontend of UmpleOnline. This will not contain any discussion of parts of the main Umple software that the UmpleOnline backend interacts with. Instead, it will focus on only files within the umpleonline/ folder. All file paths mentioned are relative to the umpleonline/ folder.

Backend

Filename	Description
scripts/compiler.php	This file is responsible for receiving ajax calls from the frontend of UmpleOnline. It maps them to one of the Umple JAR's, either umple.jar or umplesync.jar. It unpacks the parameters from ajax calls, uses them to determine the correct command-line call and passes the parameters.
scripts/compiler_config.php	This file largely contains utility functions that are invoked by compiler.php or umple.php. It contains functions to: Generate <select> menu options for code generation in umple.php. Save and load Umple models within UmpleOnline. Generate filenames for Umple models within UmpleOnline. Abstract common functionality away from compiler.php, such as executeCommand(). Wrap server maintenance commands, such as cleanupOldFiles(). True to its name, this file contains a few configurations for compiler.php, such as file paths. This file also contains unused functions from past or experimental features of UmpleOnline, such as UIGU.

Frontend

Filename	Description
umple.php	This is the main front-facing file for UmpleOnline and therefore contains all the static HTML. In addition to providing the main content for UmpleOnline, it also parse incoming URL query strings. Available URL query parameters include: nochrome – if true, this provides a version of UmpleOnline that does not include the page header. This is intended to allow an embeddable version of UmpleOnline. nodiagram – if true, this suppresses the canvas container of UmpleOnline. diagramtype – this sets the type of diagram the canvas container of UmpleOnline is displaying on load. If this is not set, an editable class diagram is displayed. If this is set to “class” then a GraphViz class diagram is displayed. If this is set to “state” then a GraphViz state diagram is displayed. If this is set to “structure” then a composite structure diagram is displayed. notext - if true, this suppresses the text editor container of UmpleOnline. showlayout - if true, the layout editor will be visible on page load. nomenu - if true, this suppresses the menu container of UmpleOnline. readonly - if true, this disables any editing features of UmpleOnline. This file also calls the Page.init() that initializes many JavaScript features on UmpleOnline.
scripts/_load.js	This is the only JavaScript file that umple.php runs directly. It loads all the JavaScript and css files that UmpleOnline uses. The loading order this file imposes on the JavaScript is important, as many of the UmpleOnline-specific JavaScript files depend on other libraries, such as jQuery.
scripts/styles.css	This contains the base styles applied to all parts of UmpleOnline.
scripts/umple_page.js	This script contains the main initialization functions, including Page.init(), which is called by umple.php. In general, this script holds and maintains the state of UmpleOnline. It enables other scripts to access and set many parts of UmpleOnline. For example, it has the functions getUmpleCode() and setUmpleCode() which get and set the code in the main text editor of UmpleOnline. All the functions and attributes are held within a global object called Page.
scripts/umple_action.js	This script contains many of the functions that react to user interaction with UmpleOnline. For example, this script contains handling functions for special hovers, click actions, key board shortcuts, and text editing reactions. All the functions and attributes within this file are all held within a global object called Action.
scripts/umple_layout.js	This script holds the state and the behaviour of UmpleOnline's dynamic layout. This contains a main controller that swaps between using two LayoutManagers for different screen widths. The controller part of the script handles any screen width-agnostic layout features, and provides hooks for the layout managers. There are two layout managers. One is the LargeScreenManager and is active above a certain threshold screen width. This layout manager organizes the text editor, menu panel, and canvas in a single row. The other layout manager is the SmallScreenManager which is above below a certain threshold screen width. This layout manager organizes the text editor and menu panel in a single row, and places the canvas in a second row below.
scripts/umple_tooltips.js	This script handles the HTML-enabled tooltips that appear on many UmpleOnline elements. It contains a dictionary of tooltip information as a JavaScript object. The format of the dictionary is idOfHtmlTagToTooltop: [“typeOfHtmlTag”, “html contents”]. The script also contains an initialization function that is called during initialization of UmpleOnline.
scripts/umple_history.js	This script provides the stack used for the undo functionality of UmpleOnline.
scripts/umple_restore.js	This script is responsible for saving/loading page state to/from user's cookies.
scripts/umple_action_diagram.js	This script contains the functions that handle user interaction with editable class diagram. Any graphical editing done on an editable class diagram will be handled by this script.

The rest of the files that will be discussed here is the JavaScript responsible for the rendering of the editable class diagrams. This functionality is implemented in an object-oriented fashion with each JavaScript file representing a class.

Filename	Description
scripts/umple_system.js	This class coordinates the overall rendering of the diagram. It can create all the elements of the diagram, and is able to find and remove various elements from the diagram by id.
scripts/umple_position.js	This class represents a position on the diagram.
scripts/umple_line.js	This class contains the code to render lines on the diagram. These lines are used by various other classes, such as generalizations and associations.
scripts/umple_class.js	This class contains the code to render and organize the elements within an UmpleClass.
scripts/umple_attribute.js	This class contains the code to render an attribute within an UmpleClass in the diagram.
scripts/umple_method.js	This class contains the code to render a method within an UmpleClass in the diagram.
scripts/umple_association.js	This class contains the code to render associations within the diagram.
scripts/umple_generalization.js	This class contains the code to render generalizations within the diagram.

Current Testing Implementation

Within the folder umpleonline/testsuite is the ruby-based test implementation for UmpleOnline. It uses rspec as a test framework with Capybara as the website interaction library. To enable cross-platform and headless testing, PhantomJS is used as the browser to run the tests and Poltergeist is used to provide a ruby binding to PhantomJS.

These tests are implemented by emulating the way a user interacts with UmpleOnline. The user's actions are performed on the website and then appropriate changes in state are checked. This has the benefit of catching the same errors that real users will notice. Unfortunately, it depends on a real running version of UmpleOnline, and is therefore much slower than a unit test-based approach to testing. In addition, because the features test many parts of the code at once, it can be difficult to track a particular failure to the offending code.

These tests are run through a ant build script: build/build.websitetests.xml. Instructions on use are built into the script and can be displayed by using ant -f build/build.websitetests.xml help.

The tests are broken up into a number of features, and the file structure is organized in the same way. Each feature has two files associated with it, a _test_spec.rb file, and a _helper.rb file. The test spec file contains the actual test cases, and the helper file contains common functions used within those test cases. These files are contained within the umpleonline/testsuite/spec folder. These are the features that are currently tested:

Feature name	Description
dynamic_layout	These tests ensure the dynamic resizing of the layouts of UmpleOnline work properly.
page_load	These tests ensure that the URL query string options are processed correctly.
load_examples	These tests ensure that all the umple examples load properly. This tests both the textual portion and the graphical portion of the examples.
diagram_editing_model	These tests ensure that graphical editing functionality correctly modifies the model.
diagram_editing_position	These tests ensure that the graphical editing functionality correctly modifies the positional data for the model.
options_panel	These tests ensure the menu items in the “options” tab of the menu panel work correctly.

General Suggestions to Improve UmpleOnline

These suggestions are guidelines to help developers improve UmpleOnline by making more durable and lowering technical debt.

UmpleOnline's file structure could use some cleaning up. A quick look inside umpleonline/scripts will reveal this fact. Many of the files within the scripts folder are not scripts. Many assets, such as icons and other images are stored here. A simple change would be to create a new assets folder, aggregate these in that new folder, and update the references to the moved files. In addition, the various JavaScript files would benefit from being organized into various subdirectories. Having the JavaScript files that deal with rendering of the canvas, for example, in their own directory within the scripts folder would make it clear that they are a separate functional unit.

Many of the JavaScript files would benefit from refactoring. In particular, umple_page.js and umple_action.js could each be refactored into multiple files. Also, it would be beneficial if these refactorings would move the code towards an object-oriented implementation.

The last general change would be to add unit testing to much of the JavaScript, using a testing framework, such as Jasmine. This sort of testing would be easiest to apply to the parts of the code that are already implemented in an object-oriented way. Thus, adding unit-tests and refactoring to object-oriented implementation go hand-in-hand. Adding unit-testing would replace some of the much slower tests that are currently implemented, and would make it simpler to find the code that causes any failures.