add documentation

Author: Ryan Haskell-Glatz

README.md

@@ -0,0 +1,51 @@
+# KeystoneJS | Singleton Plugin
+> A plugin that allows the creation of "singleton" KeystoneJS lists.
+
+### Description
+
+This plugin prevents users from creating multiple items, and guarantees that an item is created automatically.
+
+So if you want to make "Homepage Settings", we gotchu <3
+
+
+### Example Usage
+
+
+__`HomepageSettings.js`__
+
+```js
+const keystone = require('keystone')
+
+// 1. Include the `singleton` option
+const List = keystone.List('HomepageSettings', {
+  singleton: true
+})
+
+// 2. Add in your fields.
+List.add( /* ... */ )
+
+// 3. Register your list.
+List.register()
+```
+
+
+__`keystone.js`__
+
+```js
+const keystone = require('keystone')
+const singleton = require('keystone-singleton')
+
+// 1. Initialize KeystoneJS
+keystone.init( /* ... */ )
+
+// 2. Initialize this plugin
+singleton.init({ keystone })
+
+// 3. Include your Models
+keystone.import('models')
+
+// 4. Start KeystoneJS
+keystone.start()
+```
+
+Your KeystoneJS list will automatically be created on startup.

index.js

@@ -0,0 +1,71 @@
+module.exports = {
+  init: ({ keystone }) => {
+    const register = keystone.List.prototype.register
+
+    keystone.List.prototype.register = function () {
+      const List = this
+      const isSingleton = List.options.singleton
+
+      // Only do this if the `singleton` option is set:
+      if (isSingleton) {
+        // Get the list name, and a human-readable name
+        const listName = List.key
+        const prettyName = listName
+          .split('')
+          .map(letter =>
+            (letter.toUpperCase() === letter)
+              ? ' ' + letter
+              : letter
+          )
+          .join('')
+          .trim()
+
+        // Automatically name the item
+        List.add({
+          singleton__name: {
+            type: String,
+            required: true,
+            default: prettyName,
+            hidden: true,
+            select: false
+          }
+        })
+
+        // Map `singleton__name` to KeystoneJS name
+        List.options.map = List.options.map || {}
+        List.options.map.name = List.options.map.name || 'singleton__name'
+
+        // Disallow creation and removal
+        List.options.nocreate = true
+        List.options.nodelete = true
+
+        // Keep label singular by default
+        List.options.label = List.options.label || prettyName
+
+        // Register the singleton
+        register.apply(this)
+
+        // Attempt to create item, if none already exist
+        const Model = keystone.list(listName).model
+
+        Model.count()
+          .lean()
+          .exec()
+          .then(count => {
+            if (count === 0) {
+              console.info(`SINGLETON: Creating '${listName}'...`)
+              return Model.create({})
+            } else {
+              return Promise.resolve(undefined)
+            }
+          })
+          .catch(reason => {
+            console.error(`SINGLETON: Could not create '${listName}'.`)
+          })
+      } else {
+        // Register the list
+        register.apply(this)
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,16 @@
+{
+  "name": "keystone-singleton",
+  "version": "1.0.0",
+  "description": "A plugin that allows the creation of \"singleton\" KeystoneJS lists.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://bitbucket.org/onenorth/keystone-singleton.git"
+  },
+  "author": "Ryan Haskell-Glatz",
+  "license": "ISC",
+  "homepage": "https://bitbucket.org/onenorth/keystone-singleton#readme"
+}