WABuR Tutorial Lesson 1

October 8, 2017 · View on GitHub

This first lesson of the WABuR Tutorial covers.

Application Design

The first step in building any application is deciding what to build. WABuR or simply WAB will follow an object based design. With that in mind, building a blog will require blog entries so an Entry will be the primary object-type in the application.

tell me more...

WABuR Components and Terminology

WABuR is designed as a Model View Controller (MVC) system. At the core is a Ruby Controller that executes the business logic of the app. The Controller resides at the server-side. To support the Controller, an HTTP web server and a Database are needed. This is provided by the Runner-Shell combination as denoted in the WAB Components diagram. The view aspect of the MVC pattern here is a JavaScript implementation at the client-side in a browser. JavaScript essentially implements a separate display application that interacts with the Controller with messages that are exchanged via the HTTP server conforming to a defined API.

tell me more...

Development Environment

For development the pure Ruby Runner and Shell are used. The pure Ruby Runner is in the bin directory and is named wabur. A browser will also be needed to test the View or UI.

tell me more...

File and Directory Organization

WABuR projects follow a suggested layout. Not all directories will be present in this lesson as some wabur and other runners will supply if not found in the directories.

The files for this lesson will be in the lesson-1/blog directory which will be laid out as indicated.

blog
├── config
|   ├── wabur.conf
|   ├── opo.conf
|   └── opo-rub.conf
├── lib
|   └── ui_controller.rb
└── site
    ├── assets
    |   ├── css
    |   ├── fonts
    |   └── js
    └── index.html

tell me more...

Implementation

At the core of the system is the Controller. The Controller is a bridge between the View and Model. It presents a business object perspective to the View component and maps business object to the Model storage objects.

The Model provides access to stored data. In WABuR the Model is accessible to the Controller through the Shell. The stored data is JSON and can be data stored from other applications or data managed only by the Model.

The View runs in the client or in the normal case, a browser. The WABuR reference implemenation provides HTML and JavaScript using Ruby code as well as JavaScript libraries.

All files necessary are generated by creating a project directory or creating a project in GitHub and cloning it. Then cd to the project directory. Assuming the project was called blog execute the following commands.

$ mkdir blog
$ cd blog
$ wabur init Entry

This will generate all the files needed to run but since the Entry type has not been defined it will be a rather boring display.

To start from scratch, locally, use wabur new mode. Simply run the following to create a project directory at './blog' and initialize controllers for type Entry:

$ wabur new --base blog Entry

To define the Entry type the lib/ui_controller.rb is edited. Two attributes will be added, 'title' and 'content'. After opening the file notice the creation of a RestFlow where the second argument is a template for the Entry type. The only attribte is the kind of record an Entry is. Of course the value is 'Entry'.

# encoding: UTF-8

require 'wab/ui'

class UIController < WAB::UI::MultiFlow

  def initialize(shell)
    super
    
    add_flow(WAB::UI::RestFlow.new(shell,
                                   {
                                     kind: 'Entry',
                                   }, ['$ref']))
  end

end # UIController

Go ahead and add the title and content to the template. The values are the default values for the attribute. Notice the 'content' as four newlines in the content. This is an indication that the display item should be a TEXTAREA with four lines,

The third argument to the RestFlow initializer is a list of attribute paths will be displayed in a list view.

    add_flow(WAB::UI::RestFlow.new(shell,
                                   {
                                     kind: 'Entry',
                                     title: '',
                                     content: "\n\n\n\n",
                                   }, ['title', 'content']))

The generated configuration implements a UI flow as illustrated. Note the boxes in the diagram represents displays and the links between then represent transitions from one display to another triggered by an action such as pressing a button.

tell me more...

Running

The wabur Runner is used for this lesson. To start the Runner, the wabur gem must be installed or the wabur source must be available. Assuming the gem is installed and the run location is in the blog directory the command to run the application is:

$ wabur

That will start the Runner listening on port 6363 and storing data in the wabur/data directory. Open a browser and type in http://localhost:6363 and observe an empty blog entry list. Use the Create button to create a new Entry and the other displays and buttons to experience the new application.

tell me more...

Index.html

Since this is your blog a more customized front page is probably preferred. So far there is no site directory or an index.html file. Those files are virtual, by default. In other words, they're accessed from within the wabur gem itself.

To customize these files easily, they can be generated at the current WAB workspace by running the wabur init command with a --site option.

$ wabur init --site

Pro-tip: Alternatively, the --site option can be passed to wabur new as well, to generate these files along with the config files and UI Controller.

The index.html should now be present as site/index.html. Make some modifications and try running wabur again and the new files will be used. The CSS files and the JavaScript can also be modified.

There are a few things that should be present in the index.html file. For this lesson the wab CSS is used so a link in the head is needed to pick those up. A div element with an id of view is also needed so the wab JavaScript knows where to build displays. Finally a script tag is needed to pull in the wab UI JavaScript.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Welcome to My Blog</title>
    <link rel="stylesheet" type="text/css" media="screen, print" href="assets/css/wab.css" />
    <link rel="stylesheet" type="text/css" media="screen, print" href="assets/fonts/wabfont/style.css" />
  </head>
  <body>
    <header class="header">
      <div class="logo">
        <span class="brand">My Blog</span>
      </div>
    </header>

    <main class="content">
      <div id="view" class="view-content">
      <!-- contents -->
      </div>
    </main>

    <footer class="footer">
      <div class="attribution">
        Powered by <a class="brand" href="https://github.com/ohler55/wabur">WABuR</a>
      </div>
    </footer>

    <script src="assets/js/ui.js" type="module"></script>

    <script nomodule src="assets/js/systemjs/system.js"></script>
    <script nomodule src="assets/js/transpile.js"></script>

  </body>
</html>

Now when wabur is run the frame identifies the page as your blog.

Shortcut

A script is available in the wabur github repository that will execute all the steps in this lesson. It can be used to compare what you have already done in the lesson or to shortcut the lesson if desired. The script is script/run-lesson-1. If running without the gem installed please read the comments at the start of the script.