Repository files navigation

Output ExpressionEngine data in JSON format.

• ExpressionEngine 2.6+

For older versions of EE use JSON version1.0.3.

• Copy the /system/expressionengine/third_party/json/ folder to your /system/expressionengine/third_party/ folder

Set xhr to yes to only output data when an XMLHttpRequest is detected. Do not set this to yes if you are using JSONP, as JSONP requests are not true XHMLHttpRequests.

Set terminate to yes to terminate the template and output your json immediately, with Content-Type headers.

Specify which fields you wish to have in the array. Separate multiple fields by a pipe character. If you do not specify fields, you will get all of the default fields' data. The primary key (entry_id for entries,member_id for members) will always be present and cannot be suppressed by this parameter.

Set a custom Content-Type header. The default is "application/json", or "application/javascript" if using JSONP. Headers are only sent when terminate is set to "yes".

Set jsonp to yes to enable a JSONP response. You must also specify a valid callback. You are encouraged to set terminate to yes when using JSONP.

Set a callback function for your JSONP request. Since query strings do not work out-of-the-box in EE, you may want to consider using a URL segment to specify your callback, ie. callback="{segment_3}", rather than the standard ?callback=foo method.

Use a different date format. Note: always returns dates as string.

By default, JSON will output a simple array of items. Use this parameter to make the response into a JSON object whose specified property is the array of items.

Using this parameter will turn this:

[  {    "title": "Foo",    "entry_id": 1  },  {    "title": "Bar",    "entry_id": 2  }]

Into this:

{  "items": [    {      "title": "Foo",      "entry_id": 1    },    {      "title": "Bar",      "entry_id": 2    }  ]}

By default, each item in the response array is a simple object. Using this parameter turns each item into a JSON object whose specified property is the item object.

Using this parameter will turn this:

[  {    "title": "Foo",    "entry_id": 1  },  {    "title": "Bar",    "entry_id": 2  },]

Into this:

[  {    "item": {      "title": "Foo",      "entry_id": 1    }  },  {    "item": {        "title": "Bar",        "entry_id": 2    }  }]

By default, the date fields are in unix timestamp format, accurate to milliseconds. Use the Javascript Date object in combination with date field data:

for (i in data) {  var entryDate = new Date(data[i].entry_date);}

If you require a different output format for the date fields, set the date_format= parameter. This uses the php date() function. common formats include "U" (unix timestamp in seconds), "c" (ISO 8601) or "Y-m-d H:i" (2011-12-24 19:06).

{exp:json:entries channel="news"}

json:entries is a single tag, not a tag pair. Use channel:entries parameters to filter your entries.

titleurl_titleentry_idchannel_idauthor_idstatusentry_dateedit_dateexpiration_datePlus all of the custom fields associated with that channel

Seechannel:entries parameters.

This will add categories to the entries response

When paired with show_categories="yes", this will display only categories from the specified groups.

Most custom fields will just return the raw column data from theexp_channel_data database table. The following fieldtypes will provide custom data. Youmust specify thechannel parameter to get custom fields.

The data will include an array of Matrix rows, including the row_id and the column names:

your_matrix_field: [  {    row_id: 1,    my_col_name: "foo",    other_col_name: "bar"  },  {    row_id: 2,    my_col_name: "baz",    other_col_name: "qux"  }]

The data will include an array of Grid rows, including the row_id and the column names:

your_grid_field: [  {    row_id: 1,    my_col_name: "foo",    other_col_name: "bar"  },  {    row_id: 2,    my_col_name: "baz",    other_col_name: "qux"  }]

The data will include an array of related entry IDs:

your_relationships_field: [1, 2]

The data will include an array of related entry IDs:

your_playa_field: [1, 2]

your_assets_field: [  {    "file_id": 1,    "url": "http://yoursite.com/uploads/flower.jpg",    "subfolder": "",    "filename": "flower",    "extension": "jpg",    "date_modified": 1389459034000,    "kind": "image",    "width": "300",    "height": "300",    "size": "65 KB",    "title": null,    "date": 1389459034000,    "alt_text": null,    "caption": null,    "author": null,    "desc": null,    "location": null,    "manipulations": {      "medium": "http://yoursite.com/uploads/_medium/flower.jpg",      "large": "http://yoursite.com/uploads/_large/flower.jpg"    }  },  {    "file_id": 2,    "url": "http://yoursite.com/uploads/dog.jpg",    "subfolder": "",    "filename": "dog",    "extension": "jpg",    "date_modified": 1389466147000,    "kind": "image",    "width": "300",    "height": "300",    "size": "75 KB",    "title": null,    "date": 1389466147000,    "alt_text": null,    "caption": null,    "author": null,    "desc": null,    "location": null,    "manipulations": {      "medium": "http://yoursite.com/uploads/_medium/dog.jpg",      "large": "http://yoursite.com/uploads/_large/dog.jpg"    }  }]

