univunix / docpad-plugin-api

Plugin that injects your custom api into Docpad.

Api Plugin for DocPad

Due to the closing of Docpad project in 1/2/2018, this plugin won't receive any extra feature. Only critical bugs will be solved. Benjamin said that Docpad will get updates, but he will work as a side-project. We will add features if it's necessary.

How to use the plugin

First, create your API. You have to use Javascript as language and you can use NodeJS or ExpressJS methods and objects.

Each Javascript file must have this structure:

// Each module.exports MUST BE a function with these two arguments
module.exports = function (opts, baseApiUrl){
  // The ExpressJS server is an attribute of opts.
  var server = opts.server

  // You can use ExpressJS functions (version 3.x)
  server.get(baseApiUrl + '/test', function (req, res, next) {
    return res.json({
      test: 'OK'
    })
  })

  server.get('/bbbb', function (req, res, next) {
    var err = new Error()
    next(err)
  })
}

Second, you need to create the api configuration file. It's in JSON format. This is the new step for newer versions, because you can set different apis using multiple configuration files.

You can name it as you want. In my case, I call it "dpaconfig.json"

{
  "baseApiUrl": "/testone",
  "src": [
    "testapi1/src/test11.js",
    "testapi1/src/test12.js"
  ]
}

Notes about dbaconfig.json file:

• It's required to set the baseApiUrl and src variables.
• The src routes have to be relative to Docpad website root folder (the same level as docpad configuration file).

Finally, set the route of each dpaconfig file in Docpad configuration file.

plugins:
  api:
    cfgSrc: [
      'testapi1/dpaconfig.json',
      'testapi2/dpaconfig.json',
      'testapi0/dpaconfig.json'
    ]

Notes about configuration: *You have to set relative routes using Docpad root folder as base.

And we're done. Enjoy your custom api without refactoring to ExpressJS.

Install

Install this DocPad plugin by entering docpad install api into your terminal.

History

Discover the release history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• Ángel González

Sponsors

No sponsors yet! Will you be the first?

Contributors

These amazing people have contributed code to this project:

• Ángel González — view contributions
• Benjamin Lupton — view contributions
• Michael Duane Mooring — view contributions
• Rob Loach — view contributions
• vsopvsop — view contributions
• fer2d2 — view contributions

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

License

Unless stated otherwise all works are:

• Copyright © UnivUnix

and licensed under:

• MIT License

docpad-plugin-api's Issues

Change name 'uri' parameter to 'file'.

Because it's a local file address, not in network.

Make good documentation.

Update documentation before releasing 2.2 final.

New file loading system.

This is the current system:

• The plugin loads an array of file routes, all of them are set in docpad.coffee.
• All api entries are called from a unique base url.

Proposed new system:

• We will load multiple JSON files from docpad.coffee.
• The JSON file contains a list of file routes and a base url. So we can load different apis without mixing them.
• Also, each JSON file will set specific configuration for each api.

The benefits of the new system are:

• Loading different apis using different base urls.
• We can use two versions of the same api without refactoring old version.
• We can isolate each api, reducing debugging complexity.

Fixing TravisCI configuration.

Due to continuous failures in TravisCI because my configuration is not working, I will research a way to get working. I think that Balupton (Docpad creator) have some scripts for it.

This issue will apply to 2.2.x and 2.1.x branches.

Converting from Coffeescript to ES6.

According with future development of Docpad (Issue docpad/docpad#1046). I will do the same thing on this plugin for next milestone.

Move javascript loading function from serverExtend to docpadReady or docpadLoaded

I suspect that the crashes in Travis CI (#11) are caused by this issue. Also, I have new requirements with this plugin. Maybe I need to use the other events provided by Docpad (get templateData from Docpad in JSON format for AJAX calls).

Load API file from configured location.

Return HTTP errors in JSON format when the called url matches with API base url.

Allow multiple API formats.

Do you have any suggestion? Write it here.

If you want to suggest new features related with this plugin, you can put them here. I will read them and put them in independent issues if I can do them.

Thank you in advance.

Due to the closing of Docpad project in 1/2/2018, no extra features will be provided to this plugin.

Update to latest Docpad version.

Docpad updates API when it detects changes.

I must check if it's possible to do that.

Adding multiple API files instead of only one.