Listicles
=========
Our drafts API and posts API support listicles creation, listicles are a set of particles inside a post
and you can control the place where they are going to be rendered inside the body by introducing a
listicle HTML tag in post body parameter, as follows:
.. code-block:: html
Parameters
**********
============= ================ ===========================================
Name Type Description
============= ================ ===========================================
``items`` Array of objects Items, particles of the listicle - Optional
``settings`` Object Settings - Optional
============= ================ ===========================================
Item Parameters
***************
+------------------------+-------------+----------------------------------------------------------------------------------+
| Name | Type | Description |
+========================+=============+==================================================================================+
| ``headline`` | String | Headline - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``manual_basename`` | String || Slug part - Optional |
| | || If received, this field is used as slug part, otherwise, we generate it based |
| | | on ``headline`` field. |
| | || If not received and ``headline`` is empty, the basename will take the following |
| | | form: |
| | | |
| | | .. code-block:: python |
| | | |
| | | 'particle-{id}' |
| | | |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``media`` | String | Media, usually a raw shortcode to be rendered above or below body - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``is_image`` | Boolean | For backward compatibility, it must be ``true`` if media is an image - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``image_id`` | Integer | ID of the uploaded image - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``caption`` | String | Caption - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``credit`` | String | Photo credit - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``manual_image_crops`` | Object | Crops calculated when uploading image - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``body`` | String | Body - Optional |
+------------------------+-------------+----------------------------------------------------------------------------------+
.. note::
* ``image_id`` can be found as ``id`` in Image API **response** when uploading or
editing images.
* It's possible to use image shortcodes in ``media`` field, you can find them in "shortcode" field inside the
payload **response** when uploading images with :doc:`/images`.
* Consider to ask your Account Manager for a help on configuring permalink settings if you want to start using
listicle slugs.
Setting Parameters
******************
+-------------------+-------+----------------------------------------------+
|Name |Type |Description |
+===================+=======+==============================================+
|``body_text_above``|Boolean|| Controls body position above or below media.|
| | || Optional. Defaults to ``false``. |
+-------------------+-------+----------------------------------------------+
|``layout_type`` |Integer|| Layout type. |
| | || Optional. Defaults to ``1``. |
| | || Choices: |
| | | |
| | | - ``1``: Regular listicle |
| | | - ``2``: Slideshow |
| | | - ``3``: Full screen |
+-------------------+-------+----------------------------------------------+
Example
*******
The parameters described above should be sent as part of the payload for creating/updating
drafts/posts, as the following:
.. code:: json
{
"headline": "This is an awesome post!",
"body": "
foo
bar
",
"listicle": {
"items": [
{
"headline": "Listicle 1",
"body": "Here is some content"
}
],
"settings": {
"body_text_above": true
}
}
}
Example with shortcode
**********************
.. code:: json
{
"headline": "This is an awesome post!",
"body": "foo
bar
",
"listicle": {
"items": [
{
"headline": "Listicle 1",
"media": "[rebelmouse-image is_animated_gif=false crop_info=\"%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%22thumbnails%22%3A%20%7B%22origin%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%2235x35%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F35x35.jpg%22%2C%20%221200x800%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x800.jpg%22%2C%20%22480x270%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F480x270.jpg%22%2C%20%22700x1245%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F700x1245.jpg%22%2C%20%22980x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F980x.jpg%22%2C%20%22600x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x.jpg%22%2C%20%22600x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x600.jpg%22%2C%20%22960x540%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F960x540.jpg%22%2C%20%22600x300%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x300.jpg%22%2C%20%22210x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F210x.jpg%22%2C%20%22300x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F300x.jpg%22%2C%20%22600x400%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x400.jpg%22%2C%20%221200x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x600.jpg%22%7D%2C%20%22manual_image_crops%22%3A%20%7B%2216x9%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20222%2C%20%22height%22%3A%20289%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22960x540%22%2C%20%22480x270%22%5D%7D%2C%20%222x1%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20255%2C%20%22height%22%3A%20256%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x600%22%2C%20%22600x300%22%5D%7D%2C%20%223x2%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20169%2C%20%22height%22%3A%20342%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x800%22%2C%20%22600x400%22%5D%7D%2C%20%221x1%22%3A%20%7B%22width%22%3A%20109%2C%20%22top%22%3A%20402%2C%20%22height%22%3A%20109%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22600x600%22%5D%7D%2C%20%229x16%22%3A%20%7B%22width%22%3A%20117%2C%20%22top%22%3A%20303%2C%20%22height%22%3A%20208%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22700x1245%22%5D%7D%7D%7D%22%0A\" original_size=\"512x511\" expand=1]",
"is_image": true,
"image_id": ,
"caption": "Here is the caption
",
"credit": "Here is the credit
",
"body": "Here is some content"
}
],
"settings": {
"body_text_above": true
}
}
}