App-Writer Users Guide
App-Writer Console is designed to be as easy as possible. At the same time, it's rather powerful so you need some guidance about the basic codes for constructing an app and then how to get an app working then how to refine it in many ways.
Specifying the app via Codes
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. All you need to do is specify where you want your inputs and outputs using simple codes to place controls, with their key values, into different rows. App-Writer automatically works out layout issues such as the number of columns per row so your app functions perfectly on any device from phone to laptop.
The codes are simple and are written in "HTML style", though with some freedom - the quotes can be single ' or double " or even omitted if you prefer. Any space in an ID (identifier) which is in quotes will be replaced by underscore:
X ID='MyID' Y='123' Z='456'The first letter is the type, ID is the internal ID code (variable name) used by the Javascript (remember, Javascript is case sensitive) and the label for your textbox or slider, V is the initial Value (when needed, e.g. for sliders), sliders also require: F is From, T is To, S is Step (e.g. 0.01 if you want slider steps of 0.01). P is for "Placeholders" for graphs and G is for Graphics done in an HTML5 Canvas, R is Radiobutton, C is Checkbox, A is textArea (multi-line text output).
So to specify a Slider with ID FlowRate which goes from 1 to 100, starts with a default value of 25 and moves in steps of 0.1 you would have S ID="FlowRate" F="1" T="100" V="25" S="0.1", or S ID='FlowRate' F='1' T='100' V='25' S='0.1' or just S ID=FlowRate F=1 T=100 V=25 S=0.1
(bracket) terms are optional. For the Slider this is L=Y if you want the slider to have a logarithmic scale, for a Textbox it is V=5 if you want this to be an input with a value of 5 (without V it is a readonly output), C=Checked is if you want your radiobutton or checkbox checked, N=5 gives 5 rows of text in a TextArea.
The interpretation of your wishes is as flexible as I can make it. Quotes are optional and to some extent uncloded quotes can be coped with, the order of the parameters (other than the first letter to define the code) is optional and most spaces are ignored. However, the interpretation can't cope with every possible oddity so if the results aren't what you expect, please check that your inputs aren't too unreasonable.
Extracting the HTML and JS
As soon as you have entered any or all of your controls, do Ctrl-A and Ctrl-C to copy from the HTML and JS code boxes to put into your code editor files and save them respectively as .html and .js files. Because you get instant HTML and JS, you can check the look and feel of your app as you build it up.
The name you enter in the App Name box automatically gets inserted into the code and, most importantly, the html expects to find your Javascript in a file called "Whatever you typed in.js". So when you save your html and js files from your code editor, make sure you give them the correct name. You will also have to save the files into a folder with the correct infrastructure, described below.
Also use Ctrl-A and Ctrl-C to copy the OutCode box which gives you a short summary (your codes) of your app requirements. Save this via your code editor. If you later need to modify the app or create a new app with a similar structure, paste the saved OutCode into the InCode box and click the Create from Input button. This will clear whatever is currently in your code boxes and reproduce the original version.
Here is a simple set of inputs for you to try. The values such as A1 or D2 show the column/row where the entry goes. They produce an app with two graphs, two sliders (one of which uses a log range), a text output and a checkbox which is pre-checked. Just click anywhere in the code, do Ctrl-A, Ctrl-C then go to App-Writer, paste into the InCode box and click the Incode button:
Here is the summary of the codes used in the Console.
App-Writer
Development infrastructure
However easy I make it for you to get a basic app, you still need your own infrastructure to be able to write/modify/test your apps. Here are the basics.
A folder with some key infrastructure files
The app works by referring to a few infrastructure files that do all the heavy lifting to invoke various Javascript support files and call the relevant CSS style sheet. In turn this means that some paths have to stay constant. If the app expects to find JQuery in an inc/js folder then it has to be there. But all you have to do is download infrastructure.zip, unzip it into an appropriate location and make sure that the .html and .js files you create go into that folder. The TestApp created using the simple code sample on this page is included in the zip so you can see what the two output files should look like when you try your own first apps. Within the infrastructure files is custom.css. You can use custom.css to override any of the css that is in the large styles.css which is deliberately not minified so you can edit it directly if you prefer.
A coding text editor
In principle you can use any basic notepad to write your code. But it's far easier with a smart coding editor. I currently use Sublime Text but I might move to PHP Storm and others very much like Atom. There are plenty of choices.
Some coding snippets
The code created by App-Writer doesn't do anything other than cope with basic inputs and outputs. You have to provide the science code. The App-Writer Snippets page provides a set of snippets that cover many of the routine bits of coding that I find myself doing within my own apps. If users need more snippets, just ask. And if anyone wants me to add their favourite snippets then I'm happy to do that too.
Notes and Tips
Here are some of the tips you will need depending on your application.
Note that the infrastructure runs on JQuery, which is to say that it's like most other powerful sites. JQuery just makes everything a lot easier, though you have to get used to seeing things like:
FlowValue=$('#FlowValue').val()Tooltips
Relevant items such as textboxes, radio buttons etc. include within their HTML title="Title text". Replace Title text (but leave the quotes) with whatever helpful Tooltip comment you want to appear when yours users hover the mouse above the control.
Sliders versus Textboxes
Most of my apps use sliders rather than textboxes. There are two advantages. The first is that it is much easier to input via sliders on a phone or tablet. The second is that sliding different sliders is a great way to get a feel for what each input does as you get immediate feedback on how the outputs are varying. The drawback is that you often cannot enter a precise value because the slider only has so much precision to cover a large range - this is especially true for very-large ranges when you use Log mode. If your app relies on super-accurate inputs then use textboxes.
Option boxes
Option boxes (Comboboxes, Drop-down boxes) need two bits of special treatment. The first is that you have to add the options within the HTML. The app simply provides one pseudo option so you see the syntax and can add more. The second is that when the user selects a different option this needs to trigger a calculation. An "event handler" is added for each box. This handler calls CalcIt.
CalcIt
Every change of an input (Slider, Textbox, Option/Check/Radio) is sent to the catch-all routine CalcIt. This does three key things.
- It saves all the current settings to localStorage, the safe (sandboxed) place to store local data, so that those settings are available next time the app is run.
- It reads all relevant values of sliders, textboxes, option/check/radio and assigns them to the variable name provided by your ID.
- The default JS also puts some dummy data into any graph outputs that you have specified and draws a simple graphic if you use a Canvas. These functional prototypes will save you a lot of coding time.
Obviously you can feel free to take all/any of these functions out of CalcIt and/or redirect different events to different routines.
Flot graphs
The graphing is done via JQuery.Flot, a powerful graphing utility. To supply the graphing data you simply need to fill the point arrays, e.g. PPts1, by pushing in new pairs of values. So if you are in a loop where x goes from 1 to 100 and y is calculated by your code, you simply PPts1.push([x,y]). Flot does other types of graph but I've never needed them other than a pie chart in one of my more obscure apps. When you move the mouse over the graph the values are automatically shown. The functional prototype gives a readout saying something like "X=3, Y=5". You can readily change this to, say, "μ1=3 M, ΔG=5 kJ/mole", i.e. the code handles Greek symbols, sub/superscripts etc. and units are specified.
The graphs are set up with both X and Y axes plotting from 0 to 100. For example, the X axis is specified using: xaxis: {min: 0, max: 100, axisLabel: "X",}. If you take out either or both of min and max Flot will autoscale the axis, otherwise you need to work out those values beforehand or via an algorithm. Obviously you provide your own axis label which, again, handles Greek characters, sub/superscripts etc.
If you have multiple plots on one graph you need to provide labels to distinguish them. Instead of the default code which is:
$.plot($("#placeholder1"),[{ data:PPts1}], options1)you use something like
$.plot($("#placeholder1"),[
{ data:PPts1,label:"Curve 1"},
{ data:PPts2,label:"Curve 2",lines:{show:true}, points:{show:false}}
], options1)where the second set of data are plotted with lines but no points (or whatever you want by changing between true and false).
The JQuery.Flot website has many examples to help you customise your code.
Canvas
Drawing graphics onto the HTML Canvas can be a bit tedious using standard Canvas syntax, so the apps use jcanvas which has clearer syntax, similar to just about any other drawing syntax. You can feel free to swap between the two modes. To get an idea of how to code for Canvas, look up the jcanvas site or look at the basic example (a circle and rectangle) I provide as a functional prototype.
Data outputs
Users often want to process your output data, so how do you give it to them? The strength of Javascript within HTML5 is that it is safe - it can't damage your (corporate) computer. This means that it is impossible to save data directly to your device. It also means that you cannot put information straight onto the Clipboard. You can save the data to a remote server then download it - but it's a hassle and raises concerns about who or what is looking at your data. So my standard method is to use a TextArea box which allows multi-line output which can be copy/pasted. And, of course, that's how the HTML and JS are output in App-Writer. It's not ideal, but it's pretty good.
Javascript for those who've not seen it before
I can program in C, Fortran, Visual Basic, C#, PHP and Javascript. Other than some automatic habits, swapping between them is no big deal. Visual Basic has Dim to specify a variable, Javascript has Var. C# has Math.Sqrt, Javascript has Math.sqrt. In C and PHP, a closing ; is required, in Javascript it is optional and in Visual Basic it doesn't exist. The "If" and "Loop" constructs in Javascript are identical to C etc. Visual Basic is not case sensitive, the others are.
The biggest difference is that in Javascript you don't specify whether something is an integer, double or string. It works it out for itself. You don't even have to declare something via Var, you can just use it. This is great for quick coding but allows subtle dangers to creep in. For example if you just read a number from an input text box, you probably have to use parseFloat() to make sure Javascript gets the idea that this is a number not a string. Also, Javascript is amazingly free with arrays and you can do all sorts of cool stuff unimaginable in more buttoned-up languages.
My most common catastrophic error if I happen to be in Visual Basic thought mode is to have a loop of i going from 1 to 100 and an if statement saying if(i=50) blah blah. This simply forces i to equal 50, so the loop continues for ever. The correct syntax, of course, is if (i==50).
For those who come from a purely Fortran background, the bad news is that all those GO TO statements are very hard to get right as Javascript, like all modern languages, has no equivalent.
Debugging
Debugging is all done within your browser. If you've never tried F12 (on most browsers) then you've never seen the wealth of information that is open to you in the browser's Developer Tools showing you what is going on behind the scenes. In particular, in the Console view you will see all the errors due to missing files (such as core css or js files) or to problems running the Javascript.
The simplest debugging tool is to include a line of code something like:
console.log("Here are the values in the loop",i,alpha,beta)where you might have a for loop using the index i and you are interested in why your calculated values alpha and beta are having problems.
Modern browser debuggers are immensely powerful so it is worth going over a tutorial to know how to use them.
Of course, make sure you have a bunch of browsers in which to test your code. Chrome and Firefox nearly always work well. IE/Edge are notorious for behaving badly and if you hit an IE problem a search will usually find that others find IE's behaviour as exasperating as you do.
