Better documetnation needed for paginateEventTimeline

[selankon]

Hi,

I need help to use the paginateEventTimeline method. I don't find documentation anywhere.

From a room of type sdk.Room i'm trying to get paginated events:

await this.client.paginateEventTimeline(room.getLiveTimeline(),{})

But this fail with error:

Error: EventTimelineSet.addEventsToTimeline cannot be used for adding events to the live timeline - use Room.addLiveEvents instead at EventTimelineSet.addEventsToTimeline

Can anyone give me instructions of how to get paginated room events?

Thanks in adavance!

[selankon]

Ok, I found that I MUST to define the opts {backwards: true, limit: 10} to work properly.

But this don't give me a paginated list, this instead do same as await this.client.scrollback(room);.

What I would like to do is to retrieve a paginated list of events, like from 0 to 10th, from 10th to 20th etc.. The only way to achieve this with the sdk is to add events to the timeline?

Thanks in advance

[AbdullahQureshi1080]

@selankon I had some issues with pagination myself, so I used the scrollback helper to get previous messages and then updated the UI state myself. Let me know if that help.

const client = await this.getClient();
const room = await this.getRoomById(roomId);
const scrollback = await client.scrollback(room, 5); // this could be any number of events that you want, I tried with max 30 and it works fine, but since my need was 5 messages so this helped me. 

[selankon]

Hi, thanks for your answer. This is how finally I resolve the problem but it don't paginate, just add events to the live event timeline. I adapted my program to this behaviour

[AbdullahQureshi1080]

@selankon It's not ideal but It let's us emulate the same behavior as pagination, that otherwise can be handled by sdk itself but due to lack of support and documentation it makes it very difficult to achieve the small niches.

[skylord123]

There are no examples of how to do this correctly and a lot of bad information out there so I figured it out and wanted to share for others.

To paginate I highly recommend using the TimelineWindow class. That is the whole purpose of this class. You have to initialize it yourself.

const {TimelineWindow} = require("matrix-js-sdk");
let room = matrixClient.getRoom(roomId);
if(!room) {
    console.log(`Room ${roomId} does not exist`);
    return;
}
let timelineWindow = new TimelineWindow(matrixClient, room.getUnfilteredTimelineSet());
let eventId = null; // we can fetch events around a specified event or set to null to go from end of timeline
let initialWindowSize = 20; // number of events to grab for initial load
await timelineWindow.load(eventId, initialWindowSize); // load the initial events (required step)

// now we can grab the events
let events = timelineWindow.getEvents();

// now lets move the window backwards
// moreMessages will be false if there are no more events in this direction
let backwards = true;
let moreMessages = await timelineWindow.paginate(backwards ? 'b' : 'f', 8);

if(moreMessages)
{
    // there are more messages, lets remove the previous page's events
    await timelineWindow.unpaginate(8, !backwards);

    // now we can grab the next page of events
    events = timelineWindow.getEvents();
}

Since this uses the default unfiltered timeline it will have the initial sync limit from MatrixClient's initialSyncLimit option so if you want a larger page size you must increase this as well or build an unfiltered timeline yourself.

await node.matrixClient.startClient({
    initialSyncLimit: 20 // default is 8
});

I was trying a page size of 20 but my initialSyncLimit was set to the default 8 preventing me from getting more than 8 events (and also broke my pagination by skipping records)

[richvdh]

[contributions to documentation improvements are very welcome!]

[theobouwman]

@skylord123 thank you very much! Great example.

[theobouwman]

@skylord123 how can we work with the TimelineWindow so that new events automatically refresh the window?

[skylord123]

@skylord123 how can we work with the TimelineWindow so that new events automatically refresh the window?

@theobouwman New matrix events emit an event on the matrix client when they come in. You listen for this event to handle incoming matrix events.

My package node-red-contrib-matrix-chat for Node-RED uses this so you can check it out for reference:
https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/blob/master/src/matrix-server-config.js#L195-L256

As far as I am aware the event timeline is only used to paginate events that have already occurred (so more for paginating past events). I may be wrong about that though. I would definitely contribute to the docs if I was more sure about my findings. For now though if anyone needs an example of how to paginate I created a node to do exactly this for my module so that code can be used as a reference:
https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/blob/master/src/matrix-paginate-room.js