v0.2.0

See CHANGELOG.md

Issues:
------
* fixes issue #2 - news page
* fixes issue #6 - terms and conditions
* fixes issue #9 - documentation
* fixes issue #10 - more documentation

CHANGELOG.md

@@ -6,6 +6,15 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased][Unreleased]
 
 
+## [0.2.0][0.2.0] - 2016-04-24
+
+Added:
+
+* Add terms and conditions
+* Add pages for *news*
+* Add more documentation on hacking on the code
+
+
 ## [0.1.0][0.1.0] - 2016-03-25
 
 Added:
@@ -21,6 +30,7 @@ Added:
 This is the very first version.
 
 
-[Unreleased]: https://github.com/forfuturellc/mmtc-ke/compare/v0.1.0...HEAD
-[0.0.0]: https://github.com/forfuturellc/mmtc-ke/compare/v0.0.0...HEAD
-[0.1.0]: https://github.com/forfuturellc/mmtc-ke/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/forfuturellc/mmtc-ke/compare/v0.2.0...HEAD
+[0.0.0]:https://github.com/forfuturellc/mmtc-ke/releases/tag/v0.0.0
+[0.1.0]:https://github.com/forfuturellc/mmtc-ke/releases/tag/v0.1.0
+[0.2.0]:https://github.com/forfuturellc/mmtc-ke/releases/tag/v0.2.0

HACKING.md

