Listicles
=========

.. contents:: :depth: 2

Both our drafts API and posts API support listicle creation.

Listicles are a set of particles grouped together inside a post. Their placement (where they will be rendered inside
the post body) can be determined by the use of a listicle HTML tag in the post body parameter as follows:

.. code-block:: html

   <listicle id="listicle-{post_id}"></listicle>

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                                                              |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``headline_html``      | String      || Headline as HTML - Optional                                                     |
|                        |             || If received, this field takes precedence over ``headline``                      |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``manual_basename``    | String      || Slug part - Optional                                                            |
|                        |             || If received, this field is used as slug part, otherwise, this is generated      |
|                        |             |  based on the value in the``headline`` field.                                    |
|                        |             |                                                                                  |
|                        |             || If it is not received and the ``headline`` field is also empty, the basename    |
|                        |             |  will be as follows:                                                             |
|                        |             |                                                                                  |
|                        |             |  .. code-block:: python                                                          |
|                        |             |                                                                                  |
|                        |             |     'particle-{id}'                                                              |
|                        |             |                                                                                  |
+------------------------+-------------+----------------------------------------------------------------------------------+
| ``media``              | String      | Media; usually a raw shortcode to be rendered above or below the 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 the Image API **response** when images are uploaded
     or edited.
   * Image shortcodes can be placed in the``media`` field and will be found in the "shortcode" field inside the
     payload **response** when uploading images with :doc:`images`.
   * Ask your account manager for further help 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 using the following structure:

.. code:: json

   {
     "headline": "This is an awesome post!",
     "body": "<p>foo</p><listicle></listicle><p>bar</p>",
     "listicle": {
        "items": [
          {
           "headline": "Listicle 1",
           "body": "Here is some content"
         }
       ],
       "settings": {
          "body_text_above": true
       }
     }
   }

Example with shortcode
**********************

.. code:: json
   :force:

   {
     "headline": "This is an awesome post!",
     "body": "<p>foo</p><listicle></listicle><p>bar</p>",
     "listicle": {
        "items": [
          {
           "headline": "Listicle 1",
           "media": "[rebelmouse-image <id> 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": <image_id>,
           "caption": "<p>Here is the caption</p>",
           "credit": "<p>Here is the credit</p>",
           "body": "Here is some content"
         }
       ],
       "settings": {
          "body_text_above": true
       }
     }
   }