Developers - OpenAero/main GitHub Wiki
OpenAero is, as it's name suggests, open software. The source code is freely accessible and anyone is invited to submit improvements and additions to the code.
If you're interested in doing this, there is some useful information on several subjects to be found below.
OpenAero is completely written in Javascript. Currently OpenAero is mostly tested on Google Chrome. Functioning on other browsers is considered a bonus (as of 2023, the Edge and Safari browser also work flawlessly). The reasons for this are:
- Chrome offers best support for modern HTML5 techniques that are needed for the functioning of complex web apps
- Chrome is highly standards compliant. Even though some of it's features are not supported in other browsers now, it's expected that this will happen in the future
- Chrome is available on all modern OSs, including mobile
- Testing and coding for multiple browsers takes time which is better spent at developing OpenAero functionality
- Completely Open Source
- Rescalable to any size without loss of quality
- Files are in XML format which means they are human readable and easily managed by software
The current stable version of OpenAero can be found at https://openaero.net and https://www.openaero.net . The development version is located at https://openaero.net/devel and is updated very frequently.
Beside the browser based version of OpenAero there are also in-store apps for Android, iOS and Windows. The Android and iOS versions are compiled using Cordova and offer additional possibilities for users of Android and iOS devices. The apps are not (completely) open source. The Windows version is compiled using Visual Studio 2017.
For creating rule checking files, knowledge of Javascript or SVG are not required. What is required:
- A thorough understanding of the rules to be coded
- Understanding of Regular Expressions (regex)
A description of the format can be found at the beginning of the rules.js file, which is available at https://github.com/OpenAero/main/tree/master/data/rules. In the source code you can also find various other (national) rule files to help you get started.
It's possible to import rule files into OpenAero from the browser. This is done through "Import rules file" which can be found in the "Tools" menu. A message will be presented indicating success or failure. The rules that have been loaded can also be checked through Chrome's Javascript Console (Chrome menu -> More Tools -> Developer Tools).
After checking your rule file for correctness, you can send it to [email protected] to have it added to the next version of OpenAero.
For regular users, OpenAero should be run from openaero.net or app (Android, iOS or Windows). This assures the latest version is always available. Developers however may want a local copy to see how changes to the code work out. To create a local copy of the source, go to https://github.com/OpenAero/main. There, you can create a clone of the project using Git (see below) or download a zip file of the code.
Once a copy has been made, OpenAero can be opened by opening the local index.html page from the OpenAero directory. Alternatively, the OpenAero directory can be put under your own webserver's directory and accessed by going to http://localhost/OpenAero
This is the preferred method, as it keeps track of changes and improves collaboration. The main branch of OpenAero is used for development. Releases are published separately. For the essentials, take a look at:
Before diving right in, please take some time to get familiar with OpenAero's code. All of it is heavily commented so it should be possible to get a quick grasp of it workings. The main files are:
BASE:
* index.html Main page. Holds menus, predefined dialogs etc
CONFIGURATION:
* js/config.js All configuration options etc * data/library.js Library of sequences * data/figures/figures.js Figure definitions * data/logo.js Logo definitions, mostly as SVG * components/languages/en.js Holds English user interaction texts * components/languages/XX.js Holds language XX user interaction texts * data/rules/rules.js Default rules and explanation of rules files format * data/rules/rules-XXX.js Specific rule sets for association XXX
SOFTWARE:
* js/main.js The core of the system. All functions, user interaction etc * js/rulesWorker.js Performs rule checking asynchronously in a Web Worker * js/jszip.min.js Used to create ZIP files (e.g. for _Save figs separate_) * js/vkbeautify.min.js Used to create good-looking XML output * js/qrcode.min.js Used to create sequence QR codes
STYLING:
* assets/css/general.css Main css file with all general declarations * assets/css/desktop.css CSS for desktop use only * assets/css/desktop-largeMobile.css CSS for desktop and large mobiles * assets/css/mobile.css CSS for mobile use only * assets/css/smallMobile.css CSS for small mobile (smartphone) use only
So with respect to programming, most action takes place in main.js. To improve readability and prevent code repetitions many separate functions are used. Any action will usually have the effect of calling a number of these functions.
Most actions will initially be triggered by "mousedown", "change" etc... event handlers on an element in index.html. These handlers are mostly specified in function _addEventListeners_ in main.js. E.g. clicking on "Clear sequence" will trigger clearSequence() which will start the corresponding function in main.js.
Allthough specific elements can get quite complex, the basic functioning of OpenAero is simple:
* Read the sequence string * Check which kind of draw is requested (Form A, B, C, grid) * Convert the string to correctly oriented figures * put these in the *figures* global object, including extra information * Check the rules when applicable * Do the actual drawing from the *figures* object
When a figure is updated through the figure editor, or the sequence is changed through another point-and-click method:
* Update the sequence string * Start from 'Read the sequence string'