#ah-tdp-content-item-plugin

##Version Master: V3.0.8

##Semver This project aims to maintain the semver version numbering scheme.

##Changelog See changelog file

##Overview A simple content plugin for actionhero which has a markdown or HTML formatted source, optional server-side markdown to HTML conversion and a MongoDB backend.

ah-tdp-content-item-plugin is designed specifically for use with the actionHero API framework (and also to a slightly lesser extent, the TDPAHCMS system) and thus is unlikely to work directly with any other application. You're welcome to fork and modify of course if that is of interest of course.

##Features

• Markdown or HTML
• Asynchronous operation throughout
• Included unit tests, automatically run via Travis-CI
• Included default actions for automated testing
• Included initialiser
• Supports dedicated per actionhero environment configurations

##Requirements

• Prerequisite since it's the plugin host
  • actionhero
• Production requirements
  • mongoskin
  • check-types
  • markdown
• Development/test requirements
  • mocha
  • should
  • actionhero

##Installation Installation is relatively simple and is simplest using npm:

# Install actionhero (skip this if you have already got it installed)
npm install actionhero

# Generate a skeleton actionhero project (skip if already done)
./node_modules/.bin/actionhero generate

# Install ah-tdp-content-item-plugin (and save to package.json file - optional)
npm install ah-tdp-content-item-plugin --save

Then you'll need to edit the actionhero config file, config/plugins.js and add the plugin name into the plugins array.

After that, you can start your API server using npm start.

No doubt you'll want to change lots more things but the above is a generic set of instructions.

##Usage This module is an actionhero plugin so it conforms to the base requirements, this means it provides:

• Actions
• An initialiser
• An editable, userland config file (which is actionhero 'environment' (development, production etc.) aware) which will appear as <project root>/config/plugins/ah-tdp-content-item-plugin.js assuming the contentIteminstall NPM script worked properly
• The core module itself

##Configuration You should edit the userland config file as required, this is where you can customise the module to fit your project requirements. This file will not be replaced by module updates so you need to manually keep it up to date, at least until I create some automated method.

For detailed explanation of the fields, check the userland or default config file comments.

###Configuration file: environments Configuration options can be defined for all or (overridden) for individual environments using the following structure:

exports.default=
{
    ah-tdp-content-item-plugin: function(api)
    {
        return {
            ...
        }
    }
}

exports.production=
{
    ah-tdp-content-item-plugin: function(api)
    {
        return {
            ...
        }
    }
}

...

This structure is as per the common actionhero configuration model. The environment is set via a environment variable (on *nix systems this is NODE_ENV) which override the base/default options in exports.defaults{}. So you should put common (environment agnostic/independent) configuration options in the exports.defaults{} section and then override/augment those with any environment-specific options as required.

##Actions There are some default actions included which are intended as at least a starter/example and are structured to be generally appropriate to be restricted via an ACL, for example my actionhero ACL plugin

###ah-tdp-content-item-plugin/create ####Overview Creates a new content item version (all items are versions). To ensure you create a new version of an existing content item, simply use the (exact) same contentItemID (parameter: i) or "friendly name" (parameter: f).

####Parameters

• Required:
  • m (string) - the content markdown (remember that HTML is valid markdown)
  • At least one of:
    • f (string) - the "friendly name" (label)
    • i (string) - the contentItemID (a reference string which is unique to one content item and consistent across all that content items versions)
• Optional
  • h (string) - the HTML for the content item. This can be automatically created from the supplied markdown (parameter: m) if correct configuration is specified (i.e. if convertMarkdownToHTMLOnServerSide is true. Optionally, you can set overwriteClientSuppliedHTML to true which means that any user-supplied HTML will be overridden with the coverted markdown)
  • d (integer) - a unix timestamp to use as the datePublished. This can be a future date to allow for scheduled publishing or the current (or a previous) timestamp to publish immediately

####Output TBC - would be good to be configurable and use responseObject by default

###ah-tdp-content-item-plugin/delete ####Overview Deletes an existing content item (either one version or all version of the item). Note that all deletes are currently soft deletes (i.e. they simply mark the item/version as deleted rather than removing it from the database collection).

####Parameters

• Required:
  • i (string) - the contentItemID (a reference string which is unique to one content item and consistent across all that content items versions)
• Optional
  • v (string) - either "all" to delete all versions of the content item or a specific content item version id (_id) to delete only one version

####Output TBC - would be good to be configurable and use responseObject by default

