Apps Getting Started for Ghost Devs

This guide is a description of the set of APIs and tools which are currently in a state of constant change as we work through the Ghost Apps project solidifying and standardising how things will work. This documentation exists so that those developers who are working on the project can keep up to date and are able to build demo Apps for the purpose of building & testing the App Platform. This is not intended as a guide for App developers just yet. We may scrap the whole lot and start again at any moment 😉

---

Note: This has been updated for Ghost-App 0.0.2 - breaking changes

---

Creating

Ghost Apps are created by extending the Ghost-App boilerplate.

Create a new folder in your content/apps folder, for now the folder name is your app name. Permitted characters: a-z, 0-9, _, -.

Inside the folder, create a package.json and an index.js file.

package.json should include version and dependencies:

{
  "name":"my-app",
  "version": "0.0.x",
  "dependencies": {
    "ghost-app": "0.0.2"
  }
}

index.js should look like:

var App = require('ghost-app'),

    MyApp;

MyApp = App.extend({

    install: function () {},

    uninstall: function () {},

    activate: function () {},

    deactivate: function () {}

});

module.exports = MyApp;

Proxy

The proxy object is available inside any lifecycle function as this.ghost. For example you could do the following in the activate method and see the title 'Welcome to Ghost' output on startup:

this.ghost.api.posts.read(1).then(function (post) {
    console.log(post.title);
});

Filters

Filters are available via the proxy, or via a special syntax as part of the app lifecycle:

MyApp = App.extend({
    filters: {
       ghost_head: 'handleGhostHead',
       ghost_foot: [9, 'handleGhostFoot']
    },
    handleGhostHead: function () {},
    handleGhostFoot: function () {}
});

The array syntax can be used to provide an optional priority, the default is 5.

Note: Permissions should be added to package.json

    "ghost": {
        "permissions": {
            "filters": ["ghost_head", "ghost_foot"]
        }
    }

Handlebars helpers

There is no special syntax available for handlebar helpers (see https://github.com/TryGhost/Ghost-App/issues/14), so use the proxy object like so:

activate: function () {
    console.log('MyApp: activate()');
    this.ghost.helpers.register('my_helper', this.handleMyHelper);
}

handleMyHelper: function() {
    return('foo bar baz');
}

Installing

Open up your database, and add the name of your app to activeApps in the settings table.

For example, if your app's folder name is example-app, the value of activeApps should be ["example-app"]. Double quotes are required.

If your database is not huge, you can easily modify it like so:

• SETTINGS > Labs > Export

• Open the exported .json file with a text editor

• Replace "key":"activeApps","value":"[]"
  with "key":"activeApps","value":"[\"example-app\"]"

• SETTINGS > Labs > Delete all Content

• SETTINGS > Labs > Import

(TODO: Confirm that this brute force procedure does not have undesired side effects!)

Or, if you prefer something pointy-clicky: "the DB Browser for SQLite"

Once added, restart Ghost and your app will be installed & loaded.

Changelog

0.0.2

• Removed .App from boilerplate signature
• Added new filter syntax inc using deregister instead of unregister
• Switched underscore to lodash

0.0.1 Initial publish