User Manual

#Introduction

Meteoris is a Realtime Javascript Boilerplate and Code Generator built on the Meteor JS Framework v1.0. It gives you a running start for your Meteor apps by making use of many of the most recommended packages.

##Why Use Meteoris

• Generate CRUDSS (Create, Retrieve, Update, Delete, Sort and Search) code and templates directly from data definitions, saving yourself large amounts of repetitive hand coding.
• Roles Based Access Control predefined in your app. User and Role CRUDSS is already done for you!
• Provide MVC/MVVM/MVP boilerplate for meteor v.1.0.x+?
• Begin your development cycle with shared boilerplate (standardized structure) maintained and kept up-to-date by the Meteoris community
• Start off with many of the best-known Meteor packages installed and being used properly by experienced developers.

###Folder Structure

Meteoris uses standard Meteor folder structure, with some minor modifications.

├── client                \# All client-side dynamic artifacts
│   ├── assets             \# Client-side widgets
│   ├── css                \# Static stylesheets
│   ├── routers            \# Business route definitions
│   ├── sass               \# Styling generator
│   ├── templates          \# Application structure templates and helper code
│   └── views              \# Business templates and helper code
├── lib                   \# Client & server joint action artifacts
│   ├── applications       \# Routing and housekeeping
│   ├── collections        \# Data strucutre definitions
│   ├── controllers        \# Control data movement between collections and views
├── public                \# Your static content for public consumption
│   ├── font               \# fonts
│   ├── images             \# images
│   └── svg                \# vector graphics
└── server                \# Server-side folder for secure services

#Documentation

##Audience

This document addresses the needs of readers who already have some development experience using JavaScript and Meteor. To have already followed through the official Meteor tutorial is the minimum requirement.

##Installation

1. Meteoris depends on prior installation of Meteor v.1.0+. Probably the command you need is as follows, but you should check the Meteor Reference Manual to be sure nothing has changed since the time of writing.

    curl https://install.meteor.com | /bin/sh
   

2. Git clone the Meteoris GitHub repo:

    git clone https://github.com/radiegtya/meteoris.git yourProjectName
   

3. Prepare for networking. Edit the file ./lib/applications/meteoris/configs/config.js. Change these two lines to set the base URL for internal links and the location of your MongoDB server if you do not wish to use the local one.

    baseUrl: 'http://yourMeteorServer.yourCompany.tld:3000',
    mongoUrl: 'mongodb://yourMongoServer:27017/yourProjectName/',
   

   You can use localhost:3000 here, but the site will not work well (eg, no images) if accessed from some other host.

4. Start up Meteor by typing this command ...

    meteor
   

5. Type one of the following URLs in your browser to open the demonstration app.

    http://yourMeteorServer.yourCompany.tld:3000
   

   or

    http://localhost:3000
   

6. To login in to the admin or demo accounts, use these credentials:

   UID	PWD
   admin@meteoris.me	admin
   demo@meteoris.me	demo

   You can also establish your own account from the registration page.

Mugen - the Meteoris UI Generator

Meteoris has an added advantage above other boilerplate repos you might be invited to use. It will generate basic Create, Retrieve, Update, Delete, Sort and Search code (CRUDSS) from within your developed application using a simple interface.

The files are immediately available for full use, and Mugen can be disabled for demos and removed for production, easily. It's boilerplate on steroids, so to speak.

To try it out, either go to http://localhost:3000/mugen, or use the menu as shown :

This is the Meteoris UI Generator a.k.a Mugen. It will generate a more or less complete set of files for managing a new data base model. You simply enter some basic field definitions and press the "Generate" button.

NOTE : Be aware that Mugen is not yet a two-way tool. For now, it generates the code then forgets everything about your data structure. Obviously, it should work from pre-existing, or imported, field data in order later to regenerate the files with an updated data structure.

###Configuring for Development or Production Environments

Mugen is a development tool that generates run time code, and so it is too dangerous for production use. You can activate or deactivate Mugen in the file lib/applications/meteoris/configs/config.js by setting the parameter "activateMugen" true or false. You do not need to stop and start Meteor, the change takes place immediately.

Attempts to return to Mugen after it has been disabled will take users to your default "Not Found" page as shown :

###Default Generated User

As mentioned above in Installation, Meteoris provides two predefined users: admin and demo. The list of all users is only accessible to you when you have logged in with admin privileges.

Once you have admin privileges the User menu opens the user list editor, which permits to insert, update and remove users. (In a production system, of course, the menu item ought to be hidden from unauthorized users.)

##CRUDSS Generator

The preeminent feature of Meteoris is Mugen the CRUDSS generator UI.

