|
|
|
|
@ -0,0 +1,287 @@
|
|
|
|
|
@c This document is part of the Liza Data Collection Framework manual.
|
|
|
|
|
@c Copyright (C) 2018 R-T Specialty, LLC.
|
|
|
|
|
@c
|
|
|
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
|
|
|
@c under the terms of the GNU Free Documentation License, Version 1.3
|
|
|
|
|
@c or any later version published by the Free Software Foundation;
|
|
|
|
|
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
|
|
|
@c Texts. A copy of the license is included in the section entitled ``GNU
|
|
|
|
|
@c Free Documentation License''.
|
|
|
|
|
|
|
|
|
|
@node Hacking
|
|
|
|
|
@chapter Hacking Liza
|
|
|
|
|
@helpwanted
|
|
|
|
|
|
|
|
|
|
This chapter provides general information and guidance for
|
|
|
|
|
[prospective] developers of Liza.
|
|
|
|
|
|
|
|
|
|
@dnindex Libraries
|
|
|
|
|
@dnindex GNU ease.js
|
|
|
|
|
@dnindex Mocha
|
|
|
|
|
@dnindex Chai
|
|
|
|
|
For writing classes; interfaces; and traits,
|
|
|
|
|
developers should familiarize themselves with @easejs{}.
|
|
|
|
|
For writing unit tests,
|
|
|
|
|
developers should be familiarize themselves with
|
|
|
|
|
@mocha{} and @chai{}.
|
|
|
|
|
For more information on the libraries used by Liza,
|
|
|
|
|
see @ref{Libraries}.
|
|
|
|
|
|
|
|
|
|
@dnindex Copyright Header
|
|
|
|
|
@dnindex Source Files
|
|
|
|
|
@dnindex Source File Naming
|
|
|
|
|
Most source files have a general structure that must be followed.
|
|
|
|
|
For example,
|
|
|
|
|
all such files must have a copyright header and
|
|
|
|
|
must be named after the class they define or system under test.
|
|
|
|
|
For more information,
|
|
|
|
|
@pxref{Source Files}.
|
|
|
|
|
|
|
|
|
|
Generally speaking,
|
|
|
|
|
developers should be familiar with vanilla ECMAScript;
|
|
|
|
|
DOM APIs;
|
|
|
|
|
and have a basic understanding of Node.js for well-rounded Liza
|
|
|
|
|
development.
|
|
|
|
|
Writing this manual requires basic understanding of Texinfo.
|
|
|
|
|
References for these topics and others are provided in
|
|
|
|
|
@pxref{Developer Resources}.
|
|
|
|
|
|
|
|
|
|
@menu
|
|
|
|
|
* Source Files:: Conventions for project files
|
|
|
|
|
* Libraries:: The few libraries used by Liza
|
|
|
|
|
* Developer Resources:: Where to look for more information
|
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@node Source Files
|
|
|
|
|
@section Source Files
|
|
|
|
|
@helpwanted
|
|
|
|
|
|
|
|
|
|
@dnindex Source Files
|
|
|
|
|
This section describes conventions for organizing files,
|
|
|
|
|
both in directory structure and in content.
|
|
|
|
|
|
|
|
|
|
@menu
|
|
|
|
|
* Copyright Header:: Important header at the top of all
|
|
|
|
|
source files
|
|
|
|
|
* ECMAScript Strict Mode:Strict Mode. Always indicate strict mode
|
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
@node Copyright Header
|
|
|
|
|
@subsection Copyright Header
|
|
|
|
|
@dnindex Copyright Header
|
|
|
|
|
@dnindex License
|
|
|
|
|
@dnindex GNU General Public License version 3
|
|
|
|
|
@dnindex GNU General Public License version 3, Or Later
|
|
|
|
|
Every source file should begin with a copyright header including the
|
|
|
|
|
appropriate years and license information.
|
|
|
|
|
This ensures that this information is always available even if the
|
|
|
|
|
file becomes separated from the source distribution (e.g. is
|
|
|
|
|
distributed independently).
|
|
|
|
|
Further,
|
|
|
|
|
it is necessary to indicate that the source file is distributed under
|
|
|
|
|
the GNU General Public License version@tie{}3 @emph{or later}@mdash{
|
|
|
|
|
}that ``or later'' clause does not exist as part of the license itself,
|
|
|
|
|
and so the mere presence of the license in @file{COPYING} is
|
|
|
|
|
insufficient.
|
|
|
|
|
|
|
|
|
|
The copyright headers vary slightly between JavaScript and Texinfo
|
|
|
|
|
source files,
|
|
|
|
|
represented in @ref{f:cheader-js} and @ref{f:cheader-texi}
|
|
|
|
|
respectively.
|
|
|
|
|
|
|
|
|
|
@float Figure, f:cheader-js
|
|
|
|
|
@example
|
|
|
|
|
/**
|
|
|
|
|
* DESCRIPTION OF FILE
|
|
|
|
|
*
|
|
|
|
|
* Copyright (C) 2017, 2018 R-T Specialty, LLC.
|
|
|
|
|
*
|
|
|
|
|
* This file is part of the Liza Data Collection Framework
|
|
|
|
|
*
|
|
|
|
|
* Liza is free software: you can redistribute it and/or modify
|
|
|
|
|
* it under the terms of the GNU General Public License as published by
|
|
|
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
|
|
|
* (at your option) any later version.
|
|
|
|
|
*
|
|
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
|
* GNU General Public License for more details.
|
|
|
|
|
*
|
|
|
|
|
* You should have received a copy of the GNU General Public License
|
|
|
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
|
*/
|
|
|
|
|
@end example
|
|
|
|
|
@caption{Example copyright header for JavaScript files}
|
|
|
|
|
@end float
|
|
|
|
|
|
|
|
|
|
@float Figure, f:cheader-texi
|
|
|
|
|
@example
|
|
|
|
|
@@c This document is part of the Liza Data Collection Framework manual.
|
|
|
|
|
@@c Copyright (C) 2018 R-T Specialty, LLC.
|
|
|
|
|
@@c
|
|
|
|
|
@@c Permission is granted to copy, distribute and/or modify this document
|
|
|
|
|
@@c under the terms of the GNU Free Documentation License, Version 1.3
|
|
|
|
|
@@c or any later version published by the Free Software Foundation;
|
|
|
|
|
@@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
|
|
|
@@c Texts. A copy of the license is included in the section entitled ``GNU
|
|
|
|
|
@@c Free Documentation License''.
|
|
|
|
|
@end example
|
|
|
|
|
@caption{Example copyright header for JavaScript files}
|
|
|
|
|
@end float
|
|
|
|
|
|
|
|
|
|
For more information, see ``How to Apply These Terms to Your New
|
|
|
|
|
Programs'' under the @gplvthree{}.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@node Strict Mode
|
|
|
|
|
@subsection ECMAScript Strict Mode
|
|
|
|
|
@dnindex Strict Mode, ECMAScript
|
|
|
|
|
ECMAScript@tie{}5's
|
|
|
|
|
@url{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode,Strict Mode}
|
|
|
|
|
throws errors in more situations that may lead to buggy code,
|
|
|
|
|
allows for better optimization of ECMAScript code during runtime,
|
|
|
|
|
and prohibits syntax that conflicts with future ECMAScript versions.
|
|
|
|
|
It also enables certain features,
|
|
|
|
|
like using @code{let} inside blocks.
|
|
|
|
|
|
|
|
|
|
It should always be enabled going forward as shown in @ref{f:strict-mode}.
|
|
|
|
|
The statement should immediately follow the copyright header
|
|
|
|
|
(@pxref{Copyright Header}),
|
|
|
|
|
before any other code.
|
|
|
|
|
|
|
|
|
|
@float Figure, f:strict-mode
|
|
|
|
|
@example
|
|
|
|
|
// Copyright header
|
|
|
|
|
|
|
|
|
|
'use strict';
|
|
|
|
|
|
|
|
|
|
// ...
|
|
|
|
|
@end example
|
|
|
|
|
@caption{Enabling strict mode}
|
|
|
|
|
@end float
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@node Libraries
|
|
|
|
|
@section Libraries Used
|
|
|
|
|
@dnindex Libraries
|
|
|
|
|
Liza does not use many libraries.
|
|
|
|
|
The primary reason for this was that few libraries useful to Liza
|
|
|
|
|
existed during its initial development@mdash{
|
|
|
|
|
}Node.js and its community was still very young.
|
|
|
|
|
With that said,
|
|
|
|
|
care should be taken to ensure that libraries are added only after a
|
|
|
|
|
careful analysis of its costs and benefits,
|
|
|
|
|
as they add volatility to the whole system and may also
|
|
|
|
|
introduce security vulnerabilities outside of our control.
|
|
|
|
|
They further introduce maintenance obligations for keeping up with
|
|
|
|
|
newer versions of those libraries and addressing
|
|
|
|
|
backwards-compatibility concerns.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@subsection System Libraries
|
|
|
|
|
@dnindex GNU ease.js
|
|
|
|
|
JavaScript does not natively support the classical object-oriented
|
|
|
|
|
model familiar to users of more traditional classical
|
|
|
|
|
object-oriented languages like Java, C++, C#, and@tie{}PHP.
|
|
|
|
|
Liza is built using @easejs{},
|
|
|
|
|
which provides those familiar features.
|
|
|
|
|
The primary language used by developers in the office that created
|
|
|
|
|
Liza is@tie{}PHP,
|
|
|
|
|
which motivated the creation of ease.js to ease the burden of
|
|
|
|
|
entry.
|
|
|
|
|
|
|
|
|
|
Consequently,
|
|
|
|
|
Liza is written in a classical object-oriented style rather than
|
|
|
|
|
using prototypes.
|
|
|
|
|
The @code{class} keyword introduced in ECMAScript@tie{} is largely
|
|
|
|
|
syntatic sugar around the prototype model and does not address the
|
|
|
|
|
primary concerns of ease.js,
|
|
|
|
|
nor does it provide traits.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@subsection Testing Libraries
|
|
|
|
|
@dnindex Mocha
|
|
|
|
|
@dnindex Chai
|
|
|
|
|
@mocha{} is used as the test runner for JavaScript unit tests.
|
|
|
|
|
@chai{} is the assertion library.
|
|
|
|
|
This differs from PHP development where a single system (PHPUnit)
|
|
|
|
|
encompasses both of these needs.
|
|
|
|
|
|
|
|
|
|
Chai offers a few different styles of assertions (``should'',
|
|
|
|
|
``expect'', and ``assert'');
|
|
|
|
|
Liza uses @url{http://www.chaijs.com/guide/styles/#expect,``expect''}.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@subsection UI Libraries
|
|
|
|
|
@dnindex jQuery
|
|
|
|
|
jQuery was used in the past,
|
|
|
|
|
but has been largely purged from the system (and continues to be
|
|
|
|
|
removed) due to strong performance issues.
|
|
|
|
|
Further,
|
|
|
|
|
now that browser APIs have stabalized and Liza no longer needs to
|
|
|
|
|
support as far back as Internet Explorer@tie{}6,
|
|
|
|
|
the standard DOM APIs are more than sufficient.
|
|
|
|
|
|
|
|
|
|
Liza instead provides its own UI and DOM abstractions
|
|
|
|
|
(@srcrefraw{src/ui}) that have been optimized for Liza's needs.
|
|
|
|
|
|
|
|
|
|
There are modern frameworks that may overlap with the type of UI
|
|
|
|
|
operations that Liza performs,
|
|
|
|
|
as well as certain DOM optimizations that it performs;
|
|
|
|
|
however,
|
|
|
|
|
it is unlikely that such frameworks (e.g. React, Angular, Meteor)
|
|
|
|
|
will ever be integrated,
|
|
|
|
|
as the cost of doing so exceeds the marginal benefit.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@node Developer Resources
|
|
|
|
|
@section Developer Resources
|
|
|
|
|
@dnindex Resources, Developer
|
|
|
|
|
@dnindex MDN
|
|
|
|
|
@url{https://developer.mozilla.org/en-US/docs/Web,MDN}@footnote{
|
|
|
|
|
Formerly the ``Mozilla Developer Network''; see
|
|
|
|
|
@url{https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/,''The Future of MDN: A Focus on Web Docs''}
|
|
|
|
|
for the history of the rename.}
|
|
|
|
|
is an essential resource for web development in general,
|
|
|
|
|
especially for JavaScript/ECMAScript and the various Web APIs.
|
|
|
|
|
It contains resources for all levels,
|
|
|
|
|
including for those @url{https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps,unfamiliar with JavaScript}.
|
|
|
|
|
All developers should familiarize themselves with the resources
|
|
|
|
|
available on MDN so that they understand what type of information is
|
|
|
|
|
readily accessible for future reference.
|
|
|
|
|
|
|
|
|
|
@dnindex Node.js
|
|
|
|
|
The Server (@pxref{Server}) uses Node.js.
|
|
|
|
|
Although it's largely abstracted away,
|
|
|
|
|
there may be times where you need to touch on it,
|
|
|
|
|
in which case the
|
|
|
|
|
@url{https://nodejs.org/en/docs/,Node.js documentation} will be helpful.
|
|
|
|
|
However,
|
|
|
|
|
it is important to note the version of Node.js that Liza is currently using,
|
|
|
|
|
as it may be woefully out of date and require looking at older
|
|
|
|
|
versions of the documentation.
|
|
|
|
|
|
|
|
|
|
@dnindex Texinfo, GNU
|
|
|
|
|
@cindex Documentation
|
|
|
|
|
This manual is written using
|
|
|
|
|
@url{https://www.gnu.org/software/texinfo/,Texinfo},
|
|
|
|
|
which is the documentation format of the GNU@tie{}operating system.
|
|
|
|
|
The format is structured and well-suited for software documentation
|
|
|
|
|
with output in a variety of formats.
|
|
|
|
|
Looking at the source code of this manual will be helpful@mdash{
|
|
|
|
|
}it provides the general structure and numerous macros that are
|
|
|
|
|
specific to Liza.
|
|
|
|
|
|
|
|
|
|
@dnindex MongoDB
|
|
|
|
|
@cindex Database
|
|
|
|
|
Data are persisted using @url{https://www.mongodb.com/,MongoDB}.
|
|
|
|
|
Database operations in Liza are abstracted away,
|
|
|
|
|
but it's helpful to understand how to query the database directly to
|
|
|
|
|
understand how the system works and composes its data,
|
|
|
|
|
and for the purposes of debugging.
|
|
|
|
|
|
|
|
|
|
For information on specific libraries used by Liza,
|
|
|
|
|
@pxref{Libraries}.
|
Mike Gerwitz