Merge 66dd79f into b779129

Author: starsinmypockets

.gitignore

@@ -10,3 +10,6 @@ yarn-error.log
 sandbox/*
 .env
 .nyc_output/*
+
+# VIM swap files
+.*.sw*

README.md

@@ -111,10 +111,102 @@ Here is the summary of existing routes at the moment:
   * Post: `/news/my-post`
   * Anything else: `/foo/bar`
 
+## Extensions
+
+The platform can be extended in the following ways:
+
+### Theme Routes
+
+Your theme needs a `routes.js` file which defines a `module.export` function that receives the express `app` object. Use `app` to add routes, middleware, etc, to the frontend app.
+
+When your theme is enabled, the `routes.js` file will be parsed by the app.
+
+*NOTE* You do not need to return anything from this function, just extend the app object by reference.
+
+And in `/themes/your_cool_theme/routes.js`:
+```
+module.exports = function (app) {
+  // extend the express app object as you see fit
+  // for example, add a route /foo
+  app.get('/foo', (req, res) => {
+    res.render('example.html', {
+      title: 'Example Theme route',
+      content: {foo: 'Hello theme route'}
+    })  
+  })  
+}
+```
+
+### Plugins
+
+#### User Defined Plugins
+
+Users can define plugins.
+
+Create a directory with the plugins name in `/plugins`
+Add an `index.js` file that uses the app object, as in `theme routes` above.
+
+Add the plugin name to your `.env` file (or to your node environment via any available method). Separate multiple plugins with a space:
+`PLUGINS=your_cool_plugin`
+
+For example, we will create a `req_parameter_logger` plugin:
+
+`plugins/req_parameter_logger/index.js`
+```
+module.exports = function(app) {
+  app.use((req, res, next) => {
+    console.log("EXAMPLE PLUGIN LOGGER {req query}:", req.query)
+    next()
+  })  
+}
+```
+
+Add the plugin name to your .env file.
+Now when we can run `$ yarn start`
+
+Our plugin will be loaded:
+
+```
+Loading configured plugins...
+Loading configured theme routes...
+Listening on :4000
+```
+
+If we visit `localhost:4000?q=123&q1=12451`we will see the following in our console:
+
+```
+EXAMPLE PLUGIN LOGGER {req query}: { q: '123', q1: '12451' }
+EXAMPLE PLUGIN LOGGER {req query}: {}
+```
+
+#### NPM Plugins
+
+If an express middleware plugin is available as a standalone module on npm you can install it as-is by installing the package via npm, and adding it to your `PLUGINS` variable in `.env`
+
+For example, we will install the cookie-parser plugin, alongside our example.
+
+in `.env`:
+`PLUGINS="example cookie-parser"`
+
+now install the npm package:
+`$ yarn add cookie-parser`
+
+Cookie-parser will now be applied to all of your requests as express middleware!
+
+(For instance, you could take advantage of this in custom routes, etc)
+
+For more on express middleware: https://expressjs.com/en/guide/using-middleware.html
+
 ## Tests
 
-Run tests (note that tests are running against mocked API_URL set to http://127.0.0.1:5000/api/3/action/):
+Set `.env` to hit mocked services:
+
+```bash
+API_URL=http://127.0.0.1:5000/api/3/action/
+WP_URL=http://127.0.0.1:6000
+```
 
+Run tests:
 ```bash
 yarn test
 

config/index.js

@@ -6,6 +6,8 @@ require('dotenv').config()
 nconf.argv()
   .env()
 
+nconf.use('memory')
+
 const api_url = process.env.API_URL || 'http://127.0.0.1:5000/api/3/action/'
 
 // This is the object that you want to override in your own local config
@@ -19,7 +21,10 @@ nconf.defaults({
   SITE_URL: process.env.SITE_URL || 'http://0.0.0.0:4000',
   WP_URL: process.env.WP_URL || 'http://127.0.0.1:6000',
   WP_TOKEN: process.env.WP_TOKEN || '',
-  THEME_DIR: process.env.THEME_DIR || 'themes'
+  THEME_DIR: process.env.THEME_DIR || 'themes',
+  NODE_MODULES_PATH: process.env.NODE_MODULES_PATH || 'node_modules',
+  PLUGINS: process.env.FE_PLUGINS || '',
+  PLUGIN_DIR: process.env.PLUGIN_DIR || 'plugins',
 })
 
 module.exports = {

env.template

@@ -1,6 +1,7 @@
-API_URL=
-WP_URL=
+PLUGINS="example"
 WP_TOKEN=
-NODE_ENV=staging
-THEME=
+NODE_ENV=development
+THEME=example
 TRANSLATIONS=
+API_URL=http://127.0.0.1:5000/api/3/action/
+WP_URL=http://127.0.0.1:6000

index.js

@@ -1,5 +1,3 @@
-'use strict'
-
 const path = require('path')
 const express = require('express')
 const cors = require('cors')
@@ -13,6 +11,7 @@ const i18n = require("i18n")
 const config = require('./config')
 const dmsRoutes = require('./routes/dms')
 const cmsRoutes = require('./routes/cms')
+const { loadThemeRoutes, loadUserPlugins } = require('./utils')
 
 module.exports.makeApp = function () {
   const app = express()
@@ -52,6 +51,9 @@ module.exports.makeApp = function () {
   app.use(i18n.init)
   app.use(session({ secret: 'keyboard cat', cookie: { maxAge: 60000 }}))
   app.use(flash())
+  
+  loadUserPlugins(app)
+  loadThemeRoutes(app)
 
   // Redirect x/y/ to x/y
   app.use((req, res, next) => {

plugins/example/index.js

@@ -0,0 +1,7 @@
+module.exports = function(app) {
+  app.use((req, res, next) => {
+    console.log("EXAMPLE PLUGIN LOGGER {req query}:", req.query)
+    res.header('x-my-custom-header', 1234)
+    next()
+  })
+}

tests/routes/index.test.js

@@ -5,6 +5,44 @@ const mocks = require('../../fixtures')
 mocks.initMocks()
 
 const app = require('../../index').makeApp()
+const config = require('../../config')
+
+
+// THEME ROUTES
+// @@TODO Test fail case for theme routes
+test('Theme defined route exists when THEME is set', async t => {
+  config.set('THEME', 'example')
+  const app = require('../../index').makeApp()
+  const res = await request(app)
+    .get('/foo')
+  
+  t.is(res.statusCode, 200)
+  t.true(res.text.includes('Hello theme route'))
+})
+
+
+test('Theme defined route does NOT exists when THEME is not set', async t => {
+  config.set('THEME', 'opendk')
+  const app = require('../../index').makeApp()
+  const res = await request(app)
+    .get('/foo')
+  
+  t.is(res.statusCode, 500)
+})
+
+
+// PLUGINS
+// @@TODO Test fail case for plugins
+// @@TODO Test load plugin from npm
+test('User-plugin-provided res has expected custom header present', async t => {
+  config.set('PLUGINS', "example cookie-parser")
+  const app = require('../../index').makeApp()
+  t.plan(1)
+
+  const res = await request(app)
+    .get('/')
+  t.true(res.headers['x-my-custom-header'] === '1234')
+})
 
 
 // CMS

themes/example/routes.js

@@ -0,0 +1,9 @@
+module.exports = function (app) {
+  app.get('/foo', (req, res) => {
+    console.log('example route')
+    res.render('example.html', {
+      title: 'Example Theme route',
+      content: {foo: 'Hello theme route'}
+    })
+  })
+}

themes/example/views/example.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block bodyclass %}dash{% endblock %}
+{% block content %}
+<div class="pt-6">
+    {{ content.foo }}
+</div>
+{% endblock %}

utils/index.js

@@ -1,3 +1,7 @@
+const config = require('../config')
+const path = require('path')
+const fs = require('fs')
+
 module.exports.ckanToDataPackage = function (descriptor) {
   // Make a copy
   const datapackage = JSON.parse(JSON.stringify(descriptor))
@@ -206,3 +210,59 @@ module.exports.processMarkdown = require('markdown-it')({
   linkify: true,
   typographer: true
 })
+
+/**
+ * Returns an array of express Router instances
+ * or []
+ */
+module.exports.loadThemeRoutes = function (app) {
+  console.log('Loading configured theme routes...')
+  
+  try {
+    const theme = config.get('THEME')
+    const themePath = config.get('THEME_DIR')
+    console.log(theme, themePath)
+    if (!theme) return
+    const resource = path.join(process.cwd(), themePath, theme, 'routes.js')
+    console.log(resource)
+    require(resource)(app)
+  } catch (e) {
+    const theme = config.get('THEME')
+    console.warn(`WARNING: Failed to load configured theme routes for ${theme}`)
+  }
+}
+
+module.exports.loadUserPlugins = function (app) {
+  console.log('Loading configured plugins...')
+  
+  try {
+    const plugins = config.get('PLUGINS')
+    const pluginPath = config.get('PLUGIN_DIR')
+    const nodeModulesPath = config.get('NODE_MODULES_PATH')
+    
+    if (!plugins) return 
+
+    // try to load each resource
+    return plugins.split(' ').forEach(plugin => {
+      const userResource = path.join(process.cwd(), pluginPath, plugin, 'index.js')
+      const npmResource = path.join(process.cwd(), nodeModulesPath, plugin)
+      
+      // look for plugin in user space
+      if (fs.existsSync(userResource)) {
+        require(userResource)(app)
+      // otherwise look in node_modules
+      } else if (fs.existsSync(npmResource)) {
+        const middleware = require(plugin)
+        app.use(middleware())
+      } else {
+        // if all else fails give the user a helping hand
+        const userPluginPath = path.resolve(process.cwd(), pluginPath, plugin)
+        throw new Error(`Cannot find configured plugin ${plugin}. Is it installed? If the plugin is an npm module try to run\n"yarn add ${plugin}"\nIf it is a user plugin, make sure you have a directory at ${userPluginPath} and a valid index.js file there.`)
+      }
+    })
+  } catch (e) {
+    const plugins = config.get('PLUGINS').split(" ") || []
+    console.warn('WARNING: Failed to load configured plugins',plugins, e)
+    return []
+  }
+}