coServ Tutorial — Part I

This is the first installment of a three part tutorial which will use a TODO list to demonstrate how to build web apps using coServ.

Purpose:

1. familiar with coServ cli and use the cli tool to create a web app.
2. familiar with the file structure of a coServ web application.
3. learn how to create the model, view and controller of a palet.

Note: This tutorial works for the formal release v1.0 and up. This does not work for the older versions (version < 1.0).

What is a palet

Before we get started, you may need to know what is a palet. A palet is a web UI component which can render a piece of HTML fragment. coServ divides a web page into smaller parts with each part rendered by a palet. Using this “divide and conquer” strategy, web pages can be developed in a more manageable and easier way.

coServ CLI

Using the coServ CLI tool can help first time developers to get started quickly. So let’s do it. Assume you’ve installed node.js already. Then install coServ CLI globally:

pm install -g @coserv/cli

Then change to a directory (or create one) where you’ll save your coServ web app. Inside the intended directory, you can generate a new web app by running the following command in a terminal:

xs create tutorOne

“tutorOne” is the code name of your app. You can name it anything you like. Once done, you’ll find a new ‘www’ directory in your work directory. The next step is to start coServ:

xs service

Now point your browser to http://127.0.0.1:4040, you should see something like:

Congratulations! You’ve created a web app (named ‘tutorOne’) and made it run. Read on to see how you can build a TODO app from that.

In the remaining part of this tutorial, we’ll create a palet called ‘todo/list’ which can list all the TODO items.

Build your own palet

Every web page on coServ is built of palets. Each palet is implemented with a node.js module (but with the .xs postfix), and a palet file should be stored under the ‘themes/default/palets’ directory (let’s call it the PALET directory). coServ does not use routers because routers could be ambiguous and difficult to manage when things get complicated. Instead, each palet on coServ is given an URL directly mapped to (relative to the PALET directory) the palet file. In our example, the file path of the TODO list palet will be:

www/tutorOne/themes/default/palets/todo/list.xs

Inside the palet source file, we can create the view part of a palet:

exports.view = function(model)  {
    let root = xs.root()
                 .add('h5', 'My TODO List')
    return root
}

That will create a ‘div’ tag as the palet’s root element. xs.root() is to create a HTML element serving as the root element of a palet. There should be one and only one root element in a palet.

Next let’s display the TODO list. We’ll first make up some TODO items so we have something to show. The data model of a palet can be created using the exports.model() function:

To make it simple, we use an array to store the TODO list. For a real world application, you may want to use a database to store the appication data (in our case, the TODO list).

For each TODO item, we’ve assigned four properties to it:

* title: name of the TODO item.

* start: the time we plan to do it.

* end: the time we’ve actually done it.

* checked: true if the TODO item is checked (done).

With the data model ready, we can move on to display it. We’ll first create a function to generate the HTML representation of a TODO item. For each TODO item, we’ll show an icon to indicate if the item is checked or not. We’ll also display the title of TODO items. Below is the sample code:

Lines 10 ~ 12 create a ‘div’ element for a TODO item, and lines 14 ~ 17 display the title. If the item is checked, we’ll display the title as crossed-out. That’s what lines 14 ~ 15 are doing. Lines 2 ~ 7 are to setup tag attributes so the TODO item will be displayed as a bootstrap list item. We fill in attributes that bootstrap would expect. Line 8 chooses the icon we desire, based on the “checked” property of a TODO item.

With the rendering job of each TODO item is done, we can go back to the view() function to finish the view part of our first palet.

Lines 5 ~ 7 loop through the TODO list, and for each item we’ll call the showItem() function to render it. All TODO items will be appended to the ‘ul’ element and the ‘ul’ element is added to the palet element tree. Finally, we return the palet root element so coServ can display the palet.

If everything goes well, outcome of the page should look like:

When you’re ready, here is the part II of the tutorial.