JavaScript Files and Libraries Review Process
EPA has established this JavaScript (JS) review process and will maintain strict control of JS use in the One EPA Web environment. Most potential JS files and libraries will undergo review prior to being used in the One EPA Web environment.
There are four classes of JavaScript files that can be found in the Drupal WebCMS:
- library/framework scripts, like jQuery
- component/plugin scripts that require a library, like jQuery UI, jQuery Colorbox
- common application-level scripts that are shared among multiple pages and might require the above
- JavaScript embedded on a single page that might require the above
While JavaScript files and libraries can be easily written and deployed on an EPA server, larger issues are security, redundancy, and the need for caching.
- An improperly written JavaScript file can introduce security vulnerabilities which hackers can exploit to cause damage to the EPA Public Access servers.
- We want to reduce the number of duplicate JS files on the Drupal WebCMS server. (Duplicate JS files occur when multiple versions of the same JavaScript file(s) are uploaded.)
- We want to reduce duplicate functionality. There are dozens of lightbox-style scripts that do the same thing in a different way.
- We want to take advantage of caching—many JS files and libraries are large files, and if each of us link to and use the same files, we reduce our bandwidth and improve overall visitor experience.
For these reasons, we are establishing more control over JS files on the Drupal WebCMS server than we did with JS files on the static web server (buckeye). OEI will be reviewing all uses of JavaScript to ensure appropriate coding style and usage.
Approved JavaScript files and libraries are added to the Drupal WebCMS codebase, and you can link to these approved JavaScript files and libraries from your Drupal WebCMS pages.
Any content editor developing and maintaining "personal" JavaScript files (i.e., those developed for specific use and from outside NCC) must certify that the scripts are designed and implemented according to established guidelines and security standards.
- The Review Process
- Criteria for Approval of JavaScript Files and Libraries
- Lifecycle for JavaScript Files and Libraries
- Using Standard and Certified JS Files on Production Web Servers
- Using JavaScript for Dynamic (Small) Applications
The Review Process
OEI cannot help you troubleshoot your JS code. If you're using the standard JS, please see the Web Style Guide for examples and how-tos. If you're writing your own code or using a third-party library, you must know what you're doing. It is your responsibility to ensure that no conflicts exist between your code and existing JavaScript that are already in use for the One EPA template and the Drupal WebCMS application.
All external JavaScript files not already in use and approved must be reviewed, and your office will be responsible to fund that review via a Working Capital Fund service agreement (you will need a registration code). It should not take more than 10 hours per submission, but you should allow for at least five days for the scanning process (there's a queue). As scripts are submitted, we will monitor them for candidates to make generally available as part of our documented / semi-supported library. You, the original submitter, will remain primarily responsible, and OEI will serve as intelligent librarians, not code-maintainers.
Contact the TZ Service Manager in OEI to set up a TZ account to pay for the JavaScript code review under Working Capital Fund Services. OEI will work with CGI to give you a cost estimate and a description of what they will do.
Criteria for Approval
This is the review criteria for JS files and libraries:
- EPA JavaScript Web Standard
- JavaScript is ideally used to enhance pages and user experience. Pages should be able to display all of the real content and media when JavaScript is disabled.
- The use of JavaScript is discouraged when server-side coding can accomplish the same end goal.
- JavaScript should not be used to query complex datasets requiring numerous data files.
- JavaScript should not be used to perform complex calculations.
- OEI will approve the following:
- dynamic data presentation, such as from data files: CSV, JSON, XML;
- database calls to an EPA data source via AJAX/jquery;
- interactivity, including forms and form results.
- OEI will disapprove the following:
- Code that does not pass the JSHint (or JSLint) or EPA scanning processes;
- Code that is not properly licensed for use by EPA;
- Code that changes the EPA One Web look-and-feel (local styles are not allowed);
- JavaScript that breaks the responsive design template;
- JavaScript that injects HTML onto a page with contain local styles;
- Anything already part of the standard libraries or that can be achieved using JS files and libraries already approved;
- Any packed/minified JavaScript provided for to review.
Lifecycle of a JavaScript File or Library
This section outlines the life cycle of a JavaScript file or library in the Drupal WebCMS environment.
Stage 1. Development
The Application owner begins development and testing of JS. The EPA specifically provides the Drupal WebCMS Sandbox server for this purpose. The sandbox server has the same code as the production environment, decreasing the testing and debugging time. There is no cost to step up a user account on the sandbox. If you have an account on the production server, you also have an account on the sandbox.
During development the JavaScript coder should review the security issues as outlined in the JavaScript Program Security Checklist and Deployment Request Form. JS files will be expected to conform to these standards. Any script not in compliance with these standards will be disapproved.
You will first provide the JS files to OEI so that we can load them into the sandbox. A list of dependencies must be provided to OEI by the developer so that the JavaScript can be loaded in the correct order on the page. Once the files are available, you will build your page and code.
General Coding Rules
The long-term value of software is in direct proportion to the quality of the codebase. Over its lifetime, a program will be handled by many pairs of hands and eyes. If code is able to clearly communicate its structure and characteristics, it is less likely that it will break when modified in the never-too-distant future.
Code conventions can help in reducing the brittleness of programs. To the extent possible, follow Douglas Crockford's coding standards for JavaScript.Exit
Stage 2. Security Checklist and Deployment
Once development and testing has concluded, the JS owner submits the JavaScript Program Security Checklist and Deployment Request Form to WebCMS Support (web_cms_support@epa.gov). No work can take place until you have a registration id/charge code set up for vetting submitted code.
Submitted JavaScript files will be vetted by our contractors--they will scan your code and page. The code owner (you) will pay for this vetting, which should not take more than 10 hours of work per code submission. (Note that this means you pay for every submission, so it's to your benefit to ensure that the submitted code works.) This review process can take up to five days (there's a queue).
If the code passes review:
The JS files and libraries will be placed into the production repository (our revision control system). You will no longer have write access to the code. All changes to code will be recorded. Rollbacks to previous versions will be possible. You can request a rollback by emailing WebCMS Support (web_cms_support@epa.gov).
If the code fails review:
You will be notified with a copy of the review along with recommendations. The JavaScript then can be further developed until the security requirements are met. JavaScript that does not meet security and coding standards will not approved.
If a JavaScript fails on the production server:
If a JavaScript file or library fails in the production environment, OEI can provide only limited support (e.g., assist in the identification of failure points in the code). If problems cannot be fixed quickly, you must retest the code on EPA's Drupal WebCMS Sandbox server.
Stage 3. Updating a JavaScript File or Library
As OEI will manage the revision control system, you will no longer have write access to your production JS file or library. You will modify your JS on the Sandbox server and, when testing is complete, make a JS Update Request by contacting us.
After the request has been received and confirmed with you, OEI will run a diff on the two scripts. New code will be reviewed and tested. If the JavaScript passes review, it will be certified and updated as noted above. If it does not pass review, you will be notified as above.
If necessary, you can request that current code be rolled back to a previous version. To rollback, make a JS Update Request. One caveat: if the code is out of date, it will be subject to a new review before it is restored.
Stage 4. Retiring/Reactivating a JS File or Library
If a JavaScript is no longer required, you can retire it by submitting a JS Update Request.
The script will be retired from active use, archived, and available for reactivation. To reactivate it, submit a JS Update Request. One caveat: if the code is out of date, it will be subject to a new review before it is restored.
Please note that OEI will review JS usage periodically. If the code has not been used or accessed in the last 60 days, you will be notified. You can then determine if the JS should remain operational or be retired.
Using JavaScript for Dynamic (Small) Applications
One reason we're opening up JS for our content editors is captured in the image to the right, which shows an example of using JS to read and output data from an external data source (whether another EPA server or an uploaded data file).
DataTables or Highcharts, or other scripts, will help you display this external file-based data.
Examples include the Superfund Where you Live dataset (powered by Datatables and a JSON file), Region 1's Charles River Buoy dataset (powered by Highcharts and a CSV file).