popcms

#POPCMS is a lightweight NodeJS, MongoDB website content management system

It's designed for using in Bootstrap sites, allows simple HTML editing by the webmaster by changing files, and intuative content admin management in the browser using CKEditor inline.

Handlebars is used for HTML templating, and the page data model is automatically created based on the tags the webmaster places in the HTML template.

A template contact form is included, which refers to API endpoints that will send emails via SendGrid, which you'll need an account with in order to send emails.

Login is achieved through a Google Account using OAuth with Google+. The developer will need to create a clientId and secret at https://console.developers.google.com/ - more info below!

##Change log

• 2016-12-30 - v0.4.0 - Reduced editable html element definition to single tag. Introduced change log. :)

##Installation It's currently a single installation within your application root folder. (We might split out into modules in the future).

To get started, create a new folder to hold your project, and in the root folder run the following commands: npm init

Then npm install popcms --save

##Creating your application

We recommend creating the following folders in your application:

• /html/ - place your html templates in here.
• /static/css/ - place your css files in here - start with a simple style.css in there. The app will server this folder as /css/
• /static/img/ - place your image files in here. The app will server this folder as /img/

You should also create a robots.txt and a favicon.ico file to go in the /static/ folder.

##HTML Templates#

The templates should be placed in the /html/ folder. These will use handlebars syntax to identify named text areas, that POPCMS will replace with inline text editors for admin users.

POPCMS expects the following files as a minimum:

