# How to use

Use the `data-jsonp` attribute on `<pre>` elements, like so:

    <pre
      class="language-javascript"
      data-jsonp="https://api.github.com/repos/leaverou/prism/contents/prism.js">
    </pre>

Don't specifiy the `callback` query parameter in the URL; this will be added automatically. If the API expects a different callback parameter name however, use the `data-callback` parameter to specify the name:

    <pre class="…" data-jsonp="…" data-callback="cb"></pre>

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.

The following JSONP APIs are automatically detected and parsed:

- GitHub
- GitHub Gists
- Bitbucket

If you need to do your own parsing, you can hook your your own data adapters in two ways:

1. Supply the `data-adapter` parameter on the `<pre>` element. This must be the name of a globally defined function. The plugin will use only this adapter to parse the response.
2. Register your adapter function by calling `Prism.plugins.jsonphighlight.registerAdapter(function(rsp) { … })`. It will be added to the list of inbuilt adapters and used if no other registered adapater (e.g. GitHub/Bitbucket) can parse the response.

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 `null`. 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 `class` or `data-jsonp` attributes to assist in parsing the response).

The following example demonstrates both methods of using a custom adapter, to simply return the stringyfied JSONP response (i.e highlight the entire JSONP data):

    <!-- 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>

And later in your HTML:

    <!-- 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>

Finally, unlike like the File Highlight plugin, you do need to supply the appropriate `class` 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 `.xaml` extension for example, this plugin then needs to somehow map that to highlight as `markup`, which just means more bloat. You know what you're trying to highlight, just say so :)

## Caveat for Gists

There's a bit of a catch with gists, as they can actually contain multiple files. There are two options to handle this:

1. 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
2. If your file contains multiple files, the first one will be chosen by default. However, you can supply the filename in the `data-filename` attribute, and this file will be highlighted instead:

       <pre class="…" data-jsonp="…" data-filename="mydemo.js"></pre>

# Examples

The plugin’s JS code (from GitHub):

GitHub Gist (gist contains a single file, automatically selected):

GitHub Gist (gist contains a multiple files, file to load specified):

Bitbucket API:

Custom adapter (JSON.stringify showing GitHub status):

Registered adapter (as above, but without explicitly declaring the `data-adapter` attribute):