###ah-tdp-content-item-plugin/getByID ####Overview Retrieves a specific content item version.

####Parameters

• Required:
  • i (string) - the contentItemID (a reference string which is unique to one content item and consistent across all that content items versions)
  • v (string) - the specific content item version id (_id) to retrieve

####Output TBC - would be good to be configurable and use responseObject by default

###ah-tdp-content-item-plugin/getMany ####Overview Retrieves one or more content items/versions based on supplied criteria

####Parameters

• Optional:
  • v (string) - the specific content item version id (_id) to retrieve. This will restrict the result set to one content item if specified
  • n: (int or "all") number of records to return (mongoDB options.limit). Defaults to 1 if not specified.
  • o: order (string - see format). Format: e.g. fieldA:-1,fieldB:1 (1 is 'asc', -1 is 'desc' in SQL-like syntax)
  • s: (int) skip s records (mongoDB options.skip)
  • i (string) - the contentItemID (a reference string which is unique to one content item and consistent across all that content items versions)
  • l: (string) - language of versions to retrieve. Defaults to config.options.defaultLanguage if not specified
  • d: (boolean) - include deleted items? Defaults to false
  • u: (boolean) - include unpubished items? Defaults to false
  • b: (int) - begin at datePublished unix timestamp. Default is not to restrict by date
  • e: (int) - end at datePublished unix timestamp. Default is not to restrict by date
  • f: (boolean) - include future-published items? (i.e. those whose datePublished is in the future). Default is true

####Output TBC - would be good to be configurable and use responseObject by default

###ah-tdp-content-item-plugin/getNewest ####Overview Retrieves the newest (most recent in terms of datePublished) versino of the specified content item.

####Parameters

• Required:
  • i (string) - the contentItemID (a reference string which is unique to one content item and consistent across all that content items versions)
• Optional:
  • l: (string) - language of versions to retrieve. Defaults to config.options.defaultLanguage if not specified

####Output TBC - would be good to be configurable and use responseObject by default

###ah-tdp-content-item-plugin/publish ####Overview Publish an existing content item/version.

####Parameters

• Required:
  • v (string) - either "all" to publish all versions of the content item or a specific content item version id (_id) to publish only one version. Be careful if publishing all versions of an item as this would make e.g. getNewest return unpredicatable results.
• Optional
  • i (string) - the contentItemID for the content item to publish
  • d (integer) - a unix timestamp to use as the datePublished. This can be a future date to allow for scheduled publishing or the current (or a previous) timestamp to publish immediately. Defaults to Date.now() if not specified.

####Output TBC - would be good to be configurable and use responseObject by default

###ah-tdp-content-item-plugin/unpublish ####Overview Unpublish an existing content item/version. This is achieved via setting datePublished to null.

####Parameters

• Required:
  • v (string) - either "all" to unpublish all versions of the content item or a specific content item version id (_id) to unpublish only one version
• Optional
  • i (string) - the contentItemID for the content item to unpublish

####Output TBC - would be good to be configurable and use responseObject by default

##Constructor The constructor is very simple and since the module is function-scoped, it requires the 'new' syntax in the constructor to instantiate a new instance e.g.:

var ah-tdp-content-item-plugin=require("ah-tdp-content-item-plugin");
api.TDPAHContentItem=new ah-tdp-content-item-plugin(api); // (where api is the actionhero api instance)
...

The module will self-initialise, using the actionhero environment-specific config options. A successful initialisation results in an object being returned.

Note that this instantiation would normally be run in an actionhero initialiser.

##Data structure The data structure in the MongoDB layer is essentially opaque as far as the end usage/user is concerned although if required, any fields can be updated using updateContentItemVersion() (see above). For reference, the data structure is currently as follows:

