Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updated Readme and added js documentation comments

  • Loading branch information...
commit 2960bf8b061a81e8087b7ab6cf2c98504ad7234d 1 parent f57d38c
@astalker authored
View
18 README.md
@@ -1,4 +1,3 @@
-
# NBLOG
Simple Blog CMS using Mongoose, Express and EJS.
@@ -32,14 +31,21 @@ Add the following to your main script and specify your login details for the Adm
}
nblog.init(params);
-The public path is relative to the module so to use a public dir in the root you would specify /../../../public
-Nblog requires Mongo DB so make sure to start it before running your App.
+The dev and prod values are the environments. These can be configured via Node Environment variables so you can specify different settings for your local and production sites.
## Features
- * Add, edit and delete articles
- * Articles displayed in a blog layout with links to each article
- * Urls built based on date and alias
+ * Add, edit and delete articles. Meta content included for some basic SEO.
+ * Articles displayed in a blog layout with links to each article.
+ * Article urls automatically built based on date and the alias.
+ * Add, edit and delete content pages.
+ * Additional content pages displayed in the main nav.
+ * Google sitemap generation.
+ * Twitter Bootstrap implemented.
+
+## Requirements
+
+MongoDB is required and should be running before starting Nblog.
## License
View
22 lib/helper.js
@@ -2,18 +2,40 @@ var db = require('./mongoose')
, Crypto = require('crypto')
, logmongo = require('logmongo');
+/**
+ * Create an md5 hash.
+ *
+ * @param {String} String to create the hash from
+ * @param {Function} callback function
+ * @api public
+ */
exports.md5 = function(str, callback){
var hash = Crypto.createHash('md5');
hash.update(str, 'utf-8');
callback(hash.digest('hex'));
}
+/**
+ * Create a Gravatar url.
+ *
+ * @param {String} the email address to use as the basis for the Gravatar
+ * @param {Function} callback function
+ * @api public
+ */
exports.gravatar = function(email, callback){
exports.md5(email, function(hash){
callback('http://www.gravatar.com/avatar/' + hash + '?s=40');
});
};
+/**
+ * Get application preferences specified in the object params and from the database. The last login date is also returned if requested.
+ *
+ * @param {String} String to create the hash from
+ * @param {Function} callback function
+ * @param {Boolean} get the last login date
+ * @api public
+ */
exports.prefs = function(params, callback, getlog){
db.projectPreferences(params, function(err, prefs, pages){
if (prefs.gravatar){
View
205 lib/mongoose.js
@@ -3,14 +3,33 @@ var moment = require('moment');
var mongoose = require('mongoose');
var Schema = mongoose.Schema;
+/**
+ * Connect to the database.
+ *
+ * @param {String} the database url
+ * @param {Function} callback function
+ * @api public
+ */
exports.connect = function(dburl, callback) {
mongoose.connect(dburl);
}
+/**
+ * Disconnect from the database.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.disconnect = function(callback) {
mongoose.disconnect(callback);
}
+/**
+ * Setup.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.setup = function(callback) { callback(null); }
var ArticleSchema = new Schema({
@@ -52,6 +71,18 @@ var Pages = mongoose.model('Pages');
exports.emptyArticle = { "_id": "", title: "", article: "", alias: "", description: "", keywords: "" };
exports.emptyPage = { "_id": "", page: "", intro: "", content: "", description: "", keywords: "", menu: "", alias: "" };
+/**
+ * Add a new article.
+ *
+ * @param {String} title
+ * @param {String} timestamp
+ * @param {String} article
+ * @param {String} Meta description
+ * @param {String} Meta keywords
+ * @param {String} alias for the url
+ * @param {Function} callback function
+ * @api public
+ */
exports.add = function(title, ts, article, description, keywords, alias, callback) {
var newArticle = new Article();
newArticle.title = title;
@@ -73,6 +104,21 @@ exports.add = function(title, ts, article, description, keywords, alias, callbac
callback(null);
});
}
+
+/**
+ * Add a new page.
+ *
+ * @param {String} page name
+ * @param {String} timestamp
+ * @param {String} introduction text
+ * @param {String} content text
+ * @param {String} Meta description
+ * @param {String} Meta keywords
+ * @param {String} alias for the url
+ * @param {Boolean} option to display the page in the menu
+ * @param {Function} callback function
+ * @api public
+ */
exports.addpage = function(page, ts, intro, content, description, keywords, alias, menu, callback) {
var newPage = new Pages();
newPage.page = page;
@@ -97,6 +143,13 @@ exports.addpage = function(page, ts, intro, content, description, keywords, alia
});
}
+/**
+ * Delete an article.
+ *
+ * @param {String} id
+ * @param {Function} callback function
+ * @api public
+ */
exports.delete = function(id, callback) {
exports.findArticleById(id, function(err, doc) {
if (err)
@@ -108,6 +161,14 @@ exports.delete = function(id, callback) {
}
});
}
+
+/**
+ * Delete a page.
+ *
+ * @param {String} id
+ * @param {Function} callback function
+ * @api public
+ */
exports.deletePage = function(id, callback) {
exports.findPageById(id, function(err, doc) {
if (err)
@@ -120,6 +181,12 @@ exports.deletePage = function(id, callback) {
});
}
+/**
+ * Get a count of all articles. Useful for pagination.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.countArticles = function(callback) {
Article.count({}, function(err, doc) {
if (err) {
@@ -130,6 +197,19 @@ exports.countArticles = function(callback) {
});
}
+/**
+ * Edd an article.
+ *
+ * @param {String} id
+ * @param {String} title
+ * @param {String} timestamp
+ * @param {String} article
+ * @param {String} Meta description
+ * @param {String} Meta keywords
+ * @param {String} alias for the url
+ * @param {Function} callback function
+ * @api public
+ */
exports.edit = function(id, title, ts, article, description, keywords, alias, callback) {
exports.findArticleById(id, function(err, doc) {
if (err)
@@ -157,6 +237,21 @@ exports.edit = function(id, title, ts, article, description, keywords, alias, ca
});
}
+/**
+ * Edit a page.
+ *
+ * @param {String} id
+ * @param {String} page name
+ * @param {String} timestamp
+ * @param {String} introduction text
+ * @param {String} content text
+ * @param {String} Meta description
+ * @param {String} Meta keywords
+ * @param {String} alias for the url
+ * @param {Boolean} option to display the page in the menu
+ * @param {Function} callback function
+ * @api public
+ */
exports.editpage = function(id, page, ts, intro, content, description, keywords, alias, menu, callback) {
exports.findPageById(id, function(err, doc) {
if (err)
@@ -186,6 +281,13 @@ exports.editpage = function(id, page, ts, intro, content, description, keywords,
});
}
+/**
+ * Get articles limited by the requested amount and all pages.
+ *
+ * @param {Number} the number of articles to return
+ * @param {Function} callback function
+ * @api public
+ */
exports.allArticlesPages = function(num, callback) {
exports.allArticles(num, function(err, articles){
exports.allPages(function(err, pages){
@@ -193,15 +295,44 @@ exports.allArticlesPages = function(num, callback) {
});
});
}
+
+/**
+ * Get articles limited by the requested amount and sort by timestamp.
+ *
+ * @param {Number} the number of articles to return
+ * @param {Function} callback function
+ * @api public
+ */
exports.allArticles = function(num, callback) {
Article.find({}).limit(num).sort("-ts").execFind(callback);
}
+
+/**
+ * Get all pages and sort by timestamp.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.allPages = function(callback) {
Pages.find({}).sort("-ts").execFind(callback);
}
+
+/**
+ * Get all pages in the menu and sort by timestamp.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.allMenuPages = function(callback) {
Pages.find({menu: 1}).sort("-ts").execFind(callback);
}
+
+/**
+ * Get all articles by page. Used for the pagination.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.allArticlesPaged = function(num, page, callback) {
var skip = 0;
if (page > 0){
@@ -210,6 +341,13 @@ exports.allArticlesPaged = function(num, page, callback) {
Article.find({}).skip(skip).limit(num).sort("-ts").execFind(callback);
}
+/**
+ * Traverse through the articles. Used for logging and debugging purposes.
+ *
+ * @param {Function} callback function to call on each article retrieval
+ * @param {Function} callback function on completion
+ * @api public
+ */
exports.forAll = function(doEach, done) {
Article.find({}, function(err, docs) {
if (err) {
@@ -223,6 +361,12 @@ exports.forAll = function(doEach, done) {
});
}
+/**
+ * Get the project preferences from the database if they have been set.
+ *
+ * @param {Function} callback function
+ * @api public
+ */
exports.projectPreferences = function(params, callback){
Prefs.findOne({ }, function(err, doc) {
if (err) {
@@ -237,6 +381,19 @@ exports.projectPreferences = function(params, callback){
});
});
}
+
+/**
+ * Save the project preferences.
+ *
+ * @param {String} project name
+ * @param {String} email address
+ * @param {String} number of items to display per page
+ * @param {String} Meta description for home page
+ * @param {String} Meta keywords for home page
+ * @param {Boolean} Option to display Gravatar
+ * @param {Function} callback function
+ * @api public
+ */
exports.save = function(name, email, items, description, keywords, gravatar, callback) {
Prefs.findOne({ }, function(err, doc) {
if (err) {
@@ -264,7 +421,19 @@ exports.save = function(name, email, items, description, keywords, gravatar, cal
});
}
-exports.newPref = function(name, email, items, description, keywords, callback) {
+/**
+ * Create a new preferences object in the database
+ *
+ * @param {String} project name
+ * @param {String} email address
+ * @param {String} number of items to display per page
+ * @param {String} Meta description for home page
+ * @param {String} Meta keywords for home page
+ * @param {Boolean} Option to display Gravatar
+ * @param {Function} callback function
+ * @api public
+ */
+exports.newPref = function(name, email, items, description, keywords, gravatar, callback) {
var newPrefs = new Prefs();
newPrefs.name = name;
newPrefs.email = email;
@@ -281,6 +450,13 @@ exports.newPref = function(name, email, items, description, keywords, callback)
});
}
+/**
+ * Find an article by its id.
+ *
+ * @param {String} id
+ * @param {Function} callback function
+ * @api public
+ */
var findArticleById = exports.findArticleById = function(id, callback) {
Article.findOne({ _id: id }, function(err, doc) {
if (err) {
@@ -290,6 +466,14 @@ var findArticleById = exports.findArticleById = function(id, callback) {
callback(null, doc);
});
}
+
+/**
+ * Find a page by its id.
+ *
+ * @param {String} id
+ * @param {Function} callback function
+ * @api public
+ */
var findPageById = exports.findPageById = function(id, callback) {
Pages.findOne({ _id: id }, function(err, doc) {
if (err) {
@@ -299,6 +483,14 @@ var findPageById = exports.findPageById = function(id, callback) {
callback(null, doc);
});
}
+
+/**
+ * Find a page by its alias.
+ *
+ * @param {String} alias
+ * @param {Function} callback function
+ * @api public
+ */
var findPageByAlias = exports.findPageByAlias = function(alias, callback) {
Pages.findOne({ alias: alias }, function(err, doc) {
if (err) {
@@ -308,6 +500,17 @@ var findPageByAlias = exports.findPageByAlias = function(alias, callback) {
callback(null, doc);
});
}
+
+/**
+ * Find an article by its date and alias.
+ *
+ * @param {String} year
+ * @param {String} month
+ * @param {String} day
+ * @param {String} title/alias
+ * @param {Function} callback function
+ * @api public
+ */
var findArticleByDate = exports.findArticleByDate = function(year, month, day, title, callback) {
var start = new Date(year, month-1, day); //months are 0 based so Jan equals 0
var end = new Date(year, month-1, day);
View
11 lib/nblog.js
@@ -9,6 +9,12 @@ var db = require('./mongoose')
var username, password, params, next;
+/**
+ * Starts the App.
+ *
+ * @param {Object} the params
+ * @api public
+ */
exports.init = function(p){
params = p;
@@ -24,6 +30,11 @@ exports.init = function(p){
require('./routes')(app, this);
}
+/**
+ * Close DB connection.
+ *
+ * @api public
+ */
exports.close = function(){
db.disconnect(function(err) { });
};
View
8 lib/routes.js
@@ -1,4 +1,10 @@
-
+/**
+ * Specify the routes.
+ *
+ * @param {Object} the running app object
+ * @param {Class} the Nblog class
+ * @api public
+ */
module.exports = function(app, nblog)
{
app.get('/', nblog.index);
View
7 lib/server.js
@@ -5,6 +5,13 @@ var db = require('./mongoose')
, express = require('express')
;
+/**
+ * Setup the server and framework with the provided params.
+ *
+ * @param {Object} the params
+ * @param {Function} the callback function
+ * @api public
+ */
exports.init = function(params, callback){
var app = express();
View
15 lib/sitemap.js
@@ -1,6 +1,14 @@
var db = require('./mongoose')
, moment = require('moment');
+/**
+ * Generate a url.
+ *
+ * @param {String} url
+ * @param {String} date
+ * @param {String} frequency
+ * @api public
+ */
exports.url = function(url, date, freq) {
var sitemap;
sitemap = '<url>';
@@ -12,6 +20,13 @@ exports.url = function(url, date, freq) {
return sitemap;
}
+/**
+ * Create the sitemap and return it to the callback function.
+ *
+ * @param {String} host
+ * @param {Function} the callback function
+ * @api public
+ */
exports.create = function(host, callback) {
var sitemap = '<?xml version="1.0" encoding="UTF-8"?>';
Please sign in to comment.
Something went wrong with that request. Please try again.