Free-Form Purchase Options
==========================

By default each entry in a page's purchase list corresponds to a LaterPay Purchase Option specified via :doc:`../connector_admin_interface` or the :doc:`config_token` or a combination of both.

Free-Form Purchase Options allow you to add custom entries to the purchase list. An example application is a login link for existing customers which can be visually integrated into the purchase list using Free-Form Purchase Options.

Examples
--------

Add login link for existing customers to the top of the purchase list

.. tabs::

    .. group-tab:: JSON

        .. code-block:: html

            <script type="application/json" id="laterpay-connector">
                {
                    "freeFormPurchaseOptions": [
                        {
                            "title": "I'm a print subscriber",
                            "description": "Log in with your print subscriber account to get access to all articles",
                            "purchaseButtonLabel": "Login with your print subscriber account",
                            "purchaseUrl": "http://example.com/print_subscriber_login",
                            "position": 0,
                            "target": "_blank"
                        }
                    ]
                }
            </script>

    .. group-tab:: Video

        .. code-block:: javascript

            {
                connectorScript: {
                    freeFormPurchaseOptions: [
                        {
                            title: 'I\'m a print subscriber',
                            description: 'Log in with your print subscriber account to get access to all articles',
                            purchaseButtonLabel: 'Login with your print subscriber account',
                            purchaseUrl: 'http://example.com/print_subscriber_login',
                            position: 0,
                            target: '_blank'
                        }
                    ]
                }
            }

The example above adds a custom login link to the top of the purchase list. When the item is selected and the user clicks the Purchase Button, the specified URL will be opened in a new window/tab.


Object Properties
-----------------

:``freeFormPurchaseOptions``:

    An array of Free-Form Purchase Options. Each element is an object with a
    ``title``, a ``description``, a ``purchaseUrl`` and a ``purchaseButtonLabel``. Optional properties are ``price``, ``position`` and ``target``.

    :``title``:
        **Required**

        The Free-Form Purchase Option's title (displayed in the first row of the list entry).

    :``description``:
        **Required**

        The Free-Form Purchase Option's description (displayed in the second row of the list entry).

    :``purchaseUrl``:
        **Required**

        The Free-Form Purchase Option's URL. The user will be navigated to this URL when they click the Purchase Button.

    :``purchaseButtonLabel``:

        **Required**

        The Purchase Button label that will be displayed when the Free-Form Purchase Option is selected.

    :``price``:
        **Optional**

        An object stating the amount and currency. It is used for presentational purposes, only. To display a 1.23 EUR pricing, use this::

            "price": {
                "amount": 123,
                "currency": "EUR"
            }

        Note that you can use whatever currency you like here, because Free-Form Purchase Options don't correspond to actual LaterPay Purchase Options.

    :``position``:
        **Optional**

        An index starting with 0 for the top position. It indicates the Free-Form Purchase Option's position in the purchase list.

        The default position is the bottom of the purchase list.

    :``taget``:
        **Optional**

        A `link target <https://html.spec.whatwg.org/multipage/links.html#attr-hyperlink-target>`_ that is used when the Purchase Button is clicked (e.g. ``_blank`` for a new window).

        The default behavior is a redirect (equivalent to the target ``_self``).