• contentItemVersion
  • _id (string - the stringified auto-generated MongoDB _id field)
  • friendlyName (string - a descriptive label for the contentItem, generally this would be the label by which the content item is displayed in an admin interface, it's not (generally) expected to be to be used on the front end)
  • contentItemID (string - a unique identifier for the contentItem (not the version) - similar to, for example, the "slug" in wordpress)
  • markdown (string - the raw markdown)
  • HTML (string - the HTML-ified markdown)
  • language (string - recommended that you use standard codes e.g. "en-GB")
  • datePublished (unix timestamp or null if not published)
  • dateCreated (unix timestamp)
  • dateLastModified (unix timestamp)
  • dateDeleted (unix timestamp or null if not deleted)

This structure implies that:

• Content items and their versions are grouped via contentItemID (and at least potentially friendlyName) and language
• The "current" version of an item is the one whose contentItemID and language are appropriate to the request and which has the newest (most recent), non-future datePublished
• Deletions are "soft" deletes - i.e. dateDeleted is set to a non-null value (usually the value of Date.now() upon deletion) and the logic will then ignore these items unless the "include deleted items" flag is set for relevant requests

##Public methods

###General principals All public methods conform to the below principals:

• They are asynchronous and thus receive a callback function as the last argument
• They will (in async mode) return two values, error and result, where:
  • error is a string, object or array if an error occurred, null otherwise
  • result is a string, object, array, number etc. on success, null otherwise
• They will never throw errors, instead they will return accordingly

###createContentItemVersion(properties, callback) Create a new content item (version) with the specified properties.

####Arguments #####properties (object) An object containing properties for the content item (version). Note that any specified properties which do not appear in the data strucure above will be ignored.

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives two arguments:

• err (string || null) - A descriptive error or null if no error occurred
• content-item (object || null) - the created content-item object (or null if an error occurred)

###getContentItemVersion(contentItemID, options, conditions, callback) Retrieve the specified content item (version) from the database.

####Arguments #####contentItemID (string) The contentItemID of the content item (version) to retrieve

#####options (object) An optional object which specified options for the retrieval. The structure is:

{
    n: (int or "all") number of records to return (mongoDB options.limit)
    o: order (string - see format). Format: e.g. fieldA:-1,fieldB:1 (1 is 'asc', -1 is 'desc' in SQL-like syntax)
    s: (int) skip s records
}

#####conditions (object) An optional object which specified conditions for the retrieval. The structure is:

{
    l: language (string) - defaults to config.options.defaultLanguage
    d: (boolean) include deleted items? (irrelevant if config.options.softDelete is false) - defaults to false
    u: (boolean) include unpubished items? - defaults to false
    b: (int) begin at datePublished unix timestamp - default is to ignore
    e: (int) end at datePublished unix timestamp - default is to ignore
    f: (boolean) include future-published items? (i.e. those whose datePublished is in the future) - default is false
}

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives two arguments:

• err (string || null) - A descriptive error or null if no error occurred
• content-item (array || null) - the retrieved content item (version) objects in an array (or null if an error occurred)

###deleteOrRestoreContentItemVersion(contentItemID, contentItemVersionID, action, callback) Delete or restore (un-delete) a content item - either one version or all.

####Arguments #####contentItemID (string) The contentItemID of the content item (version) to delete or restore.

#####contentItemVersionID (string) The MongoDB _id (in string form) for the specific version to delete or restore.

#####action (string) The action to perform - "delete" or "restore".

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives one argument:

• err (string || null) - A descriptive error or null if no error occurred (success)

###publishOrUnpublishContentItemVersionFn(contentItemVersionID, contentItemID, action, callback) Publish or un-publish a content item - either one version or all.

####Arguments #####contentItemID (string) The contentItemID of the content item (version) to publish or un-publish.

#####contentItemVersionID (string) The MongoDB _id (in string form) for the specific version to publish or un-publish.

#####action (string) The action to perform - "publish" or "unpublish".

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives one argument:

• err (string || null) - A descriptive error or null if no error occurred (success)

###updateContentItemVersionFn(contentItemVersionID, contentItemID, fieldsToUpdate, callback) Update one or more database fields for a content item (version).

####Arguments #####contentItemVersionID (string) The MongoDB _id (in string form) for the specific version to update.

#####contentItemID (string) The contentItemID of the content item (version) to update.

#####fieldsToUpdate (object) An object containing one or more properties which match those in the above data structure to update.

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives one argument:

• err (string || null) - A descriptive error or null if no error occurred (success)

##To do/roadmap

• Write some tests and integrate with Travis
• Ensure all user input is properly filtered
• Ensure indexes are correct and optimal
• Performance optimisation
• Delete/restore should allow filtering by language
• Consider implementing hard deletes
• Consider a configurable garbage collector (probably an actionhero task) to remove old, deleted items after a period of time
• Make my ACL module default permissions appropriate to the default actions in this plugin for ease of use
• Remove hard-coded variable/property names - use config instead

##Tests Tests currently run automatically in travis and use mocha and should.

##License ah-tdp-content-item-plugin is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original aclor(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.