• master.html - the "master template" page (header/footer etc) and seperate templated files which contain the body content. This file should contain the following string, in which the content of the page template will be inserted: [[[body]]];
• 404.html - the page template to show when a page is not found (i.e. hasn't yet been created in the POPCMS database).

###Page configuration POPCMS automatically creates a set of fields for the main meta data required for each page on a website. These are editable through an admin UI added to each page when logged in as a POPCMS admin user.

The fields are:

• Page Title (title)
• Page Keywords (keywords)
• Page Description (desceiption)

###Page navigation Using handlebars, POPCMS will also automatically create a ul/li nav list where it finds the following in a template (master template or page template);

{{#nav navigation permalink}}
{{/nav}}

The two properties here are:

• navigation - this is the full list of nav items defined in the site config (below)
• permalink - this is the relative url of the current page

###Contact form POPCMS will automatically add a contact form when it finds the following in a template:

[[[contactform]]]

###Scope of templates Although editable content areas can be defined anywhere in a template, including the master template, all of the content entered is scoped to a specific page - i.e. even if you add an editor to the master template, the text content entered for tha element will only be visible on the page it's edited on.

###Example master.html (to place in your /html/ folder) {{title}} </-->

Toggle navigation My site

{{#nav navigation permalink}} {{/nav}}

[[[body]]]

###Adding Admin editable content areas This is the main point of the CMS!

Within each template, you can add areas that will be populated using database driven content (authored by an admin user). This is achieved by adding the following text: [[[editable:FIELD_NAME]]]

• Where FIELD_NAME is replaced with an alphanumeric string, which will also be used as the id for the html element that contains this block of content. e.g. [[[editable:pageHeading]]]

This will allow your POPCMS site to identify this as an editable area, and it will save the content the admin user enters with the property name pageHeading when the admin user edits this content.

###Example of your homepage HTML file (save as e.g. /html/homepage.html)

[[[editable:pageHeading]]]

<div class="row">
	<div class="col-sm-9">
		[[[editable:mainContent]]]
	</div>
	<div class="col-sm-3">
		[[[editable:rightContent]]] 
	</div>
</div>

###Example of your contact page HTML file (save as e.g. /html/contact.html)

[[[editable:pageHeading]]]

[[[editable:mainContent]]]

[[[contactform]]]

###Other pages You can create as many html templates as you wish - just add more files to the /html/ folder and be sure to include [[[editable:FIELD_NAME]]] where you would like an editable text area to be added.

Make sure the FIELD_NAME value used is unique to that particular template.

##Example use: Once you have created your templates, you just need to run POPCMS... You do so by creating server.js file in the root folder of your project, and adding the following content. You'll need to replace the various values with real settings.

Things to note:

1. We use Google accounts to authenticate the admin user (currently only one allowed). You need one of those, and you need to list it as adminEmail;
2. You need a MongoDB database... when you have that, add the connection string in connString;
3. If you want to send emails from the contact form, you'll need a SendGrid account. Add details in the sendgrid property object;
4. You'll need to setup google auth on google console, and ensure you allow the hostnames that you are using to have access.

###Sample server.js: For googleAuth, please see Setup up Auth with Google API.

var popcms = require("popcms");
popcms.createServer(
		{
			templatePath : __dirname + '/html',
			staticFilePath :  __dirname + '/static', 

			// create a secret to help secure sessions
			secret : "A_RANDOM_LONG_STRING_HERE", 
			
			// define the mongodb instance
			dbCollectionNamePrefix : "my_popcms_collection",
			connString :  "MONGO_DB_CONNECTION_STRING",

			// define the host, port and http/https where this is running.
			host : "127.0.0.1",
			port : "5000",
			httpOrHttps : "http",

			// optional dev settings (triggered by NODE_ENV=dev)
			dev : {
				host : "127.0.0.1",
				port : "5000",
				httpOrHttps : "http",
			},

			// optionally define a sendgrid account for sending contact emails.
			sendgrid: {
			    username: "SENDGRID_USERNAME",
				password: "SENDGRID_PASSWORD",
				contactMailTo: "CONTACT_FORM_TO_ADDRESS",
				contactMailFrom: "CONTACT_FORM_FROM_ADDRESS",
				contactSubject: "CONTACT_FORM_SUBJECT"
			},

			// define the info used for authenticating the admin user with Google.
			adminEmails : ["ADMIN_GOOGLE_ACCOUNT_USERNAME_1", "ADMIN_GOOGLE_ACCOUNT_USERNAME_2", "ADMIN_GOOGLE_ACCOUNT_USERNAME_3"],
			googleAuth : {
				clientID      : 'GOOGLE_AUTH_CLIENT_ID',
				clientSecret  : 'GOOGLE_AUTH_CLIENT_SECRET'}
			,

			// create your navigation if you want to use the bulit in POPCMS nav builder (recommended)
			navigation : [
				{name:"home", url:"/"},
				{
					name:"section 1", 
					url:"/section-1",
					// optionally define this as a dropdown
					style: "dropdown",
					// optionally add sub page to this navigation item (current we only really handle two levels of nav effectively)
					pages : [{
						name:"page 1", 
						url:"/page-1",
					},
					{
						name:"page 2", 
						url:"/page-2",
					}]
				}, 
				{name:"page 2", url:"/page-2/"}, 
				{name:"page 3", url:"/page-3/"}, 
				{name:"contact", url:"/contact/"}
			],
		
		// Enable the caching of output pages to memory for faster performance.  
		// Note - this is untested on large implementations (e.g. many pages) where memory limitations may cause issues.
		// Note - this will mean changes to html templates requiring an app restart .
		enableCache = false;
	}
);

##Setting up Auth with Google API This is straight forward, but can be strangely daunting if you haven't done it before (or even recently).

###Step 1 - Create a Google API project Start by heading to https://console.developers.google.com/apis/, and create a project there.

Once you have a project, you'll need to enable the Google+ API.

Google API Console will create the project, and should then prompt you to Create credentials... that's exatly what we need to do!

###Step 2 - Create credentials In the next screen, select the following options:

• Which API are you using? : Google+ API
• Where will you be calling the API from? - Web server
• What data will you be accessing? - User data

Then press "What credentials do I need".

On the next screen give the credentials a name, say "my popcms site authentication" and then configure the restrictions to ensure only your intended site can utilise this...

###Step 3 - Configure access For both restrictions options, enter the localhost details (i.e. http://127.0.0.1:5000) and the domain where you intend to host the site in the wild (i.e. http://www.mysite.com)

The "Authorized redirect URLs" will include the full callback URL, e.g. http://127.0.0.1:5000/auth/google/callback.

Then hit "Create client Id".

###Step 4 - Apply settings to app Complete the remaining details... and that's it... Take a copy of the Client ID, and put that in your server config under googleAuth. It doesn't show the ClientSecret here, so you'll have to click "Done", go back to the list, and then click into the credential you have created to access it. Copy that value into your config too.

###Step 5 - Grant admin access to correct users POPCMS allows you to create one or more admin user account. The property is adminEmails, and this expects a list of emails address as strings. Please note, these do need to be registered Google accounts. e.g. adminEmails = ["[e-mail]", "[e-mail]", "[e-mail]"]

##Running for the first time The default configuration above should work locally as long as the app can connect to your MongoDB server, and you have correctly configured the Google Account info.

###Development environment settings You may, if you wish, use the dev config when running on your local machine. You can achieve this by setting the following environment property. This allows you to override the host, port and httpOrHttps setting: NODE_ENV=dev

	// e.g. *nix
	NODE_ENV=dev node server

	// e.g. windows
	SET NODE_ENV=dev
	node server

###Standard settings From your command line, run: node server

And then in your browser, open up http://127.0.0.1:5000/ (or whatever you have changed host and port to in the createServer config).

You should see a "page not found" message, and this will tell you that the site is running, but you haven't created any pages yet.

##Logging in as admin for the first time Once you have the site up and running, you can start creating content pages by logging in to admin. You'll need to login to the account listed in the config as adminEmail and authorise your site to use the Google Account. You can do this by going to http://127.0.0.1:5000/login/ - this will direct you to Google login.

Once logged in, you should be redirected back to the site's homepage where you can create your first page.

##Creating or Editting a page All content admin or web pages is achieved through the browser and "on page". If you are logged in as an admin user, you will now see a small admin panel on the right hand side. This has three buttons:

• Logout
• Edit page settings
• Save changes

If you are creating a new page, you start by entering the url that you would like the page to exist in (within the host). E.g. you might type http://127.0.0.1:5000/my-new-page - Or if you already added this page to your config navigation, you can simply click on the navigation item.

You'll see a page that says "This page doesn't exist, but as you are the site admin, you can create it using the page admin form!". So, you can click on the edit link in the admin panel at the top right, and then select a template (from your templates in the /html/ folder you created earlier). Then give the page a title, and click the save icon on the right hand side.

Once you've saved, the page will reload with using the template you have created and selected. Now try clicking in the dashed areas of the page - you should be able to edit the content on the page, and then save that (again by using the Save icon in the top tight hand corner).

To edit an exist page, just do the same as above... this time, you can simply browse to the page you want to edit.

##Note about nav Bear in mind that creating pages, and defining the navigation are two separate things. Currently Nav is defined through the app config (this is tends to change very infrequently). If there is a real demand for it, we'll consider making setting up the nav as an admin user task too.

##Roadmap Things we are considering:

• Replace Sync template file reads with async + promises
• Navigation admin
• Implement plugin architecture and utilise for existing features (e.g. contact form and email send)
• Sample starter project
• Improved documentation of the models
• Shared content components (for content used in across pages) [partly completed with 'html/parts folder'
• Tiered master layout pages
• Structured content lists (e.g. people, blog, or product items)
• Improved page version history (extend to allow a user to view and restore old versions)
• Content file upload to public cloud storage
• CKEditor customisations