App-Writer 2 Users Guide

A cleaner App-Writer

The original App-Writer tried to do everything for you. That has good points and bad points. However, when I swapped over to a newer coding architecture for my own apps, I realised that the old App-Writer approach was unnecessary. Instead, App-Writer 2 provides a few core examples containing most of the elements you will need, so you can copy paste to get your own apps running far more easily than having to use an app-generation method.

The basics

All apps need sliders, radio buttons, check boxes, buttons and text boxes as inputs. Apps also need outputs in text boxes, textareas, graphs and graphics.

So here's what you do so that you have all these things ready to use. First, download the zipped up infrastructure a-w-2.zip. Unzip it to a convenient folder (it adds sub-folders containing all the relevant files). You find Demo.html, the more complex DemoY2.html, and the file handling version DemoFile.html (which also has a textarea output). Just double click on any of them and you're running the app.

If you want to see the demo apps online then you'll find the first at Demo.html and can find more sophisticated ones linked from there.

Now open Demo.html in a convenient coding editor. For most of us this means Visual Studio Code, which is free and amazingly powerful. It will recognise that the file is HTML so everything will be nicely colour formatted for you.

The HTML bit

There's a whole bunch of boilerplate stuff that you can look at later. That sets up everything so you have a nice-looking webpage and sliders, graphics etc. that all just work with no effort on your part.

Just scroll down to Quick Start and Credits. You can type in anything you want here to get stuff off to a quick start and give credit where credit's due.

The real stuff starts at <div class="feature-box app clearfix"></div>

The first thing you encounter sets up a graph that covers the whole width of your screen

<div class="panel panel-default"> <div class="row" style="position: relative; height:50vh; "> <canvas id="canvas"></canvas> </div> </div>

Now we start to set up our controls. We want a row of sliders and we want the first one to be linear:

<div class="row"> <div class="six-columns">Lin Input <input type="range" id="SlideLin" class="range-slider" min="1" max="100" value="50" step="0.1" data-type="linear" /> </div>

We want 6 columns in our row as we have 6 controls we want to provide. The first control is a range type, has a unique id SlideLin (always case sensitive), a class of range-slider which provides the nice look at feel. Then we want to specify the min, max, startup value and the step size. Finally we say that it's a linear slide - the next one says data-type="log" as we want that to be logarithmic.

And that's it. You just keep setting up rows of controls, following the examples of buttons, comboboxes etc. in the Demo html. The width of the controls is, in this case 1/6 of the screen spacing. If you choose "two-columns" or "three-columns" then they are, respectively, 1/2 and 1/3 the width. Other size options can be found in the .css files. This idea of laying out controls in a grid is standard good practice.

Back in the general HTML text of your app you might want to include some formulae. If you look at the Demo.html page you will see a nice-looking formula. Look at the .html in your code editor and you will find that it's a MathJax formula.

The final section calls up the necessary JavaScript boilerplate plus your specific app, in this case demo.v2.js

<script src="inc/js/log-slider.v2.js"></script> <script src="inc/js/Chart.min.js"></script> <script src="inc/js/app.new.js"></script> <script src="apps/demo.v2.js"></script>

The coding bit

Now open /apps/demo.v2.js in your code editor

The first thing you see is something about windows.onload. This sets up everything once the html has finished loading, i.e. when you know that all the elements you need are in place. Ignoring the ClickMe, all you have is a call toMain(). Main is very lightweight - it's just there to be called by any event. If you slide a slider or click a radio button, Main gets called. So what does it do?

First it does a saveSetting. This means that if this happens to be your last use of the app before you close the page, your current settings are saved (to localStorage, not to cookies) ready for the next time it's opened. This is very handy! If you ever need to ensure that the settings are your default ones, just un-rem the restoreDefaultSettings line in Main - remembering to re-rem once you've done testing.

Now it assembles all your inputs into one structure called inputs. This keeps everything clean.

Now it's time to do the calculations, so you get a result from calling CalcIt(inputs) . This result contains all your outputs. For example, result.first gets sent to your First text box of output values on the form, and result.plots contains all your graph information.

And that's it for Main. You saveSettings, get inputs, get the result of the calculation from the inputs and send those results to your output boxes or graph.

What does CalcIt do?

Via the magic of structures, CalcIt has all the input values specified in its () portion via the {} notation that allows you to just name the values within inputs (in no special order). So you have everything ready for the calculation. Here there's just a simple for loop to create some graph data. We happen to have two lines in our graph and these are placed into plotOne and plotTwo via a .push() command containing a structure {x:your-x-value,y:your-y-value}. The x: and y: are required by the plotting routine - you get to name the x and y axes later on.

So now we have to plot everything. For the demo, the user can show plotOne, plotTwo or both so we have to have some simple logic for that. The trick is that we need to return an array called plotData. If we just want one plot, we push that onto plotData. If we need both, we push both on. We need to label our lines, so we also push the name(s) of the plot(s) onto lineLabels.

When it comes to plotting, sometimes we want a bunch of defaults - e.g. the graph decides min and max values, sometimes we want to control things. We use prmap to contain plotData and lineLabels, plus a bunch of other things. At the start you can ignore them. Gradually you can start playing with them to get just the sort of graph you want.

Because you always have to label your axes, these are specified as, for example xLabel: 'Distance&m', yLabel: 'Velocity&m/s'. The & is there to show where the units begin. This allows the mouse readout to know what the units are, so as you move your mouse over the plot it might say "At Distance=5m, Velocity=23m/s" which is much nicer than just having a readout saying "5,23" which would have been the default.

The example in demoY2 shows more sophistication. For example it has a second Y axis and other complexities such as text added within the graph and control of whether a graph is "filled" or not.

Loading files

Very often you need to load some data to analyse it, so this is shown in DemoFile.html. File handling is relatively complicated in JavaScript because it's "asynchronous" - you just don't know when your data will arrive, perhaps via a poor internet connection. However, all the difficult stuff is done for you and you never need to touch that code. All you have to code is the reading of your data once it's been converted, by the magic, into an easy-to-handle format.