# QuickCi - The Configurator Interface

is an Electron application template that can be used to create generic graphical configuration interfaces for command line utility programs. Electron is a Node.js library that allows for rapid development of desktop applications using as its interface a Chromium browser. Not only will using QuickCi make your drabby programs easier to use, but it provides an option for application developers to keep their application code completely separated from their application interfaces.

I created QuickCi because I needed a configuraton interface for Gigatrees, a command line program that can be used to create family tree websites as well as generate other types of genealogical reports. Gigatrees includes dozens of configurable parameters of various data types. In the past I have built a number of user interface applications and found them difficult to manage and maintain. One of the primary goals of QuickCi was therefore to create reusable form elements and a generic definitions file that would define the components of the various configuration pages and then auto-populate those pages without having to manage each page separatly. I have tried to keep any application specific functionality to a minimum, and made sure to deliniate those areas so developers can easily modify or strip them as needed.

QuickCi currently supports a number of basic and some more advanced data types:

• bool
• enum
• integer
• string
• text
• file
• folder
• stringList
• integerList
• folderList
• groupList
• collectionList
The "list" types allow for multiple elements of the same type to appear on a page by supporting adding and removing list items. The "group" type allows a form element to combine multiple elements of other types. The "collectionList" is a specialized group type that includes form elements associated with a blog post. The "collectionList" will display an index of blog post title, each of which will show an "Edit" button that when clicked will display the post edit page.

The structure of the QuickCi distribution is shown starting with the installation folder.

\quickCi
\resources
\app
package.json
sample.xml
\assets
bootstrap.min.css
bootstrap.min.js
foundation.css
jquery.min.js
style.js
\config
app.json
definitions.json
quickci.json
\html
config.html
quickci.html
settings.html
\scripts
app.js
quickci.js
forms.js
hound.js
datatype-nnn.js
\node_modules
(empty)
\user
en.json
settings.json


QuickCi uses XML configuration files, although it could easily be modified to use JSON instead.

The folder structure is determined in part by the Electron Packager. The Electron Packager is used to package your QuickCi application into an executable. When packaging your application, the executable alongwith the various license and library files will be saved to the installation's root folder (in this case quickCi). You can of course rename this folder to match that of your application. The packager will also create the installation's application folder ("resources\app") and save into it the Electron application as electron.asar. The packager will copy your application files into the installation's application folder as well. If you have compression enabled, the entire application folder structure will be compressed into app.asar.

The following is a sample packing call to build a Windows x64 version of the sample application with compression enabled.

call electron-packager ./quickCi/resources/app sample --out=./package --icon=favicon.ico --overwrite --electron-version=1.6.2 --arch=x64 --platform=win32 --asar --win32metadata.ProductName="QuickCi Sample Application" --win32metadata.CompanyName="Tim Forsythe" --win32metadata.FileDescription="QuickCi Sample Application" --win32metadata.OriginalFilename=quickci-x64.exe --win32metadata.LegalCopyright="CC BY-NC-ND 4.0" 

QuickCi is written completely in Javascript using primarily Electron and Node.js libraries. Electron runs in two separate processes, a main process for non-rendered methods and a renderer process. On startup, Electron loads a main script defined in the package.json file as: "main": "scripts/quickci.js" into the main process, which in turn creates a main window that loads an HTML page. Any scripts loaded by the HTML page execute in the renderer process. Both processes use inter-process communication (IPC) pipes to pass named messages back and forth. In general, the HTML page will load menu and form scripts to be rendered. Menu and form listeneres will send messages with or with out data back to the main process to be processed. QuickCi uses three identical HTML files, one for the main page, one for all the configuration dialogs, and one for the preferences dialog. Each HTML page loads jQuery, Boostrap and Foundation into the <head>. The html <body> element is left blank to be filled in later by the form script based on the definition being loaded. The menu and form scripts are loaded after the html <body> element.

In order to configure QuickCi to work with your command utility, several of the configuration files need to be modified, namely: app.json, definitions.json and en.json. The first of these, contains application specific constants. In the case of the sample template:

{
"name": "QuickCi Sample Application",
"version": "0.1.1",
"author": "Gigatrees LLC",
"configRootKey": "Options",
"configMainKey": "Main",
"settingsRootKey": "Preferences",
"settingsMainKey": "Settings",
"homePage": "http://gigatrees.com",
"docsUrl": "http://gigatrees.appspot.com/blog/quickci.html",
"feedbackUrl": "http://gigatrees.com/dashboard",
"page1": "",
"page2": ""
}

The second of the configuration files contains the configurable parameter definitions including their data types, default values, etc. As an example the definitions for the main page shown in the first screenshot is defined in the definitions file as follows:

"Main": {
"fields":{
"OutputPath": {"order": 1, "wrapper":"Main", "type":"folder", "default":""}
}
}
The third of the configuration files, "en.json" is in the user folder and contains the English language translation strings. It includes the translations for the definitions, the preferences, the menu and other general strings. As an example the translations for the main page shown in the first screenshot is defined in the definitions file as follows:

"Main": {
"title":"QuickCi Sample Application",
"description":"Select output path before launching the application.",
"fields":{
"OutputPath": {
"title": "Output Path",
"description": "Select the folder where you want your web pages saved.",
"placeholder":"\\path\\to\\your\\output\\folder\\",
"buttonText":"Browse"
}
}

In order to run QuickCi, you must first install Node.js and Electron. I recommend you do this globally. Once installed, you can download the zip file, and extract it. It will put the distribution into a folder named quickCi. You should then go to the app folder and run npm install from the command line to download the necessary node_modules. You can then run npm start to start the sample application in development mode. The sample application's command line support files are not included in the QuickCi distribution. They are not necessary to start the QuickCi sample application and cycle through its configuration screens. If you want to download a the complete Gigatrees application to fully test out QuickCi in a real world situation, you can download the Gigatrees application from the Gigatrees download page.

The best way to understand how QuickCi works from here is to examine the script files. A few things worth mentioning: The main script (quickci.js) loads all the user and QuickCi configuration files and the default application configuration file on startup. It then creates the main window and populates it with the first defined configuration section (Main). The application configuration file is in XML, so it converts that file to a JSON object using the node-xml2js library. The menu is also loaded onto the main screen. The Options menu is populated dynamically using the definitions and langauges files. The "mode" parameter determines if the menu options are enabled or disabled. The mode parameter is somewhat application specific and can be removed when being used in an application that does not have more than one operating mode. The form is created also using the definitions and langauges files and then inserted into the open HTML page. Form listeners are added to all of the form's input, textarea and submit elements. Each form element is submited to the main process for processing when it is clicked on or loses focus (blur) and has changed value. Forms make use of hidden elements to hold state information such as the last value. When edited, preferences are saved to the settings file automatically, however, configuration changes must be saved explicitly. QuickCi uses a modified version of the node-hound library to watch the configuration file for external changes and offers to let the user reload modified files. QuickCi also keeps track of internal configuration changes and warns you if they try to exit or launch the command line utility first without saving the file. Lastly, QuickCi uses Bootstrap accordians to provide detailed descriptions of configurable parameters when the those parameter headings are clicked on - it's pretty slick. You can see this in action in the last screenshot above.

There are a few bits of code that are still application specific and will need to be modified before use. The app.js file contains some of these functions. The version number for QuickCi is kept in quickci.json. The package.json version is that of the sample application. This is screwy, but I could not get the Electron Packager to use anything other than the version in package.json for the file metadata on Windows. You can report bugs and bug fixes below in the comments sections. Other types of improvements are also welcome.