When enabled, you can reach it through the menu bar, or by opening the URL, http://yourMeteorServer.yourCompany.tld:3000/mugen.

In the pages that follow we will develop a simple real world case of two collections: "Jobs" and "Employees". The table structure will be "one-to-many", where a single Job may have one or more Employees.

###Jobs

By convention, we will use lower case lettering for the table/collection name (jobs/employees), but title case lettering for the collection/model code (Jobs/Employees). We will generate the Jobs collection first. The schema will look like this :

The points to notice are :

• Collection Name -- jobs
• Name -- title
• Type -- String
• Required -- checked (indicating that a title is obligatory)
• Label -- blank
• Belongs to Collection -- blank
• Relation Key -- blank

The table in the bottom half of the page provides the target storage location of the five categories of files which will be generated. You can limit generation to a subset of those five.

The next step is simply to press the Generate button. Give it a few moments to complete, then view the CRUDSS page for jobs at http://yourMeteorServer.yourCompany.tld:3000/jobs.

With that done, you have a new Collection created in MongoDB and full management power over it.

Here you can see insert/create in action, with built-in validation.

Once the job definition is saved successfully you are redirected to the view page.

When multiple records have been inserted you, as admin user, can experiment with updating, removing, searching, and sorting.

###Employees The next step is to generate the CRUDSS code for "Employees".

To do it, simply open up the mugen page again and fill the various fields as shown :

For this collection we will have name, jobId, and birthDate fields. The name field is treated the same as before, but the jobId field is special. We fill the Belongs to Collection field with "Jobs". This indicates that jobId is to be a foreign key on the Jobs collection.

It is no coincidence that this looks just like the DDL of RDBMS systems; under the hood, Meteoris uses the Meteor package aldeed:simple-schema to enforce relational integrity.

Caution : Un-addressed at this point is the question of obtaining the correct key. We will return to it shortly.

Also interesting here, is the birthDate field. When Mugen encounters a "Date" type, it generates all the code for a working "datepicker" widget.

Congratulations. We have now generated our Employees module.

Click the insert button to open the insert page.

Now we need to get the correct value for the dropdown list. We don't have the job title here because we already indicated that employees would be related to their job by jobId, not title and we haven't told Meteoris to use title. Nevertheless Meteoris has gone as far as it can with it.

In this next image you can see that Meteoris has already obtained the record key for each Job; it just doesn't know which attribute to use.

The dropdown shows a bit of helper text instead of a list of job titles. It says...

_Using jobs.name here for record "Blaa9612Blaaa". Correct it in the file : client/views/employees/form.html

This demonstrates that the application is working and has successfully read job record IDs from the database. It also points directly to the file that needs to be edited. All that remains is to search for that text within then file, in order to get to exactly the line requiring attention.