@@ -0,0 +1,123 @@
+# Hacking the Application
+
+Before proceeding any further, read the following documents:
+
+1. [CONTRIBUTING.md][contrib]: contributing source code
+1. [CODE\_OF\_CONDUCT.md][coc]: code of conduct
+1. [LICENSE][license]: software license
+
+[contrib]:https://github.com/forfuturellc/mmtc-ke/blob/master/CONTRIBUTING.md
+[coc]:https://github.com/forfuturellc/mmtc-ke/blob/master/CODE_OF_CONDUCT.md
+[license]:https://github.com/forfuturellc/mmtc-ke/blob/master/LICENSE
+
+
+## introduction:
+
+While Node.js applications are mostly platform-agnostic, we assume you're
+developing using a Unix system. Should some development script, tool, etc.
+**not** run in your windows (etc.) machine and you know how to make it
+compatible, consider sending a pull request.
+
+**Table of Contents**
+
+* [application architecture](#arch)
+* [starting the application](#start)
+* [data entry](#data-entry)
+* [deployment](#deploy)
+* [news](#news)
+
+
+<a name="arch"></a>
+### application architecture:
+
+The directory structure of the code repository:
+
+```
+.
+|-- config/     # configurations
+|-- data/       # data files, particularly for the different networks
+|-- engine/     # business logic (the "heavy-lifting")
+|-- routes/     # routing logic
+|-- web/        # web interface (whatever you see in the browser)
+`-- app.js      # main entry point, with bootstrap code
+```
+
+The application is built using, mainly:
+
+* [express][express]: THE web framework
+* [node-config][node-config]: handles application configuration
+* [nunjucks][nunjucks]: for page templating
+
+[express]:http://expressjs.com/
+[node-config]:https://github.com/lorenwest/node-config
+[nunjucks]:https://mozilla.github.io/nunjucks
+
+
+<a name="start"></a>
+### starting the application:
+
+The application can be started in either **development** or **production** mode.
+
+```bash
+$ npm start            # start in production mode
+$ npm run start-dev    # start in development mode
+```
+
+
+<a name="data-entry"></a>
+### data entry:
+
+Data entry is a one-off task, that is crucial to this application, so as to
+ensure the data used does **not** end up being stale and inaccurate. This
+is one of the most simple yet cumbersome development task. **No**
+extensive programming knowledge is required.
+
+To get started:
+
+* read the existing data files in [`data/`][data]
+* understand thee [Data File Specification][spec] being used
+
+[data]:https://github.com/forfuturellc/mmtc-ke/blob/master/data/
+[spec]:https://github.com/forfuturellc/mmtc-ke/blob/master/data/SPEC.md
+
+
+<a name="deploy"></a>
+### deployment:
+
+The application is currently being deployed on [OpenShift][openshift]
+**FOR FREE**. We highly recommend you get familiar with the platform.
+It is quite worthwhile.
+
+While we have set the CI to automatically deploy the application,
+particularly on pushing to **master** branch, we assign a developer
+in charge of any deployment issues that may arise.
+
+* developer-in-charge: [GochoMugo](https://github.com/GochoMugo)
+
+Feel free to contact the developer, should you want to submit sensitive
+information concerning the hosting server, etc. Also, CC the information
+to we@forfuture.co.ke, with a suitable subject line.
+
+[openshift]:http://openshift.redhat.com/
+
+
+<a name="news"></a>
+### news:
+
+You can find major news concerning the application at
+http://mmtc.forfuture.co.ke/news/.
+
+Since we are avoiding restarting the application, just to reflect any
+recently-added news, the developer in-charge of deployment handles this
+process:
+
+* a new branch, from the **develop** branch is created with a name
+  in a format, similar to `news/2016-04-23`.
+* new news are added to the beginning of `web/_raw/news.md`
+* while the new branch is reviewed and merged back, the updated news.md
+  should be uploaded to the server, using SSH or similar tool.
+
+News are now updated!
+
+
+**HAPPY HACKING!**

README.md

@@ -5,15 +5,12 @@
 > Running at **http://mmtc.forfuture.co.ke**
 
 
-## contributing:
+## hacking:
 
-Read [CONTRIBUTING.md][contrib] for details on how development is done
-in this project. We are enforcing a code of conduct, described in
-[CODE\_OF\_CONDUCT.md][coc].
+To start hacking on the application, read [HACKING.md][hacking] for
+guidelines and other relevant information.
 
-
-[contrib]:https://github.com/forfuturellc/mmtc-ke/blob/master/CONTRIBUTING.md
-[coc]:https://github.com/forfuturellc/mmtc-ke/blob/master/CODE_OF_CONDUCT.md
+[hacking]:https://github.com/forfuturellc/mmtc-ke/blob/master/HACKING.md
 
 
 ## license:

engine/index.js

@@ -11,6 +11,7 @@ var clients = require('./clients');
 var errors = require('./errors');
 var math = require('./math');
 var networks = require('./networks');
+var pages = require('./pages');
 
 
 exports = module.exports = {
@@ -20,6 +21,7 @@ exports = module.exports = {
   errors: errors,
   math: math,
   networks: networks,
+  pages: pages,
 };
 
 

engine/pages.js

@@ -0,0 +1,44 @@
+/**
+ * The MIT License (MIT)
+ * Copyright (c) 2016 Forfuture LLC
+ *
+ * Pages
+ */
+
+
+exports = module.exports = {
+  getHTML: getHTML,
+};
+
+
+// built-in modules
+var fs = require('fs');
+
+
+// npm-installed modules
+var showdown = require('showdown');
+
+
+// module variables
+var converter = new showdown.Converter();
+
+
+/**
+ * Load HTML content from a markdown file, usually to be inserted into
+ * a shell page, as the main content.
+ *
+ * @todo Add caching
+ *
+ * @param {String} filepath - path to markdown file
+ * @param {Function} done - callback
+ */
+function getHTML(filepath, done) {
+  return fs.readFile(filepath, 'utf8', function(readFileErr, markdown) {
+    if (readFileErr) {
+      return done(readFileErr);
+    }
+
+    var html = converter.makeHtml(markdown);
+    return done(null, html);
+  });
+}

nodemon.json

@@ -0,0 +1,10 @@
+{
+  "verbose": true,
+  "watch": [
+    "app.js",
+    "config/",
+    "data/",
+    "engine/",
+    "routes/"
+  ]
+}

package.json

@@ -1,10 +1,11 @@
 {
   "name": "mmtc-ke",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "scripts": {
     "postinstall": "bower install",
     "start": "forever app.js",
+    "start-dev": "DEBUG=mmtc-ke:* nodemon app.js",
     "test": "echo no tests!!!"
   },
   "dependencies": {
@@ -17,6 +18,7 @@
     "forever": "^0.15.1",
     "lodash": "^4.6.1",
     "nunjucks": "^2.3.0",
+    "showdown": "^1.3.0",
     "winston": "^2.2.0"
   },
   "repository": {

routes/public.js

@@ -1,3 +1,7 @@
+// built-in modules
+var path = require('path');
+
+
 // npm-installed modules
 var _ = require('lodash');
 var Debug = require("debug");
@@ -110,17 +114,35 @@ router
 
 
 // News page
-router.get("/news", function(req, res) {
-    return utils.renderPage(req, res, "news/index");
+router.get("/news", function(req, res, next) {
+  var filepath = path.resolve(__dirname, '../web/_raw/news.md');
+  return renderMarkdownPage(req, res, next, filepath);
 });
 
 
 // Terms and conditions
-router.use('/tcs', function(req, res) {
-    return utils.renderPage(req, res, 'misc/tcs');
+router.use('/tcs', function(req, res, next) {
+  var filepath = path.resolve(__dirname, '../web/_raw/tcs.md');
+  return renderMarkdownPage(req, res, next, filepath);
 });
 
 
+/**
+ * Render a markdown page
+ */
+function renderMarkdownPage(req, res, next, filepath) {
+  return engine.pages.getHTML(filepath, function(getErr, html) {
+    if (getErr) {
+      return next(getErr);
+    }
+
+    return utils.renderPage(req, res, 'misc/content', {
+      content: html,
+    });
+  });
+}
+
+
 // expose the router
 exports = module.exports = router;
 exports.router = router;

web/_raw/news.md

@@ -0,0 +1,7 @@
+<section class="post">
+  <h2>Terms and Conditions <small>2016-04-23</small></h2>
+
+  We have added a page detailing the Terms and Conditions, subject to
+  application users. Please read through it and understand. It can be
+  found at http://mmtc.forfuture.co.ke/tcs
+</section>

web/_raw/tcs.md

@@ -0,0 +1,24 @@
+# terms and conditions
+
+Your usage of this application, at http://mmtc.forfuture.co.ke, assumes your
+acceptance of these terms and conditions.
+
+1. **Source Code**: The source code for this application is available on
+   Github at https://github.com/forfuturellc/mmtc-ke. Proceed to the code
+   repository for more information on licensing. Auditing of the source
+   code is highly welcome.
+1. **Accuracy of Results**: We do **not** guarantee the accuracy of any
+   information retrieved from this application.
+1. **Service Uptime**: Unexpected downtime may occur, due to various
+   reasons such as software crashes and development work.
+1. **Privacy Policy**: We do **not** use cookies or collect any personal
+   information, except that submitted directly in the various forms made
+   available in the application itself.
+1. **Copyright**: Any brand names and trademarks used in the application
+   belong to the respective companies.
+1. **Service Abuse**: Any actions you undertake against this application
+   should be in the best interest of other users and Forfuture, LLC. Be
+   good!
+
+For any copyright-related and other legal issues may be addressed to
+Forfuture, LLC at we {at} forfuture {dot} co {dot} ke.

web/_sass/content.sass

@@ -0,0 +1,11 @@
+@import "_main"
+
+
+.main-content
+  text-align: left
+
+
+.post
+  h2 small
+    color: grey
+    font-size: 12px

web/misc/content.html

@@ -0,0 +1,12 @@
+{#
+ # Shell page for content, in markdown files
+ #}
+{% extends '_layouts/page.html' %}
+
+{# variables #}
+{% set cssURL = '/css/content.css' %}
+
+{# blocks #}
+{% block main_content %}
+{{ content | safe }}
+{% endblock %}