mirror of
https://github.com/wassname/talk.git
synced 2026-09-11 12:51:33 +08:00
Add plugins overview and quickstart
This commit is contained in:
David Erwin
@@ -1,7 +1,5 @@
|
||||
# Talk Plugins
|
||||
|
||||
Plugins for Talk can take various forms, currently we are only supporting server
|
||||
side plugins.
|
||||
|
||||
## Plugin Registration
|
||||
|
||||
|
||||
@@ -18,6 +18,9 @@ entries:
|
||||
- title: Installation
|
||||
output: web
|
||||
folderitems:
|
||||
- title: Getting Started
|
||||
output: web
|
||||
url: /install.html
|
||||
- title: Configuration
|
||||
output: web
|
||||
url: /configuration.html
|
||||
@@ -34,6 +37,12 @@ entries:
|
||||
- title: Plugins
|
||||
output: web
|
||||
folderitems:
|
||||
- title: Quickstart
|
||||
url: /plugins-quickstart.html
|
||||
output: web
|
||||
- title: Overview
|
||||
url: /plugins-overview.html
|
||||
output: web
|
||||
- title: Client API
|
||||
url: /plugins-client.html
|
||||
output: web
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Installation
|
||||
sidebar: talk_sidebar
|
||||
permalink: install.html
|
||||
summary:
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
Talk requires MongoDB and Redis.
|
||||
|
||||
- MongoDB ^3.2 - [Docs](https://docs.mongodb.com/manual/installation/)
|
||||
- Redis ^3.2.5 - [Docs](https://redis.io/topics/quickstart)
|
||||
|
||||
## Installation method
|
||||
|
||||
While Talk can be installed in many ways, we support two install paths:
|
||||
|
||||
* [Install from Source](install-source.html) (development)
|
||||
* [Install via Docker](install-docker.html) (deployment)
|
||||
|
||||
If you have success installing Talk in another way, please consider [contributing to this documentation](faq.html#how-do-i-contribue-to-these-docs)!
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Plugins Overview
|
||||
keywords: plugins
|
||||
sidebar: talk_sidebar
|
||||
permalink: plugins-overview.html
|
||||
summary:
|
||||
---
|
||||
|
||||
## Plugin Registration
|
||||
|
||||
In order for a plugin to be active in a Talk install, it must be _registered_. The parsing order for the plugin registration is as follows:
|
||||
|
||||
- `TALK_PLUGINS_JSON` environment variable
|
||||
- `plugins.json` file
|
||||
- `plugins.default.json` file
|
||||
|
||||
If you need to "disable all plugins", you can simply provide `{}` as the
|
||||
contents of `process.env.TALK_PLUGINS_JSON` or the `plugins.json`.
|
||||
|
||||
The format for this is thus:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
"people"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Where we have a `server` key with an array of plugins that match the folder
|
||||
name in the `plugins/` folder. For example, the above config would
|
||||
require a plugin from `plugins/people`, which must provide a `index.js` file
|
||||
that returns an object that matches the Plugin Specification.
|
||||
|
||||
If the package is external (available on NPM) you can specify the string for
|
||||
the version by using an object instead, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
{"people": "^1.2.0"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
External plugins can be resolved by running:
|
||||
|
||||
```bash
|
||||
./bin/cli plugins reconcile
|
||||
```
|
||||
|
||||
This achieves two things:
|
||||
|
||||
1. It will traverse into local plugin folders and install their dependencies.
|
||||
_Note that if the plugin is already installed and available in the node_modules folder, it will not be
|
||||
fetched again unless there is a version mismatch._ This will result in the
|
||||
project `package.json` and `yarn.lock` files to be modified, this is normal as
|
||||
this ensures that repeated deployments (with the same config) will have the
|
||||
same config, these changes should not be committed to source control.
|
||||
2. It will seek out dependencies that are listed in the object notation and try
|
||||
to install them from npm.
|
||||
|
||||
## Plugin Dependencies
|
||||
|
||||
You may also include additional external dependencies in your local packages by
|
||||
specifying a `package.json` at your plugin root which will result in a
|
||||
`node_modules` folder being generated at the plugin root with your specific
|
||||
dependencies.
|
||||
|
||||
## Deployment Solutions
|
||||
|
||||
Plugins can be deployed with a production instance of Talk.
|
||||
|
||||
### Source
|
||||
|
||||
Source deployments can just modify the `plugins.json` file and include any
|
||||
local plugins into the `plugins/` directory. After including the config, you
|
||||
need to reconcile the plugins and build the static assets:
|
||||
|
||||
```bash
|
||||
# get plugin dependancies and remote plugins
|
||||
./bin/cli plugins reconcile
|
||||
|
||||
# build staic assets (including enabled client side plugins)
|
||||
yarn build
|
||||
```
|
||||
|
||||
Then the application can be started as is.
|
||||
|
||||
### Docker
|
||||
|
||||
If you deploy using Docker, you can extend from the `*-onbuild` image, an
|
||||
example `Dockerfile` for your project could be:
|
||||
|
||||
```Dockerfile
|
||||
FROM coralproject/talk:latest-onbuild
|
||||
```
|
||||
|
||||
Where the directory for your instance would contain a `plugins.json` file
|
||||
describing the plugin requirements and a `plugins` directory containing any
|
||||
other local plugins that should be included.
|
||||
|
||||
Onbuild triggers will execute when the image is building with your custom
|
||||
configuration and will ensure that the image is ready to use by building all
|
||||
assets inside the image as well.
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
title: Plugins Quickstart
|
||||
keywords: plugins
|
||||
sidebar: talk_sidebar
|
||||
permalink: plugins-quickstart.html
|
||||
summary:
|
||||
---
|
||||
|
||||
I would like to create a plugin that allows my CMS to update asset information.
|
||||
|
||||
## Setup the environment
|
||||
|
||||
Before I begin working on the plugin, I've installed [Talk from source](/install-source.html).
|
||||
|
||||
### Watch the Server
|
||||
|
||||
In a terminal, I run `yarn dev-start`. This command:
|
||||
|
||||
* starts my server, showing plugin and configuration information
|
||||
* restarts it when I save files
|
||||
* shows my temporary `console.log()` statements here
|
||||
* shows real time access logs
|
||||
* shows verbose debug output if enabled (more on this later)
|
||||
|
||||
|
||||
|
||||
### Watch the Client build process
|
||||
|
||||
In another window I run `yarn build-watch`. This command:
|
||||
|
||||
* builds the client side javascript bundles
|
||||
* watches relevant files and rebuilds the bundle on change
|
||||
* displays _compile time_ errors, including (the many) syntax errors I cause
|
||||
|
||||
If you need to run `yarn install`, you will see missing module error messages here.
|
||||
|
||||
### Watch from the Browser
|
||||
|
||||
I open up `http://localhost:3000` in a web browser and see the default comment stream. I then open the dev tools console which:
|
||||
|
||||
* shows any _run time_ errors/warnings generated on the front end.
|
||||
* shows any temporary `console.log()` statements I add during development.
|
||||
|
||||
I also often toggle to the Network Tab to see:
|
||||
|
||||
* which files are being loaded
|
||||
* requests sent from my front end code, including headers, the payload/queries sent and the data returned
|
||||
|
||||
## Create a home for my new plugin
|
||||
|
||||
I want to build this plugin locally, using source control and eventually publish it to npm.
|
||||
|
||||
### Create a repo
|
||||
|
||||
I create a new repo called `talk-plugin-asset-manager`. (I use github, but this you could store this anywhere, bitbucket, svn, etc...)
|
||||
|
||||
_make sure to respect the naming convention `talk-plugin-*`. This will allow for easy identification of the repo and, eventually, easy searching on npm._
|
||||
|
||||
### Set up a local file structure
|
||||
|
||||
I like to put my plugins in a directory next to talk, but you could put this anywhere.
|
||||
|
||||
```
|
||||
cd ..
|
||||
git clone https://github.com/jde/talk-plugin-asset-manager.git
|
||||
```
|
||||
|
||||
### Register your plugin
|
||||
|
||||
Add the plugin to the plugins.json file:
|
||||
|
||||
```
|
||||
{
|
||||
"server": [
|
||||
...
|
||||
"talk-plugin-asset-manager"
|
||||
],
|
||||
"client": [
|
||||
...
|
||||
// no client side components so I won't add it here
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
But wait! Talk looks in `talk/plugins/[plugin-name]` for plugin code. Why couldn't we just add that plugin there?
|
||||
|
||||
We could have.
|
||||
|
||||
This would make it _a little_ easier to register, but _a lot_ harder to cleanly manage in version control. In order to avoid it being sucked into your Talk repo, you would have to manually `.gitignore` it or use [sub modules]() or something similar.
|
||||
|
||||
As a user of a Linux_y_ os, I prefer to create a symbolic link.
|
||||
|
||||
```
|
||||
cd /path/to/talk/plugins
|
||||
ln -s /path/to/your/plugin
|
||||
```
|
||||
|
||||
or in this case:
|
||||
|
||||
```
|
||||
cd ../talk/plugins
|
||||
ln -s ../../talk-plugin-asset-manager
|
||||
```
|
||||
|
||||
Now, as far as Talk knows, our plugin is right there in the folder. Git is wise, however, and will not include it in the Talk repo. Best of all, our `yarn dev-start` based watch statement follows symbolic links and will restart our sever each time a file is saved.
|
||||
|
||||
### Create the initial index file
|
||||
|
||||
All plugins contain server and/or client index files, which export all plugin functionality.
|
||||
|
||||
```
|
||||
// talk-plugin-asset-manager/index.js
|
||||
module.exports = {};
|
||||
```
|
||||
Reference in New Issue
Block a user