In the file, client/views/employees/_form.html, we find lines of code like these :

    <select id="jobId" class="form-control">
      <option value=""></option>
      {{#each jobs}}
        <option value="{{_id}}" {{selected ../jobId}}>{{name}} Using jobs.name here for record "{{_id}}". Correct it in the file : client/views/employees/_form.html</option>
      {{/each}}
    </select>

The change is simple enough: replace {{name}} with {{title}} and delete the "training wheels" text :

    <select id="jobId" class="form-control">
      <option value=""></option>
      {{#each jobs}}
        <option value="{{_id}}" {{selected ../jobId}}>{{title}}</option>
      {{/each}}
    </select>

We have an employee inserted successfully, albeit with the job title still blank, as the next image shows. Hence the next task ...

Now we can get our hands dirty again with a tiny bit more coding.

The page http://server:3000/employees/index provides clients (users) with a view into the Employees collection, so the corresponding source file can be found at the similarly named location client/views/employees/index.html. This will be familiar to application developers who have used Ruby on Rails, Python Django or PHP frameworks like Yii or Laravel.

Notice, of course, that this is not a complete HTML page. Rather it is a Meteor template named employeesIndex. Find the table body tag tbody in the bottom half of the template, then look for job.name and replace it with job.title.

    <tbody>
        {{#each models}}
        <tr>
            <td><input type="checkbox" class="checkAll" value="{{_id}}"/></td>
            <td>{{name}}</td>
            <td>{{job.name}}</td>
            <td>{{meteorisFormatter 'date' birthDate}}</td>
            <td>{{createdUser.profile.name}}</td>
            <td>
                <a href="{{pathFor 'employeesView'}}" class="btn btn-default"><i class="glyphicon glyphicon-eye-open"></i></a>
                <a href="{{pathFor 'employeesUpdate'}}" class="btn btn-default"><i class="glyphicon glyphicon-pencil"></i></a>
                <a id="btnRemove" class="btn btn-danger"><i class="glyphicon glyphicon-trash"></i></a>
            </td>
        </tr>
        {{/each}}
    </tbody>

Having made that change, the employee index should now look like the next image, with the correctly displayed job title -- not just an id.

It should be evident that all the hard, error-prone, donkey work of developing a CRUD page, is handled generically by Mugen. Compare that to the tedium of hand-coding jQuery widgets to create similar pages -- over and over again!

##Role Based Access Control (RBAC)

Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within an enterprise. In this context, access is the ability of an individual user to perform a specific task, such as view, create, or modify a file. Roles are defined according to job competency, authority, and responsibility within the enterprise.

(http://searchsecurity.techtarget.com/definition/role-based-access-control-RBAC).

It's another generic task that's almost identical from one app to another. You should not have to do it. To help ensure you "DRY" (don't repeat yourself), Meteoris provides RBAC management via graphical user interface rather than leave you with manual coding.

If you logout now, you will find you still have partial anonymous access. URLs like http://localhost:3000/jobs/index and http://localhost:3000/jobs/view remain accesible, while http://localhost:3000/jobs/update redirects to the Error 403 handler page. The same will happen if you try to access insert and remove action.

Login using admin@meteoris.me and all actions become available again. That is RBAC from the user's view point. Now we'll look inside to see how it is done in Meteor, and how Meteoris makes it easier still.

Drop down the menu Mugen menu, select the Role Collection sub-menu and observe that the role collections "jobs" and "employees" have already been registered by the code generator.

Notice that this page, and the other Mugen submenu items, are CRUDSS pages too. So, even though the code generator added records here, you are not dependant on it for that.

The key to understanding Meteoris RBAC is the page Mugen Role Actions. It allows you to establish a named relation ("action") between a single user group and a single collection. Intentionally, it is a grammatical construct: Subject, Verb, Object ==> Group, Action, Collection ==> "Human Resources Manager" can "Update" "Jobs". In your application's code you will need simply to ask if the user is allowed that action. Internally Meteoris will determine two things: a) the specific action on the collection is allowed for the group and b) the user is a member of it. The action is blocked unless both are true.

This diagram should make it more clear ...

As the diagram suggests we need four CRUDSS pages and corresponding collections :

What it is | Mugen Name for it | Menu >> Submenu | URL
--- | --- | --- | ---
list of names of collections | Mugen Role Collections | Mugen >> Role Collection | /mugenRoleCollections/index
list of names of groups | Mugen Role Groups | Mugen >> Role Group | /mugenRoleGroups/index
named relations between roles and collections | Mugen Role Actions | Mugen >> Role | /mugenRoleActions/manage
list of users  | Users | Users | /users/index

##RBAC Usage scenrio

Let's now walk through a typical authorization scenario with the following steps :

1. Define an authority group
2. Join a user to that group
3. Allocate authorized actions by the group to a specific collection
4. Check that the user can do as authorized and also cannot do what is not authorized.

The steps in each case need almost no explanation.

###Define an authority group

From the Mugen menu open Role Group, or visit http://localhost:3000/mugenRoleGroups/index, then click the green insert button.

Supply a name for the new role group, eg Human Resources Manager, then click the green Submit button

###Join a user a group.

We can immediately add Users by clicking the green Users Insert button.

Fill in the details, select the appropriate group and hit the green Submit button.

We have now created a group and joined a user to it. So we now have a Subject for our grammatical structure.

###Authorize a group to a collection

Now we need a Predicate, which consists of a Verb that acts upon an Object. We defined our Employees object earlier using our CRUDSS tools. The list of all collections looks like this :

We will not edit the collection list; it is there primarily as a reference. To define our Verb we must use Mugen Role Actions (from Mugen >> Role).

This CRUDSS management page let's us work on all the allowed actions for a given group on a given collection, in this case admin may index, view, insert, update and remove records of the user collection.

Our immediate task is to declare that Human Resources Manager may insert and update records in the the collection jobs. Selecting Human Resources Manager from the top dropdown, jobs from the second and clicking Search shows that no action relations have been defined.

We can declare action relations using the "Add new Action Name" field, and clicking Save.

###Verify user's privileges.

There are 5 general privileges (actions) you can specify:

• index - see the list of all collection members
• view - see all details each collection members
• insert - create a new collection member
• update - alter any existing collection member
• remove - delete any existing collection member

However, some collections have special privileges, eg, all users may view their own profile.

---

---

Meteoris - Generated Code Review

Why meteoris is good not only for CRUD code but also has a good structured code like ruby.

See this example for jobs

This generated code are:

In the routers

In the Views

in the lib/collection

in the lib/collection/controller

in the servers

For more detailed look, You can watch my documentation video.