CD2H gitForager

hexojs/hexo-inject

Name: hexo-inject

Owner: Hexo

Description: Dynamic script & style (and more) injection for Hexo

Created: 2016-03-13 17:21:53.0

Updated: 2018-05-04 02:03:26.0

Pushed: 2017-09-07 19:16:28.0

Homepage:

Size: 31

Language: CoffeeScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

hexo-inject

Dynamic script & style (and more) injection for Hexo

Usage

This plugin is for plugin/theme developers to inject custom code into rendered HTML.

0. Overview

Injection is called once per complete HTML page (ones that have both <head> and <body> section).

There are 4 injection points:

CTYPE html>
l>
ead>
<!-- head_begin -->
<!-- ... -->
<!-- head_end -->
head>
ody>
<!-- body_begin -->
<!-- ... -->
<!-- body_end -->
body>
ml>

1. Install

Ask your user to run npm install --save hexo-inject.

Or add postinstall script to your plugin's package.json:


cripts": {
"postinstall": "npm install --save hexo-inject"

2. Register to `inject_ready` filter

hexo-inject will execute inject_ready filter to pool all installed plugins for injection configuration once hexo's after_init is fired.

In your plugin:

.extend.filter.register('inject_ready', (inject) => {
 Configure injections here
 Inject raw html at head_begin
ject.raw('head_begin', 'injected content')
 Or short hand
ject.headBegin.raw('injected content')

3. Simple injection helpers

hexo-inject provides a few helpers for simple HTML content injection:

tag (injectionPoint, name, attrs, content, endTag, opts)
script (injectionPoint, attrs, content, opts)
style (injectionPoint, attrs, content, opts)
link (injectionPoint, attrs, opts)

Examples:

ct.link('head_begin', { href: '/foo/bar.css', rel: 'stylesheet' })
ct.headBegin.script({}, 'var foo = 1;', { shouldInject: (src) => determinedBy(src) })

Notes:

injectionPoint is omitted if the helper is called from short-hand form (e.g inject.headBegin)
All values in attrs and content can be a string, a Promise that returns a string, or a function that returns a string or a Promise
opts.shouldInject can be a boolean value or a function that takes current page's HTML source and returns a boolean value. If shouldInject returns false, the content will not be injected to that page.

4. Inject files

hexo-inject also provides require (injectionPoint, module, opts) helper for file injection.

The workflow is:

File path is specified by module and is resolved relative to the callsite script's folder
Once resolved, the file will be renderer by hexo's renderer (determined by file's extension). The extension will be changed to output format's. (i.e. .swig -> .html)
The rendered content will be processed by loader (again, determined by file's extension) and the result will be injected
If opts.inline == false, hexo-inject will serve the file and reference it accordingly (i.e. via <script src="/path/to/served.js"></script>). Otherwise the content will be injected directly.

Valid opts fileds are:

inline - a boolean value
src - custom path for serving the file. Default to /injected/${module.fileName}${module.ext}
data - passed to renderer
shouldInject

Custom loader

hexo-inject provides loader for .js and .css by default. If you need to handle other formats, you should implement your own loader:

ct.loader.register('.foo', (content, opts) => {
turn opts.inline
? `<Foo src=${opts.src}></Foo>`
: `<Foo>${content}</Foo>`

Note that you might need to handle opts.inline accordingly and know that content will be an empty string if inline == false.

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.