Skip to content
This repository has been archived by the owner on Nov 26, 2021. It is now read-only.

Commit

Permalink
feat: Refactor most of it
Browse files Browse the repository at this point in the history 
Refactored base structure, added coverage and semantic-release.
  • Loading branch information
@stefanjudis
stefanjudis committed Aug 29, 2016
1 parent 20ebdd1 commit 6f7c795
Show file tree
Hide file tree
Showing 31 changed files with 1,639 additions and 356 deletions.
1 change: 1 addition & 0 deletions .editorconfig
View file
@@ -1,3 +1,4 @@
[*.js]
indent_style = space
indent_size = 2
insert_final_newline = true
3 changes: 3 additions & 0 deletions .eslintrc
View file
@@ -0,0 +1,3 @@
{
"extends": "standard"
}
3 changes: 3 additions & 0 deletions .gitignore
View file
@@ -1 +1,4 @@
node_modules
.vscode
test/build
.nyc_output
8 changes: 0 additions & 8 deletions .jshintrc
View file

This file was deleted.

16 changes: 16 additions & 0 deletions .npmignore
View file
@@ -0,0 +1,16 @@
.*.swp
._*
.DS_Store
.git
.hg
.npmrc
.lock-wscript
.svn
.wafpickle-*
config.gypi
CVS
npm-debug.log
*.spec.js
test
.vscode
.nyc_output
22 changes: 22 additions & 0 deletions .travis.yml
View file
@@ -0,0 +1,22 @@
sudo: false
language: node_js
cache:
directories:
- node_modules
notifications:
email: false
node_js:
- '6'
- '4'
before_install:
- npm i -g npm@^2.0.0
before_script:
- npm prune
after_success:
- 'curl -Lo travis_after_all.py https://git.io/travis_after_all'
- python travis_after_all.py
- export $(cat .to_export_back) &> /dev/null
- npm run semantic-release
branches:
except:
- /^v\d+\.\d+\.\d+$/
258 changes: 108 additions & 150 deletions README.md
View file
@@ -1,178 +1,136 @@
# contentful-metalsmith
[![Build Status](https://travis-ci.org/contentful-labs/contentful-metalsmith.svg?branch=master)](https://travis-ci.org/contentful-labs/contentful-metalsmith)
[![Coverage Status](https://coveralls.io/repos/github/contentful-labs/contentful-metalsmith/badge.svg?branch=refactor)](https://coveralls.io/github/contentful-labs/contentful-metalsmith?branch=refactor)

A Metalsmith's plugin to get content from [Contentful](http://www.contentful.com)
A Metalsmith' plugin to generate files using content from [Contentful](http://www.contentful.com)

[![No Maintenance Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/)
## About

## Deprecation notice
This plugin for [metalsmith](http://www.metalsmith.io) allows you to build a static site using the data stored at [Contentful](http://www.contentful.com). It is built on top of the [Contentful JavaScript Client](https://github.com/contentful/contentful.js).

This project has not been maintained for some time and won't be maintained moving forward.
## Getting started

While it might work with some older versions of metalsmith, it's known not to work with more recent versions.
### Install

## About
```bash
$ npm install contentful-metalsmith
```

This plugin for [metalsmith](http://www.metalsmith.io) allows you to build a static site using the data stored at [Contentful](http://www.contentful.com). This
plugin is built on top of the [Contentful JavaScript Client](https://github.com/contentful/contentful.js).
### Configure required globals

## TL;DR
When you use metalsmith using the [cli](https://github.com/metalsmith/metalsmith#cli) edit your `metalsmith.json` and add `contentful-metalsmith` in the plugins section.

1. Install it
```javascript
// metalsmith.json

```javascript
$ npm install contentful-metalsmith
```
2. Configure it (example for [metalsmith CLI](https://github.com/segmentio/metalsmith#cli))
{
"source": "src",
"destination": "build",
"plugins": {
"contentful-metalsmith": {
"access_token": "YOUR_CONTENTFUL_ACCESS_TOKEN",
"space_id": "YOUR_CONTENTFUL_SPACE_ID"
}
}
}
```

```javascript
$ vim metalsmith.json
When you use the [JavaScript Api](https://github.com/metalsmith/metalsmith#api) add `contentful-metalsmith` to the used plugins.

----
```javascript
metalsmith.source('src')
metalsmith.destination('build')

{
"source": "src",
"destination": "build",
"plugins": {
...,
"contentful-metalsmith": {
"accessToken" : "YOUR_CONTENTFUL_ACCESS_TOKEN"
},
...
}
}
```

3. Create a source file

```html

---
title: OMG metalsmith-contentful
contentful:
space_id: AN_SPACE_ID
template: entries.html
---

[OPTIONAL CONTENT]
```

4. Create the template (handlebarsjs on this case)

```html
<!doctype html>

<html lang="en">
<head>
<meta charset="utf-8">

<title>Contentful-metalsmith plugin example</title>
<meta name="description" content="No description">
<meta name="author" content="Contentful">

</head>

<body>

{{contents}}
<table>
<thead>
<tr>
<th>Type</th>
<th>Id</th>
<th>Updated</th>
</tr>
</thead>
<tbody>
{{#each contentful.entries}}
<tr>
<td>
{{this.data.sys.contentType.sys.id}}
</td>
<td>
{{this.data.sys.id}}
</td>
<td>
{{this.data.sys.updatedAt}}
</td>
</tr>
{{/each}}
</tbody>
</table>
</body>
</html>
```

5. Enjoy

# Usage

The first thing that you have to do to use this plugin is to install and configure it (see the TL;DR section for that). Once you have done this you can create and setup source files to fetch data from [Contentful](http://www.contentful.com).

## Setup a source file

To fetch data from [Contentful](http://www.contentful.com) you have to include some extra metadata in a metalsmith source file. The available configuration parameters are the following:

* `space_id` (**required**), the id of the space from where you want to get entries.
* `entry_template` (optional), the template that will be used to render each individual entry.
* `filter` (optional), this parameter has to include some of the [filtering options](https://www.contentful.com/developers/documentation/content-delivery-api/http/#search) offered by the [Contentful's Content Delivery API](https://www.contentful.com/developers/documentation/content-delivery-api/).

All this parameters have to be nested under the key `contentful`.


An example:

```yaml

---
title: OMG metalsmith-contentful
contentful:
space_id: cfexampleapi
content_type: cat
filter:
sys.id[in]: 'finn,jake'
entry_template: entry.html
template: example.html
---
metalsmith.use(require('contentful-metalsmith')({ 'access_token' : 'YOUR_CONTENTFUL_ACCESS_TOKEN' }))
```

## Using the fetched entries on the templates
**Global parameters:**

- `acccess_token`
- `space_id`

You can find the `access_token` and `space_id` in your [app](https://app.contentful.com) at `APIs -> Content delivery API Keys`.

We have to make a distinction between two types of templates:
------------------------------

* The template rendered for the source file.
* And the template rendered for each individual entry.
To read more on all global parameters and settings read the [global settings documentation](./docs/global-settings.md).

In the context of the template rendered for the source file you will have access to a property named `contentful`. This property holds the following properties:
### Create files based on the files defined in your source folder

* `entries`, an array with all the fetched entries. The structure of each of this entry objects will be the same as the explained below for the entry template.
* `contentTypes`, an object with the id of the fetched [contentTypes](https://www.contentful.com/developers/documentation/content-delivery-api/http/#content-types) as keys. Under each key there will be an array with all the entries belonging to that particular contentType.
We're considering that you use [metalsmith-layouts](https://github.com/superwolff/metalsmith-layouts) for file rendering. That for the `layout` key is used for rendered source files and child templates.

In the context of the template rendered for an individual entry you will have access to the following properties under the property `data`:
*`source/posts.html`*

* `id`, a shortcut to the entry's id.
* `contentType`, a shortcut to the entry's contentType.
* `data`, the body of the entry as returned by [Contentful's Content Delivery API](https://www.contentful.com/developers/documentation/content-delivery-api/)
```markdown
---
title: metalsmith-contentful file
contentful:
content_type: post
layout: post.html
layout: posts.html
---

## Entry filename config
Following from the example above there are some options to help with getting the structure output:
```yaml
---
title: OMG metalsmith-contentful
contentful:
space_id: cfexampleapi
content_type: cat
entry_template: entry.html
entry_filename_pattern: :sys.locale/:fields.slug
permalink_style: true
use_template_extension: true
template: example.html
---
[OPTIONAL CONTENT]
```

* `entry_filename_pattern` takes a pattern similar to the permalink plugin where you can reference Contentful system and user entered fields, prefixed `sys.` and `field.` respectively.
* `permalink_style` will name a directory with the last part of the pattern and add an `index.html` for the file content. e.g. `my/file/path.html` vs. `my/file/path/index.html`.
* `use_template_extension` is only required if you want the extension to match the template extension. `.html` is used by default.
*`layouts/posts.html`*

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{title}}</title>
<meta name="description" content="No description">
<meta name="author" content="Contentful">
<link rel="stylesheet" href="scss/style.css?v=1.0">
</head>
<body>
<ul>
<!-- available data fetched from contentful -->
{{#each data.entries }}
<li>
<h2>{{fields.title}}</h2>
<p>{{fields.description}}</p>
<p><a href="{{_fileName}}">Read more</a></p>
</li>
{{/each}}
</ul>
{{contents}}
</body>
</html>
```

*`layouts/post.html`*

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{data.fields.title}}</title>
<meta name="description" content="No description">
<meta name="author" content="Contentful">
<link rel="stylesheet" href="scss/style.css?v=1.0">
</head>
<body>
<h1>{{data.fields.title}}<h1>
<p>{{data.fields.description}}</p>

{{contents}}
</body>
</html>
```

**This example will**

- render `posts.html` providing data of the entries of content type `post`
- render several single files with the template `post.html` providing the data of a particular post

------------------------------

To read more on source file parameters and settings read the [source file documentation](./docs/source-file-settings.md).

# License
MIT

MIT

0 comments on commit 6f7c795

Please sign in to comment.