|
| 1 | +<div align="center"> |
| 2 | + <img width="150" height="150" title="PostHTML" src="https://posthtml.github.io/posthtml/logo.svg"> |
| 3 | + <h1>Fetch Remote Content</h1> |
| 4 | + <p>A plugin for fetching and working with remote content</p> |
| 5 | + |
| 6 | + [![Version][npm-version-shield]][npm] |
| 7 | + [![License][license-shield]][license] |
| 8 | + [![Build][travis-ci-shield]][travis-ci] |
| 9 | + [![Downloads][npm-stats-shield]][npm-stats] |
| 10 | +</div> |
| 11 | + |
| 12 | +## About |
| 13 | + |
| 14 | +This plugin allows you to fetch remote content and display it in your HTML. |
| 15 | + |
| 16 | +Input: |
| 17 | + |
| 18 | +```html |
| 19 | +<fetch url="https://jsonplaceholder.typicode.com/users/1"> |
| 20 | + {{ response.name }}'s username is {{ response.username }} |
| 21 | +</fetch> |
| 22 | +``` |
| 23 | + |
| 24 | +Output: |
| 25 | + |
| 26 | +```html |
| 27 | +Leanne Graham's username is Bret |
| 28 | +``` |
| 29 | + |
| 30 | +## Install |
| 31 | + |
| 32 | +``` |
| 33 | +$ npm i posthtml posthtml-fetch |
| 34 | +``` |
| 35 | + |
| 36 | +## Usage |
| 37 | + |
| 38 | +```js |
| 39 | +const posthtml = require('posthtml') |
| 40 | +const pf = require('posthtml-fetch') |
| 41 | + |
| 42 | +posthtml() |
| 43 | + .use(pf()) |
| 44 | + .process('<fetch url="https://example.test">{{ response }}</fetch>') |
| 45 | + .then(result => console.log(result.html)) |
| 46 | + |
| 47 | + // response body |
| 48 | +``` |
| 49 | + |
| 50 | +The response body will be available under the `response` local variable. |
| 51 | + |
| 52 | +## Response types |
| 53 | + |
| 54 | +The plugin supports `json` and `text` responses. |
| 55 | + |
| 56 | +Only the response body is returned. |
| 57 | + |
| 58 | +## Expressions |
| 59 | + |
| 60 | +The plugin uses [`posthtml-expressions`](https://github.com/posthtml/posthtml-expressions), so you can use any of its tags to work with the `response`. |
| 61 | + |
| 62 | +For example, you can iterate over items in a JSON response: |
| 63 | + |
| 64 | +```html |
| 65 | +<fetch url="https://jsonplaceholder.typicode.com/users"> |
| 66 | + <each loop="user in response"> |
| 67 | + {{ user.name }} |
| 68 | + </each> |
| 69 | +</fetch> |
| 70 | +``` |
| 71 | + |
| 72 | +## Options |
| 73 | + |
| 74 | +You can configure the plugin with the following options. |
| 75 | + |
| 76 | +### `tags` |
| 77 | + |
| 78 | +Default: `['fetch', 'remote']` |
| 79 | + |
| 80 | +Array of supported tag names. |
| 81 | + |
| 82 | +Only tags from this array will be processed by the plugin. |
| 83 | + |
| 84 | +Example: |
| 85 | + |
| 86 | +```js |
| 87 | +const posthtml = require('posthtml') |
| 88 | +const pf = require('posthtml-fetch') |
| 89 | + |
| 90 | +posthtml() |
| 91 | + .use(pf({ |
| 92 | + tags: ['get'] |
| 93 | + })) |
| 94 | + .process('<get url="https://example.test">{{ response }}</get>') |
| 95 | + .then(result => console.log(result.html)) |
| 96 | +``` |
| 97 | + |
| 98 | +### `attribute` |
| 99 | + |
| 100 | +Default: `'url'` |
| 101 | + |
| 102 | +String representing attribute name containing the URL to fetch. |
| 103 | + |
| 104 | +Example: |
| 105 | + |
| 106 | +```js |
| 107 | +const posthtml = require('posthtml') |
| 108 | +const pf = require('posthtml-fetch') |
| 109 | + |
| 110 | +posthtml() |
| 111 | + .use(pf({ |
| 112 | + attribute: 'from' |
| 113 | + })) |
| 114 | + .process('<fetch from="https://example.test">{{ response }}</fetch>') |
| 115 | + .then(result => console.log(result.html)) |
| 116 | +``` |
| 117 | + |
| 118 | +### `got` |
| 119 | + |
| 120 | +The plugin uses [`got`](https://github.com/sindresorhus/got) to fetch data. You can pass options directly to it, inside the `got` object. |
| 121 | + |
| 122 | +Example: |
| 123 | + |
| 124 | +```js |
| 125 | +const posthtml = require('posthtml') |
| 126 | +const pf = require('posthtml-fetch') |
| 127 | + |
| 128 | +posthtml() |
| 129 | + .use(pf({ |
| 130 | + got: { |
| 131 | + // pass options to got... |
| 132 | + } |
| 133 | + })) |
| 134 | + .process('<fetch url="https://example.test">{{ response }}</fetch>') |
| 135 | + .then(result => console.log(result.html)) |
| 136 | +``` |
| 137 | + |
| 138 | + |
| 139 | + |
| 140 | +[npm]: https://www.npmjs.com/package/posthtml-fetch |
| 141 | +[npm-version-shield]: https://img.shields.io/npm/v/posthtml-fetch.svg |
| 142 | +[npm-stats]: http://npm-stat.com/charts.html?package=posthtml-fetch |
| 143 | +[npm-stats-shield]: https://img.shields.io/npm/dt/posthtml-fetch.svg |
| 144 | +[travis-ci]: https://travis-ci.org/posthtml/posthtml-fetch/ |
| 145 | +[travis-ci-shield]: https://img.shields.io/travis/posthtml/posthtml-fetch/master.svg |
| 146 | +[license]: ./LICENSE |
| 147 | +[license-shield]: https://img.shields.io/npm/l/posthtml-fetch.svg |
0 commit comments