-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #145 from collective/update-docs
Update documentation
- Loading branch information
Showing
71 changed files
with
1,309 additions
and
1,133 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,20 @@ | ||
# gatsby-source-plone | ||
|
||
Gatsby is a blazing fast static site generator for React. By using Plone as source, this can be used to generate a static site with PWA features with something equivalent to the click of a button. That’s the essence of the **“Big Green Button”** proposal, according to **Martin Aspeli**, who wrote a blog post **"[Pete and Andy try Plone 4](http://www.martinaspeli.net/articles/pete-and-andy-try-plone-4)"**: | ||
[GatsbyJS](https://www.gatsbyjs.org/) is a generator for blazing fast static web sites or web apps powered by pre-rendered [ReactJS](https://reactjs.org/). With this plugin, you can build any amount of gatsby sites from a single [Plone CMS](https://plone.org/), the ultimate open source enterprise CMS. | ||
|
||
_"Andy goes to Plone's Deployment control panel. There he finds a Big Green Button. | ||
He pushes it and covers his eyes. A minute later, a bunch of static HTML files appear in a directory on the server, covering the Plone site, with basic navigation and a site map. Search is provided via a form that posts to Google for search results on the current site."_ | ||
This gatsby-source plugin pulls the whole content tree from a Plone site (or its sub-folder) using [Plone REST API](https://plonerestapi.readthedocs.io/en/latest/) and makes it available for querying via GraphQL in a Gatsby based project. | ||
|
||
A gatsby-source plugin pulls the whole content tree from the plone.restapi and makes it available for querying via GraphQL in a hierarchical data structure. The gatsby-plone-starter that uses the plugin to source the data from a Plone site will illustrate all use cases of the plugin in a Gatsby project. | ||
Common use-cases include to | ||
|
||
* spin-off practically unlimited amount of individually hosted, branded and featured static sites from content managed in a single Plone instance without side-effects to the Plone instance in question | ||
|
||
* allow mixed use of Plone, where small individually branded ˝poster sites˝ could be published from larger Plone site with unified theme without need for hosting secondary CMS instances for a such need | ||
|
||
* build mash-ups mixin Plone content with content from file-system or other sources. | ||
|
||
No Plone knowledge should be required to use this plugin. Just follow the examples in gatsby-starter-plone and the official Gatsby user documentation. | ||
|
||
A Plone add-on [collective.webhook](https://pypi.org/project/collective.webhook/) can be used to trigger CI pipelines to rebuild and deploy sites after any change in Plone content. | ||
|
||
_˝Andy goes to Plone’s Deployment control panel. There he finds a Big Green Button. | ||
He pushes it and covers his eyes. A minute later, a bunch of static HTML files appear in a directory on the server, covering the Plone site, with basic navigation and a site map. Search is provided via a form that posts to Google for search results on the current site.˝_ –Martin Aspeli, 2009, ˝[Pete and Andy try Plone 4](http://www.martinaspeli.net/articles/pete-and-andy-try-plone-4)˝ |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
# Authenticating REST API calls | ||
|
||
For Plone sites requiring authentication to use Plone REST API (or limiting publishable content by permissions of specific user) you may use this guide to set up a safe method of authentication using [JWT](http://plonerestapi.readthedocs.io/en/latest/authentication.html#json-web-tokens-jwt) and [dotenv](https://github.com/motdotla/dotenv) configuration. | ||
|
||
**Note:** In time of writing, Plone REST API only created tokens valid for the next 12 hours. | ||
|
||
In UNIX-like systems (OSX, Linux, Linux subsystem for Windows), a bash script would serve as a good way to retrieve the JWT from plone.restapi, by prompting for username and password: | ||
|
||
```bash | ||
bash | ||
read -p "Username: " USERNAME | ||
read -sp "Password: " PASSWORD | ||
curl -s -X POST http://localhost:8080/Plone/@login -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"login": "'"$USERNAME"'", "password": "'"$PASSWORD"'"}' | ||
exit | ||
``` | ||
The above script will | ||
|
||
1. enter a new bash environment | ||
2. read username into environment variable | ||
3. read password into environment variable without displaying it when you type | ||
4. request authorization token | ||
5. exit bash to forget environment variables. | ||
|
||
This would give you a token as output: | ||
|
||
```json | ||
{ | ||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6IkpvaG4gRG9lIiwic3ViIjoidXNlcm5hbWUiLCJleHAiOjE1Mjc0NDk0NTl9.epewKm09S6JXe07Ha6UNicN7v9MT32Rrkflxq2OqVRI" | ||
} | ||
``` | ||
|
||
Install dotenv and setup `.env` with the token so that it can be used in the Gatsby project: | ||
|
||
```bash | ||
// Install dotenv | ||
yarn install dotenv | ||
|
||
|
||
// In .env in the project folder | ||
TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6IkpvaG4gRG9lIiwic3ViIjoidXNlcm5hbWUiLCJleHAiOjE1Mjc0NDk0NTl9.epewKm09S6JXe07Ha6UNicN7v9MT32Rrkflxq2OqVRI | ||
``` | ||
|
||
Finally setup `gatsby-config.js` to use this in your project: | ||
|
||
```javascript | ||
// Top of your file | ||
require("dotenv").config({ | ||
path: '.env', | ||
}); | ||
|
||
// In plugins list | ||
module.exports = { | ||
resolve: 'gatsby-source-plone', | ||
options: { | ||
baseUrl: 'http://localhost:8080/Plone/', | ||
token: process.env.TOKEN, | ||
} | ||
}; | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
# Supported REST API expansions | ||
|
||
This source plugin only supports fixed set of Plone REST API expansions, currently *breadcrumbs* and *navigation*, which are both published as their own GraphQL nodes, *PloneBreadcrumbs* and *PloneNavigation* respectively. | ||
|
||
Expansions are [plone.restapi](https://plonerestapi.readthedocs.io/en/latest/expansion.html) mechanism to embed additional “components”, such as _navigation, breadcrumbs, schema,_ or _workflow_ within the main content response, helping the API consumers to avoid unnecessary requests. | ||
|
||
For instance, a normal GET request to `http://localhost:8080/Plone` would give the following response: | ||
|
||
```json | ||
{ | ||
"@components": { | ||
"actions": { | ||
"@id": "http://localhost:8080/Plone/@actions" | ||
}, | ||
"breadcrumbs": { | ||
"@id": "http://localhost:8080/Plone/@breadcrumbs" | ||
}, | ||
"navigation": { | ||
"@id": "http://localhost:8080/Plone/@navigation" | ||
} | ||
}, | ||
"@id": "http://localhost:8080/Plone", | ||
"@type": "Plone Site", | ||
"id": "Plone", | ||
"...": "..." | ||
} | ||
``` | ||
|
||
But in the case we need the _breadcrumbs, navigation_ data or so on, we'll need to make more requests to `/@breadcrumbs`, `/@navigation` and more depending on the data we need. | ||
|
||
Expansions simplifies this process by retrieving all data in a single request as `http://localhost:8080/Plone?expand=breadcrumbs,navigation` giving the response: | ||
|
||
```json | ||
{ | ||
"@components": { | ||
"actions": { | ||
"@id": "http://localhost:8080/Plone/@actions" | ||
}, | ||
"breadcrumbs": { | ||
"@id": "http://localhost:8080/Plone/@breadcrumbs", | ||
"items": [] | ||
}, | ||
"navigation": { | ||
"@id": "http://localhost:8080/Plone/@navigation", | ||
"items": [ | ||
{ | ||
"@id": "http://localhost:8080/Plone", | ||
"description": "", | ||
"title": "Home" | ||
}, | ||
{ | ||
"@id": "http://localhost:8080/Plone/news", | ||
"description": "News on gatsby-source-plone development", | ||
"title": "News" | ||
}, | ||
{ | ||
"@id": "http://localhost:8080/Plone/index", | ||
"description": "", | ||
"title": "gatsby-source-plone" | ||
}, | ||
{ | ||
"@id": "http://localhost:8080/Plone/search_traversal", | ||
"description": "", | ||
"title": "Traversal using @search endpoint" | ||
}, | ||
{ | ||
"@id": "http://localhost:8080/Plone/plugin_options", | ||
"description": "", | ||
"title": "Plugin Options" | ||
}, | ||
{ | ||
"@id": "http://localhost:8080/Plone/testcases", | ||
"description": "A folder with different standard content types that Plone supports out of the box", | ||
"title": "Testcases" | ||
} | ||
] | ||
} | ||
}, | ||
"@id": "http://localhost:8080/Plone?expand=breadcrumbs%2Cnavigation", | ||
"@type": "Plone Site", | ||
"id": "Plone", | ||
"is_folderish": true, | ||
"...": "..." | ||
} | ||
``` |
Oops, something went wrong.