1 # Introduction

     2 

     3 This module lets you programmatically subscribe to updates from a

     4 [pubsub][xep0060] node, even if the pubsub service is remote.

     5 

     6 ## Example

     7 

     8 ``` {.lua}

     9 module:depends("pubsub_subscription");

    10 module:add_item("pubsub-subscription", {

    11     service = "pubsub.example.com";

    12     node = "otter_facts";

    13 

    14     -- Callbacks:

    15     on_subscribed = function()

    16         module:log("info", "Otter facts incoming!");

    17     end;

    18 

    19     on_item = function(event)

    20         module:log("info", "Random Otter Fact: %s", event.payload:get_text());

    21     end;

    22 });

    23 ```

    24 

    25 ## Usage

    26 

    27 Ensure the module is loaded and add your subscription via the

    28 `:add_item` API. The item table MUST have `service` and `node` fields

    29 and SHOULD have one or more `on_<event>` callbacks.

    30 

    31 The JID of the pubsub service is given in `service` (could also be the

    32 JID of an user for advanced PEP usage) and the node is given in,

    33 unsurprisingly, the `node` field.

    34 

    35 The various `on_event` callback functions, if present, gets called when

    36 new events are received. The most interesting would be `on_item`, which

    37 receives incoming items. Available events are:

    38 

    39 `on_subscribed`

    40 :   The subscription was successful, events may follow.

    41 

    42 `on_unsubscribed`

    43 :   Subscription was removed successfully, this happens if the

    44     subscription is removed, which you would normally never do.

    45 

    46 `on_error`

    47 :   If there was an error subscribing to the pubsub service. Receives a

    48     table with `type`, `condition`, `text`, and `extra` fields as

    49     argument.

    50 

    51 `on_item`

    52 :   An item publication, the payload itself available in the `payload`

    53     field in the table provided as argument. The ID of the item can be

    54     found in `item.attr.id`.

    55 

    56 `on_retract`

    57 :   When an item gets retracted (removed by the publisher). The ID of

    58     the item can be found in `item.attr.id` of the table argument..

    59 

    60 `on_purge`

    61 :   All the items were removed by the publisher.

    62 

    63 `on_delete`

    64 :   The entire pubsub node was removed from the pubsub service. No

    65     subscription exists after this.

    66 

    67 ``` {.lua}

    68 event_payload = {

    69     -- Common prosody event entries:

    70     stanza = util.stanza;

    71     origin = util.session;

    72 

    73     -- PubSub service details

    74     service = "pubsub.example.com";

    75     node = "otter_facts";

    76 

    77     -- The pubsub event itself

    78     item = util.stanza; -- <item/>

    79     payload = util.stanza; -- actual payload, child of <item/>

    80 }

    81 ```

    82 

    83 # Compatibility

    84 

    85 Should work with Prosody \>= 0.11.x