Welcome to WebViewer Collaboration! This guide will walk you through getting WebViewer Collaboration integrated into an application. Before starting implementation, it is recommended to read the core concepts guide to get a grasp of how these modules work at a high level.
The source code for this guide is available here, but we recommend following along to learn some core concepts.
This guide will assume that you already have an application using WebViewer, and also assumes you have Docker installed on your machine. We will be using Docker to set up a database.
This guide is intended to show you the basics of WebViewer Collaboration. The code is not production grade!
In this guide we will be setting up a new database to store collaboration related data. If you already have a database with existing data, check out the integrating with an existing database guide.
WebViewer Collaboration comes with a Postgres database you can use to quickly get started collaborating.
Start by installing the database module by running
yarn add @pdftron/collab-db-postgresql.
Now that the module is installed, we can use the provided scripts to start the Docker container and install a local PostgreSQL database.
Navigate into the modules directory by running
We now have access to the pre-configured scripts provided by the module.
Start up the PostgreSQL database by running
name parameter is what we want our docker container to be called, and
password will be our databases master password (feel free to change these values). View all the available parameters here.
Now that our database is up and running, we need to create all the tables required for Collaboration to work. We also provide a script for this!
Run the following command to initialize and seed the database:
password parameter is the password we set in the previous step, and
dbName will be the name of the newly created database. View all the available parameters here.
After running this command, our database is ready to go!
The next step to implementing WebViewer Collaboration is setting up the server. Now that we have our database set up, this part is very easy.
First, install the server module by running
yarn add @pdftron/collab-server.
In order to use the server, we need to have the
COLLAB_KEY environment variable set. Read this guide for instructions on doing so.
If you do not already have a node server, you can create one by creating a
server.js in your project. If you do already have a node server, do the following steps inside your existing server.
Import both the server module and the database module:
Now we can configure the database module to connect to the database we created in the last step. Add this code to the top of your server file:
Now we're ready to initialize the server. Add the following code to your server:
db.getResolvers() function returns a set of default resolvers for the server to use. Resolvers are the functions that allow WebViewer Collaboration to read and write from your database.
That's it! When you start up your server, you should see a log like this:
Now that our server and database are up and running, we are ready to set up the client.
First, install the client module with
yarn add @pdftron/collab-client
If you do not have a WebViewer project already, you can create one by following the WebViewer get started guide. Once you have a project set up, come back to this guide!
Find the place in your codebase where you are initializing the WebViewer library - this is where we will also initialize the collaboration client.
The WebViewer initialization code will look something like this:
Import the Collaboration client and initialize it in the promise returned from WebViewer:
subscriptionUrl are the URLs of the server we set up in the previous step. In the screenshot above you will notice that these values are logged by the server when starting up. We also pass the WebViewer instance.
That's all we need to do to initialize the client!
The first step to using the client library is logging in a user.
For this example, we will be using anonymous users.
WebViewer Collaboration also supports SSO for logging in users from an existing system. For a complete authentication flow (signing users in with access tokens or username and passwords), see this guide.
To log in an anonymous user, we use the
client.loginAnonymously function and provide it a username to give to the user.
All login functions resolve with a
User, which will we use throughout the rest of the application.
Next, we need to create a Document for the user to Collaborate on.
We can use the
User.createDocument API to create a document.
We are going to write a function that creates a document for the current user, and call this function when some button is clicked in our UI.
In the code above, we are using a hard-coded URL for our document's location. In a real application, the user would probably upload a file or provide their own URL to the file. See creating documents for more info.
We also provide name for the document, and we also mark the document as public. See this guide for more details about public documents.
We then call the
Document.view() function, which loads the document in WebViewer.
my-button is clicked, a document will be created and loaded in the viewer.
In addition to creating documents, we may also want to get a list of a users documents to display somewhere in our UI. There are a couple ways to do this.
In this example we will skip the UI part and just use the list of documents to join and/or view them.
Getting a users documents
Add the following code to your app:
The code we just added grabs all the users documents, and loads the latest one in the viewer when the application loads. Here you could also loop over these documents and render them to your UI (see a React sample here).
In order for a user to annotate a document, they must become a member of that document. This can accomplished a couple ways, but in this example we will just use the
Only public documents can be self-joined
For this example we will set up our app so that all users automatically join all public documents when they sign in.
Let's add some code to get the latest public document, and join them it we haven't already:
The code we added uses the paginator class, which is used to fetch documents in an efficient way. You can read more about paginators here.
All this code is doing is fetching the latest public document, and joining it if we are able to. We could load and join more documents by increasing the
In a more complete app, you would typically render these public documents to your UI and allow the user to click a button to join the document.
Now, when the user loads the page, they will automatically join the last public document!
The last step of this guide is actually collaborating on a document!
Opening the app in your browser will create a new anonymous user. That user can then click the
my-button button to create a new public document. If you refresh the page, that new document will be automatically loaded!
In order to collaborate, we must have at least two users signed in. To accomplish this with our current set-up, we can open a new incognito window and go to our app. This will create a new anonymous user, and will also automatically join the document the first user created!
At this point you are able to draw annotations and see them sync in real time between users.
Now that you have all the modules implemented, we recommend learning more about the collaboration client.