helloxl

* HelloXL - a simple sample ReactJS project to learn from.

** Overview.

There's a wealth of introductory React material out there, much of it
is wonderful.  There's even great tools, like [[https://github.com/facebookincubator/create-react-app][create-react-app]] that
will set up a new React app for you.  The intent of this repository is
not *that*.  It is rather intended to be used to give new comers a
quick tour of what a React application looks like, from the code point
of view.  It is inherently trivial. 

** Prerequisites
*** Setting up or Linux computer
If you're on Arch linux, Ubuntu or Red Hat / Centos, this projects
Makefile should be able to set up everything you need.  Be warned that
this will result in Docker and Go being installed on your machine.

*** Setting up on Mac

**** 1. Install HomeBrew

If you already have HomeBrew, you can skip this.  The following should
all be carried out in a terminal/console.

First install homebrew
#+BEGIN_SRC sh
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
#+END_SRC

Then update HomeBrew's repository
#+BEGIN_SRC sh
brew update
#+END_SRC

Then use a text editor to add the following to your =~/.bash_profile= file:

#+BEGIN_SRC sh
export PATH="/usr/local/bin:$PATH"
#+END_SRC

Finally you'll need to source your bash profile:

#+BEGIN_SRC sh
. ~/.bash_profile
#+END_SRC

**** 2. Install NodeJS
Using HomeBrew you can now install NodeJS.
#+BEGIN_SRC sh
brew install node
#+END_SRC

**** 3. Install Go
#+BEGIN_SRC sh
brew install go
#+END_SRC

**** 4. Optionally install Docker for Mac
If you want to install docker on your mac, and run this in a linux container, then [[https://www.docker.com/docker-mac][follow these instructions.]]

*** Setting up on Windows

Follow the instructions [[http://dilbert.com/strip/1995-06-24][here]].  Seriously though, the secret is to bang the rocks together guys.

** Running helloxl.

If all the above works out correclty, you should be able to just run:

#+BEGIN_SRC sh
make
#+END_SRC

.. and wait for that to finish.  You should then run the tests to see
that everything is working as expected:

#+BEGIN_SRC sh
make test
#+END_SRC

Finally you have a choice - either run the app locally, or run it from
a docker container.

*** Running locally
If all the above steps worked you simply need to run:

#+BEGIN_SRC sh
./helloxl
#+END_SRC

.. and point your browser to http://localhost:3000 to see the
application running.

*** Running in a docker container

If you installed docker, then you can also:
#+BEGIN_SRC sh
make docker-run
#+END_SRC

.. this will trigger the building of a new docker image, and
eventually start it, mapping the containers port 3000 to localhost's
port 8080.  When it's ready und running you'll see a message that looks like this:

#+BEGIN_SRC sh
2017/04/27 13:15:15 Starting in development on 0.0.0.0:3000
#+END_SRC

Now you should be able to access the app at [[http://localhost:8080]].

When you're done with the server you can kill it with =Ctrl-c=.

** A breif introduction to the code.
*** =jsx= directory

The =JSX= files are the ReactJS code.  =JSX= is a special extended
version of JavaScript used by ReactJS to allow the embedding of HTML
style tags in code.

React is essentially a way of making new tags for an HTML page, and
controlling the way state flows in and out of them.  To the consumer
of these tags they appear exactly as native HTML tags - you can set
properties on them, and respond to events from them.  These tags are
called =Components= and they can either be implemented as a simple
function that takes a =props= argument (See, for example =Sheet=,
=Row=, and =Column= in =jsx/xl.jsx=), or as a class that inherets from
=React.Component= and has (at least) a =render= function that returns
tags (See =XLApp= in =jsx/xl.jsx=).

The file =jsx/app.jsx= is the place where the React code get's bound
to the page (See the =run= function).  Note that this happens in
response to the event indicating that page is fully loaded - this is
important.

*** Go files

Go (often referred to as "Golang" to ease googling) is a compiled,
statically typed programmnig language that can be seen as a sort of
"easier C".  It's the fasting growing programming language in the
world right now (both in commercial and hobbiest use).

The topic here is not Go, so I won't go into detail, but essentially
the files that end in the =.go= extension are source code (and unit
tests) for a small server program that, when compiled, creates an
executable called "helloxl" in the projects root directory.

If you invoke =helloxl= it will start listening on all interfaces of
your machine on port 3000.  If you use the =make docker-run= approach
to running the program, we'll bind the localport 8080 to the
containers port 3000.

*** =.babelrc=
Babel is a general purpose compiler for javascript.  In the React
world it's used to convert JSX into plain ol' JavaScript.  The
=.babelrc= file contains the configuration of babel for the projcet.
It's an extremely simply JSON file that just tells babel which plugins
to use. 

*** =Dockerfile=

Docker is a way of simplifying the constuction and use of containers.
It's not relevant to this projcet, but I added it as I was deploying
the code into a Kubernetes cluster for my own purposes.  The
=Dockerfile= simply describes how to build a container for this
appplication.  You can safely ignore it.

*** =Makefile=

GNU Make is a tool for automating build processes.  Here the
=Makefile= takes care of all of the set up, compilation, testing and
even running of the application inside Docker (if you so wish).  If
you wish to know how to setup a React + Go project from scratch, you
can read the =Makefile= and see what is done.  You're probably better
off just using something like [[https://github.com/facebookincubator/create-react-app][create-react-app]] though.

To make the =Makefile= do something you invoke it by running =make= at
the command line.  You can restrict it to handling a single target
(plus any dependencies) by added a target name to the command as per
=make golang-test=.

*** =node_modules= directory

This is a directory maked by =npm= (The NodeJS package manager), here
you'll find all the dependencies required to make React work.
Normally speaking you'd never need to look in here, but you can learn
a lot about JS coding by reading the contents.

*** =public= directory

Static content to be served for the web page lives here.  Included CSS
files, but also the generated javascript that babel makes from the
=jsx= files we write for the react app.  You don't need to look at
this, just know that it exists, and it's where we load our javascript
from.

*** =README.org=

This file!

*** =views= directory

The sever app has templates for HTML pages here.  

In =./views/includes/header.tpl= you'll find the =<script />= tag that
loads our generated =app-bundle.js= file, which contains the plain JS
version of all of the =jsx= code in this project.

In =./views/index.tpl= you see that we include the header, and we define a div to hold our application, it looks like this:

#+BEGIN_SRC html
<div id="app" />
#+END_SRC

*** =webpack.config.js=

The =webpack= program is responsible for bundling up all our generated
javascript into one bundle (when it's generated you'll find it in
=./public/js/app-bundle.js=.  The configuration file is written in
JavaScript and tells =webpack= where to find the =jsx= files, and
where to put the output bundle.  The =source-map= is also configured
here, which allows the browser dev tools to map errors in the
generated JavaScript files back to the =JSX= code.