170 lines
6.9 KiB
HTML
170 lines
6.9 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
|
||
<meta charset="utf-8" />
|
||
<link rel="icon" href="assets/favicon.png" />
|
||
<title>JSONP Highlight ▲ Prism plugins</title>
|
||
<base href="../.." />
|
||
<link rel="stylesheet" href="assets/style.css" />
|
||
<link rel="stylesheet" href="themes/prism.css" data-noprefix />
|
||
<script src="assets/vendor/prefixfree.min.js"></script>
|
||
|
||
<script>var _gaq = [['_setAccount', 'UA-33746269-1'], ['_trackPageview']];</script>
|
||
<script src="https://www.google-analytics.com/ga.js" async></script>
|
||
</head>
|
||
<body>
|
||
|
||
<header data-plugin-header="jsonp-highlight"></header>
|
||
|
||
<section class="language-markup">
|
||
<h1>How to use</h1>
|
||
|
||
<p>Use the <code>data-jsonp</code> attribute on <code><pre></code> elements, like so:</p>
|
||
|
||
<pre><code><pre
|
||
class="language-javascript"
|
||
data-jsonp="https://api.github.com/repos/leaverou/prism/contents/prism.js">
|
||
</pre></code></pre>
|
||
|
||
<p>
|
||
Don't specify the <code>callback</code> query parameter in the URL; this will be added
|
||
automatically. If the API expects a different callback parameter name however, use the
|
||
<code>data-callback</code> parameter to specify the name:
|
||
</p>
|
||
|
||
<pre><code><pre class="…" data-jsonp="…" data-callback="cb"></pre></code></pre>
|
||
|
||
<p>
|
||
The next trick is of course actually extracting something from the JSONP response worth
|
||
highlighting, which means processing the response to extract the interesting data.
|
||
</p>
|
||
|
||
<p>The following JSONP APIs are automatically detected and parsed:</p>
|
||
|
||
<ul>
|
||
<li><a href="https://developer.github.com/v3/repos/contents/#get-contents">GitHub</a></li>
|
||
<li><a href="https://developer.github.com/v3/gists/#get-a-single-gist">GitHub Gists</a></li>
|
||
<li><a href="https://confluence.atlassian.com/display/BITBUCKET/src+Resources#srcResources-GETrawcontentofanindividualfile">Bitbucket</a></li>
|
||
</ul>
|
||
|
||
<p>If you need to do your own parsing, you can hook your your own data adapters in two ways:</p>
|
||
<ol>
|
||
<li>
|
||
Supply the <code>data-adapter</code> parameter on the <code><pre></code> element.
|
||
This must be the name of a globally defined function.
|
||
The plugin will use <em>only</em> this adapter to parse the response.
|
||
</li>
|
||
<li>
|
||
Register your adapter function by calling
|
||
<code class="language-javascript">Prism.plugins.jsonphighlight.registerAdapter(function(rsp) { … })</code>.
|
||
It will be added to the list of inbuilt adapters and used if no other registered
|
||
adapter (e.g. GitHub/Bitbucket) can parse the response.
|
||
</li>
|
||
</ol>
|
||
|
||
<p>
|
||
In either case, the function must accept at least a single parameter (the JSONP response) and
|
||
returns a string of the content to highlight. If your adapter cannot parse the response, you
|
||
must return <code class="language-javascript">null</code>. The DOM node that will contain the highlighted code will also
|
||
be passed in as the second argument, incase you need to use it to query any extra information
|
||
(maybe you wish to inspect the <code>class</code> or <code>data-jsonp</code> attributes to
|
||
assist in parsing the response).
|
||
</p>
|
||
|
||
<p>
|
||
The following example demonstrates both methods of using a custom adapter, to simply return
|
||
the stringified JSONP response (i.e highlight the entire JSONP data):
|
||
</p>
|
||
|
||
<pre><code><!-- perhaps this is in a .js file elsewhere -->
|
||
<script>
|
||
function dump_json(rsp) {
|
||
return "using dump_json: " + JSON.stringify(rsp,null,2);
|
||
}
|
||
</script>
|
||
|
||
<!-- … include prism.js … -->
|
||
<script>
|
||
Prism.plugins.jsonphighlight.registerAdapter(function(rsp) {
|
||
return "using registerAdapter: " + JSON.stringify(rsp,null,2);
|
||
})
|
||
</script>
|
||
</code></pre>
|
||
|
||
<p>And later in your HTML:</p>
|
||
|
||
<pre><code><!-- using the data-adapter attribute -->
|
||
<pre class="language-javascript" data-jsonp="…" data-adapter="dump_json"></pre>
|
||
|
||
<!-- using whatever data adapters are available -->
|
||
<pre class="language-javascript" data-jsonp="…"></pre>
|
||
</code></pre>
|
||
|
||
<p>
|
||
Finally, unlike like the <a href="/plugins/file-highlight/index.html">File Highlight</a>
|
||
plugin, you <em>do</em> need to supply the appropriate <code>class</code> with the language
|
||
to highlight. This could have been auto-detected, but since you're not actually linking to
|
||
a file it's not always possible (see below in the example using GitHub status).
|
||
Furthermore, if you're linking to files with a <code>.xaml</code> extension for example,
|
||
this plugin then needs to somehow map that to highlight as <code>markup</code>, which just
|
||
means more bloat. You know what you're trying to highlight, just say so :)
|
||
</p>
|
||
|
||
<h2>Caveat for Gists</h2>
|
||
|
||
<p>
|
||
There's a bit of a catch with gists, as they can actually contain multiple files.
|
||
There are two options to handle this:
|
||
</p>
|
||
|
||
<ol>
|
||
<li>
|
||
If your gist only contains one file, you don't need to to anything; the one and only
|
||
file will automatically be chosen and highlighted
|
||
</li>
|
||
<li>
|
||
If your file contains multiple files, the first one will be chosen by default.
|
||
However, you can supply the filename in the <code>data-filename</code> attribute, and
|
||
this file will be highlighted instead:
|
||
<pre><code><pre class="…" data-jsonp="…" data-filename="mydemo.js"></pre></code></pre>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
|
||
<section>
|
||
<h1>Examples</h1>
|
||
|
||
<p>The plugin’s JS code (from GitHub):</p>
|
||
<pre class="lang-javascript" data-jsonp="https://api.github.com/repos/PrismJS/prism/contents/plugins/jsonp-highlight/prism-jsonp-highlight.js"></pre>
|
||
|
||
<p>GitHub Gist (gist contains a single file, automatically selected):</p>
|
||
<pre class="lang-css" data-jsonp="https://api.github.com/gists/599a04c05a22f48a292d"></pre>
|
||
|
||
<p>GitHub Gist (gist contains a multiple files, file to load specified):</p>
|
||
<pre class="lang-markup" data-jsonp="https://api.github.com/gists/599a04c05a22f48a292d" data-filename="dabblet.html"></pre>
|
||
|
||
<p>Bitbucket API:</p>
|
||
<pre class="lang-css" data-jsonp="https://bitbucket.org/!api/1.0/repositories/nauzilus/stylish/src/master/whirlpool/style.css"></pre>
|
||
|
||
<p>Custom adapter (JSON.stringify showing the GitHub REST API for <a href="https://api.github.com/repos/PrismJS/prism">Prism's repository</a>):</p>
|
||
<pre class="lang-javascript" data-jsonp="https://api.github.com/repos/PrismJS/prism" data-adapter="dump_json"></pre>
|
||
|
||
<p>Registered adapter (as above, but without explicitly declaring the <code>data-adapter</code> attribute):</p>
|
||
<pre class="lang-javascript" data-jsonp="https://api.github.com/repos/PrismJS/prism"></pre>
|
||
</section>
|
||
|
||
<footer data-src="assets/templates/footer.html" data-type="text/html"></footer>
|
||
|
||
<script>function dump_json(x) { return "using dump_json: " + JSON.stringify(x,null,2); }</script>
|
||
<script src="prism.js"></script>
|
||
<script src="plugins/jsonp-highlight/prism-jsonp-highlight.js"></script>
|
||
<script>Prism.plugins.jsonphighlight.registerAdapter(function (x) { return "using registerAdapter: " + JSON.stringify(x,null,2); })</script>
|
||
<script src="assets/vendor/utopia.js"></script>
|
||
<script src="components.js"></script>
|
||
<script src="assets/code.js"></script>
|
||
|
||
|
||
</body>
|
||
</html>
|