Exhance

A jQuery plugin that takes a JSON or XML string and makes it colorful and easy to read.

Exhance is a portmanteau of the words 'exchange' and 'enhance', inspired by the fact that the plugin enhances the appearence of popular data exchange languages when presented on a website. Also, I think it sounds kinda cool.

Requirements

Exhance requires jQuery, at least version 1.4.2 but preferably newer, as well as the files jquery.exhance.js/jquery.exhance.min.js and jquery.exhance.css included on the website.

Exhance should work in browsers that are supported by jQuery. According to my tests it works without problems in IE7 and mostly fine (some CSS issues) in IE5.

Usage

The first thing you need is the data. It is recommended that you put it in a script tag, preferably in the document head, but it can be placed in any element anywhere in the document as long as the element has an ID and that the data is the only content of the element.

<script type="application/json" id="jsonExampleData">
{"object1" : {"innerObject" : {"string1" : "test","string2" : "moreTest","nothing" : null},"niceLinks" : ["http://google.com","http://en.wikipedia.org"],"thisIsTrue" : false},"anArray" : [42,23,15]}
</script>

Next you need a place to display the data, for example a div, but any block element should do just fine.

<div id="jsonExample1Display"></div>

Then the only thing remaining is calling Exhance. The src parameter is the ID of the element containing the data. If no source is given, Exhance will look for the data in the display element as given by the selector.

$('#jsonExample1Display').Exhance({
  src : 'jsonExampleData'
});

The result:

Other Possibilities

If you want the data presented in plain text, without the colorful HTML markup inserted, just formatted with newlines and tabs, it is easily accomplished.

$('#jsonExample2Display').Exhance({
  src : 'jsonExampleData',
  pre : true
});

The 'pre' (preformatted) parameter gives this result:

Or, if you want the user to be able to switch between the two...

$('#jsonExample3Display').Exhance({
  src : 'jsonExampleData',
  box : true
});

...the 'box' parameter is for you.

XML

While JSON is the default settings, Exhance handles XML just as well.

Please note that while in this example I have the XML in a script tag, it might be a better solution to store it in a separate file and load it with AJAX. Otherwise, depending on what kind of XML your data contains, it might interfere with the HTML.

<script type="application/xml" id="xmlExampleData">
<test1><element1><foo bar="true" mode="test">Welcome to Exhance.</foo></element1><element2>bye</element2><description>XML test data</description></test1><test2>http://jquery.com</test2>
</script>

and

$('#xmlExample1Display').Exhance({
  src : 'xmlExampleData',
  type : 'xml',
  box : true
});

yields:

More Examples

Here are a couple of examples that uses larger sets of data which is retrieved using AJAX.


Configuration

Parameters

Name Description
ajax Type: boolean
Default: false

If the data should be retrieved using AJAX. If this parameter is set to true, then 'src' should be the relative path to the file containing the data.
box Type: boolean
Default: false

Places the data in a styled box and offers controls that enables the user to switch between colored and plain preformatted text.
boxBlock Type: boolean
Default: false

If true, the box created by the 'box' parameter is displayed as a block (as opposed to inline-block) and streches 100% of the width of the parent element.
boxMenu Type: boolean
Default: true

If false, the menu in the box created by the 'box' parameter will be hidden.
indent Type: integer
Default: 30

The number of pixels for each indentation.
hover Type: boolean
Default: false

The different parts of the JSON/XML data changes background on hover.
links Type: boolean
Default: true

If links found in the data should be padded with <a>-elements.
placeholder Type: string
Default: "%exhance%"

The placeholder used in the 'wrapper' parameter.
pre Type: boolean
Default: false

If the 'box' parameter is false, 'pre' will print the data without any formatting except newlines and tabs.
If the 'box' parameter is true, the plain text option in the menu will be default.
src Type: string/boolean
Default: false

The ID of the element containing the data or, if 'ajax' is set to true, the relative path to the file containing the data.
If false, Exhance will look for the data in the element given by the selector, which is also the element in which the data should be displayed.
type Type: string
Default: "json"

The language of the data. 'json' and 'xml' supported.
wrapper Type: string
Default: "%exhance%"
Example: "someFunction(%exhance%);"

Only available for JSON.
If the data should be wrapped in text, for example a function call.
write Type: boolean
Default: true

If false, the selected element(s) will not have their contents altered, only the element's data attributes will be changed.
xmlComments Type: boolean
Default: true

If comments should be printed when displaying XML.

Data

Exhance saves some data on the elements, this is retrieved with $(element).data().nameOfKey.

Key Description
exhancePre The data as plain text, formatted with newlines and tabs.
If the language is XML, < and > is encoded as &lt; and &gt;.
exhanceXml Only set for XML.
Same as exhancePre but with < and > unencoded.
exhanceObj The data represented as a JavaScript object or a DOM object for JSON and XML respectively.

Miscellaneous

If you have already used Exhance on an element and want to recreate it, you don't need to specify the source (unless you want to change it), Exhance will use the exhancePre/exhanceXml variables it set the first time.

You can use the shortcut $(element).Exhance('pre') to recreate an element to contain only preformatted plain text. Although $(element).Exhance({pre:true}) works just as fine.

Similarly, $(element).Exhance('hover') and $(element).Exhance('disableHover') are shortcuts to enable and disable the hover effect and $(element).Exhance('data') returns the contents of the data attributes exhancePre/exhanceXml for JSON and XML respectively.

$(element).Exhance() will always return $(element) in order to allow for chaining.


License and Copyright

Exhance is licensed under the MIT License.

Copyright (c) 2014 Tomas Thelander


Download

Exhance is available on the jQuery Plugin Registry and on GitHub.