NOTE: image manipulation urls are only available to Assets files store locally, not on Amazon S3 or Google Storage.

your_channel_files_field: [  {    "file_id": 1,    "url": "http://yoursite.com/uploads/flower.jpg",    "filename": "flower.jpg",    "extension": "jpg",    "kind": "image\/jpeg",    "size": "65 KB",    "title": "flower",    "date": 1389459034000,    "author": 1,    "desc": "Lorem ipsum",    "primary": true,    "downloads": 10,    "custom1": null,    "custom2": null,    "custom3": null,    "custom4": null,    "custom5": null  },  {    "file_id": 2,    "url": "http://yoursite.com/uploads/dog.jpg",    "filename": "dog.jpg",    "extension": "jpg",    "kind": "image\/jpeg",    "size": "75 KB",    "title": "dog",    "date": 1389466147000,    "author": 1,    "desc": "Lorem ipsum",    "primary": false,    "downloads": 0,    "custom1": null,    "custom2": null,    "custom3": null,    "custom4": null,    "custom5": null  }]

The data will be the Unix timestamp, accurate to milliseconds. This is because the native JavaScript Date object accepts a millisecond-based timestamp in its constructor.

your_date_field: 1385661660000

{exp:json:search search_id="{segment_3}"}

json:search must be paired with {exp:search:simple_form} or {exp:search:advanced_form}.

Seechannel:entries parameters.

The native search forms will append a search_id automatically to the result_page when you submit a form.

{exp:search:simple_form channel="site" form_id="search" return_page="site/json"}    <input type="text" name="keywords">    <input type="submit" value="Submit">{/exp:search:simple_form}<script type="text/javascript">jQuery(document).ready(function($){  $("#search").submit(function(){    $.post(      $(this).attr("action"),      $(this).serialize(),      function(data) {        console.log(data);      },      "json"    );    return false;  });});</script>

{exp:json:members member_id="1|2"}

json:members is a single tag, not a tag pair.

Specify which members, by member_id, to output. Separate multiple member_id's with a pipe character. Usemember_id="CURRENT_USER" to get member data for just the current user.

Specify which members, by username, to output. Separate multiple usernames with a pipe character.

Specify which members, by group_id, to output. Separate multiple group_id's

Set a limit for records to retrieve.

If you're doing cross-domain AJAX, you will probably want to use JSONP.

This is the JSON template:

{exp:json:entries channel="site" jsonp="yes" callback="{segment_3}"}

And the request itself:

$.ajax({  url: "http://yoursite.com/group/template/yourCallbackFunction",  dataType: "jsonp",  jsonp: false});function yourCallbackFunction(data) {  console.log(data);}

You'll see here that we appended the callback function to the url as a segment, rather than use the traditional ?callback=function syntax. This is because query strings do not work out of the box with EE. If you have gotten query strings to work with EE you can use the traditional approach:

{exp:json:entries channel="site" jsonp="yes" callback="<?php echo $_GET['callback']; ?>"}

The request:

$.ajax({  url: "http://yoursite.com/group/template",  dataType: "jsonp",  jsonpCallback: "yourCallbackFunction"});function yourCallbackFunction(data) {  console.log(data);}

• Addedjson_plugin_entries_end andjson_plugin_members_end hooks
• Improved Wygwam support
• Fixed intermittent disappearingee()->TMPL object

• Addedoffset support for members

• Add Channel Files support.

• Addroot_node anditem_root_node parameters.

• Add manipulations to Assets fields

• Fix bug where show_categories parameter did not work

• Fix bug wherefields parameter was not being honored
• Fix bug causing fatal MySQL error when using thefixed_order parameter

• Fix WSOD on Plugins page
• Fix PHP errors when an Assests field has no selection(s)

• Added support for the following fieldtypes: Assets, Grid, Playa, Relationships
• Change IDs (entry_id, author_id, etc.) and Dates to integers
• Addedshow_categories andshow_category_group parameters to{exp:json:entries}
• Added{exp:json:search}
• Added JSONP support
• Addeddate_format parameter
• Addedcontent_type parameter

• IDs (entry_id, author_id, etc.) and Dates are returned as integers
• The following fieldtypes have different output: Playa, Assets. Please see docs above for an example of their output.