openproject/frontend/doc/RAILS.md

Legacy Frontend in Rails

Important: There are no explicit tests for the legacy frontend code - most of it is covered by Capybara based specs.

application.js.erb

The manifest file hosts a plethora of additional JavaScript used throughout the application. It still maintains it's function as the original manifest used for the asset pipeline.

If you really do have to add some JavaScript which ties into either

• legacy views (i.e. non-angular views, of which there are plenty)
• component based JS (tooltip.js is an example)

you should create another JS file in ./app/assets/javascripts and use the manifest as you would in any other Rails application.

The goal here should be to get rid of the JavaScript put directly into application.js.erb.

Tie in with angular

The line between the original JavaScript and the "legacy" JavaScript is a little bit blurred, as there are cases where jQuery based JavaScript has to rely on existing angular behaviour and vice versa.

An example would be the use of the AutoCompleteHelper (see ./frontend/app/helpers/auto-complete-helper.js) in the old WorkPackage form, after an HTML form has been loaded into the existing DOM after the user has decided to update the Work Package):

//@see ./app/assets/javascripts/work_packages.js.erb
// the goal is to use the service for initializing atWho after a new piece of HTML has been inserted into the document

// the body is always the angular application on every page
var injector = angular.element('body').injector();

// the injecotr can be used to apply our service in arbitrary scopes
// NOTE: textareas is a collection of angular elements
injector.invoke(['AutoCompleteHelper', function(AutoCompleteHelper) {
    AutoCompleteHelper.enableTextareaAutoCompletion(textareas);
}]);

Note: In the above example, a scope is assumed for the elements passed to the service. The full implementation is a bit more esoteric, as one will have to manually create a scope around newly generated elements.

Legacy views in Rails

"Legacy views" are mostly views working with plain JavaScript, of which the most is found in application.js.erb.

Also, all of the plugins mainly use their own JavaScript to enable the functionality of their views.

The only views that currently rely on angular are:

• Work Packages List
• Timelines
• some private plugins

That should change over the course of development, especially to get rid of the prototype.js dependency.

Keep in mind, that there are places in the application where JavaScript code is safely stored away in a ruby method, an example would be the ApplicationHelpers own user_specific_javascript_includes.

A quick search for jQuery over all ruby files usually yields very good starting points and clues how and where to start refactoring.

protoype.js and plugins

Prototype and some of it's related plugins are used in several of OpenProjects plugins.

One extreme example is MyProjectPage, which duplicates functionality from the core application. It uses Sortable to achieve drag and drop functionality. It's a very old library (~2009) that is not maintained actively anymore.

Be that as it may, the prototype.js dependency cannot be fully removed as long as the plugins rely on it.

There are basically two approaches here:

1. Remove it completely and see what breaks
2. Move the prototype.js to the plugins that need it and remove the dependency from the core