Write documentation for the archive API. Also add another test.
update #306
This commit is contained in:
JC Brand
parent
dca0472e80
commit
69de033cea
|
|
@ -146,7 +146,7 @@ Developer API
|
|||
Earlier versions of Converse.js might have different API methods or none at all.
|
||||
|
||||
In the Converse.js API, you traverse towards a logical grouping, from
|
||||
which you can then call certain standardised accessors and mutators, like::
|
||||
which you can then call certain standardised accessors and mutators, such as::
|
||||
|
||||
.get
|
||||
.set
|
||||
|
|
@ -202,6 +202,139 @@ Example:
|
|||
roster_groups: true
|
||||
});
|
||||
|
||||
The "archive" grouping
|
||||
----------------------
|
||||
|
||||
Converse.js supports the *Message Archive Management*
|
||||
(`XEP-0313 <https://xmpp.org/extensions/xep-0313.html>`_) protocol,
|
||||
through which it is able to query an XMPP server for archived messages.
|
||||
|
||||
query
|
||||
~~~~~
|
||||
|
||||
The ``query`` method is used to query for archived messages.
|
||||
|
||||
It accepts the following optional parameters:
|
||||
|
||||
* **options** an object containing the query parameters. Valid query parameters
|
||||
are ``with``, ``start``, ``end``, ``first``, ``last``, ``after``, ``before``, ``index`` and ``count``.
|
||||
* **callback** is the callback method that will be called when all the messages
|
||||
have been received.
|
||||
* **errback** is the callback method to be called when an error is returned by
|
||||
the XMPP server, for example when it doesn't support message archiving.
|
||||
|
||||
Examples
|
||||
^^^^^^^^
|
||||
|
||||
**Requesting all archived messages**
|
||||
|
||||
The simplest query that can be made is to simply not pass in any parameters.
|
||||
Such a query will return all archived messages for the current user.
|
||||
|
||||
Generally, you'll however always want to pass in a callback method, to receive
|
||||
the returned messages.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
var errback = function (iq) {
|
||||
// The query was not successful, perhaps inform the user?
|
||||
// The IQ stanza returned by the XMPP server is passed in, so that you
|
||||
// may inspect it and determine what the problem was.
|
||||
}
|
||||
var callback = function (messages) {
|
||||
// Do something with the messages, like showing them in your webpage.
|
||||
}
|
||||
converse.archive.query(callback, errback))
|
||||
|
||||
|
||||
**Requesting all archived messages for a particular contact or room**
|
||||
|
||||
To query for messages sent between the current user and another user or room,
|
||||
the query options need to contain the the JID (Jabber ID) of the user or
|
||||
room under the ``with`` key.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
// For a particular user
|
||||
converse.archive.query({'with': 'john@doe.net'}, callback, errback);)
|
||||
|
||||
// For a particular room
|
||||
converse.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
|
||||
|
||||
|
||||
**Requesting all archived messages before or after a certain date**
|
||||
|
||||
The ``start`` and ``end`` parameters are used to query for messages
|
||||
within a certain timeframe. The passed in date values may either be ISO8601
|
||||
formatted date strings, or Javascript Date objects.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
var options = {
|
||||
'with': 'john@doe.net',
|
||||
'start': '2010-06-07T00:00:00Z',
|
||||
'end': '2010-07-07T13:23:54Z'
|
||||
};
|
||||
converse.archive.query(options, callback, errback);
|
||||
|
||||
|
||||
**Limiting the amount of messages returned**
|
||||
|
||||
The amount of returned messages may be limited with the ``max`` parameter.
|
||||
By default, the messages are returned from oldest to newest.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
// Return maximum 10 archived messages
|
||||
converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
|
||||
|
||||
|
||||
**Paging forwards through a set of archived messages**
|
||||
|
||||
When limiting the amount of messages returned per query, you might want to
|
||||
repeatedly make a further query to fetch the next batch of messages.
|
||||
|
||||
To simplify this usecase for you, the callback method receives not only an array
|
||||
with the returned archived messages, but also a special RSM (*Result Set
|
||||
Management*) object which contains the query parameters you passed in, as well
|
||||
as two utility methods ``next``, and ``previous``.
|
||||
|
||||
When you call one of these utility methods on the returned RSM object, and then
|
||||
pass the result into a new query, you'll receive the next or previous batch of
|
||||
archived messages.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
var callback = function (messages, rsm) {
|
||||
// Do something with the messages, like showing them in your webpage.
|
||||
// ...
|
||||
// You can now use the returned "rsm" object, to fetch the next batch of messages:
|
||||
converse.archive.query(rsm.next(), callback, errback))
|
||||
|
||||
}
|
||||
converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
|
||||
|
||||
**Paging backwards through a set of archived messages**
|
||||
|
||||
To page backwards through the archive, you need to know the UID of the message
|
||||
which you'd like to page backwards from and then pass that as value for the
|
||||
``before`` parameter. If you simply want to page backwards from the most recent
|
||||
message, pass in the ``before`` parameter with a value of ``null``.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
converse.archive.query({'before': null, 'max':5}, function (message, rsm) {
|
||||
// Do something with the messages, like showing them in your webpage.
|
||||
// ...
|
||||
// You can now use the returned "rsm" object, to fetch the previous batch of messages:
|
||||
rsm.previous(); // Call previous method, to update the object
|
||||
// parameters so that the previous batch of messages will be returned.
|
||||
rsm.count = 10; // Increase the page size (currently it's set to 1,
|
||||
// because that was what we specified in our last query.
|
||||
// Now we query again, to get the previous batch.
|
||||
converse.archive.query(rsm, callback, errback);
|
||||
}
|
||||
|
||||
|
||||
The "user" grouping
|
||||
-------------------
|
||||
|
|
|
|||
29
spec/mam.js
29
spec/mam.js
|
|
@ -227,6 +227,35 @@
|
|||
Date.prototype.getTimezoneOffset = getTimezoneOffset;
|
||||
});
|
||||
|
||||
it("accepts \"before\" with an empty string as value to reverse the order", function () {
|
||||
var sent_stanza, IQ_id;
|
||||
var sendIQ = converse.connection.sendIQ;
|
||||
spyOn(converse.connection, 'sendIQ').andCallFake(function (iq, callback, errback) {
|
||||
sent_stanza = iq;
|
||||
IQ_id = sendIQ.bind(this)(iq, callback, errback);
|
||||
});
|
||||
if (!converse.features.findWhere({'var': Strophe.NS.MAM})) {
|
||||
converse.features.create({'var': Strophe.NS.MAM});
|
||||
}
|
||||
converse_api.archive.query({'before': '', 'max':10});
|
||||
var queryid = $(sent_stanza.toString()).find('query').attr('queryid');
|
||||
expect(sent_stanza.toString()).toBe(
|
||||
"<iq type='set' xmlns='jabber:client' id='"+IQ_id+"'>"+
|
||||
"<query xmlns='urn:xmpp:mam:0' queryid='"+queryid+"'>"+
|
||||
"<x xmlns='jabber:x:data'>"+
|
||||
"<field var='FORM_TYPE'>"+
|
||||
"<value>urn:xmpp:mam:0</value>"+
|
||||
"</field>"+
|
||||
"</x>"+
|
||||
"<set xmlns='http://jabber.org/protocol/rsm'>"+
|
||||
"<max>10</max>"+
|
||||
"<before></before>"+
|
||||
"</set>"+
|
||||
"</query>"+
|
||||
"</iq>"
|
||||
);
|
||||
});
|
||||
|
||||
}, converse, mock, test_utils));
|
||||
|
||||
describe("The default preference", $.proxy(function (mock, test_utils) {
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user