Open and Annotate PDFs from Your Elm App

In this article, we’ll explore how to add advanced PDF features to your Elm app using PSPDFKit for Web. It builds upon our Open a PDF in Elm blog post, so be sure to check that out first.

To get started, we’ll need a free PSPDFKit for Web demo license. Follow the trial signup steps, and then make a note of your NPM_KEY and LICENSE_KEY, which we’ll need shortly.

ℹ️ Note: If you don’t want to follow along, you can see the finished code in our PSPDFKit for Web Elm example project, along with examples for several other popular languages and frameworks.

Setup

To set up our project, let’s first create the initial structure for our app:

1
2
3
4
mkdir pspdfkit-web-example-elm
cd pspdfkit-web-example-elm
mkdir src assets
touch src/index.js src/Main.elm

Then we’ll install our dependencies:

Copy
1
2
3
npm init -y
npm install -D elm elm-webpack-loader html-webpack-plugin webpack webpack-dev-server
npm install -D https://customers.pspdfkit.com/npm/YOUR_NPM_KEY_GOES_HERE/latest.tar.gz

Note that we’re using webpack to automate some of the grunt work, along with elm-webpack-loader to tell webpack how to handle Elm files. The webpack setup is not that relevant here, so we’ll skip over the details, but you can see the full webpack configuration in the finished example project.

First Iteration: Rendering

As in the previous article, our initial goal is simply to render a PDF in the browser. Here’s an example PDF to use if you don’t have one handy. Be sure to place it in the assets folder we created previously.

On the Elm side (in src/Main.elm), we’ll start simple and just create a div with an id of PSPDFKitContainer to contain our PSPDFKit instance:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
module Main exposing (init, main, update, view)

import Browser
import Html exposing (div)
import Html.Attributes exposing (id, style)



-- MODEL


init =
    {}



-- UPDATE


update msg model =
    model



-- VIEW


view model =
    div [ id "PSPDFKitContainer", style "height" "100vh" ] []



-- PROGRAM


main =
    Browser.sandbox { init = init, update = update, view = view }

On the JavaScript side (in src/index.js), we just need to tell PSPDFKit to render into the PSPDFKitContainer div created by Elm and pass in both the license key we obtained earlier and the path to our PDF document:

Copy
1
2
3
4
5
6
7
8
9
10
import { Elm } from "./Main";
import PSPDFKit from "pspdfkit";

Elm.Main.init({ node: document.body });

PSPDFKit.load({
  pdf: "example.pdf",
  container: "#PSPDFKitContainer",
  licenseKey: YOUR_LICENSE_KEY_GOES_HERE
});

With that, our PDF is now shown in the browser:

Second Iteration: Configuration

PSPDFKit for Web has a rich set of configuration options. In this second iteration, our aim is to specify these in Elm and pass them over to JS using Ports.

On the Elm side, we create a configure port which we can use to send our data to JS. We also define some data types that tell Elm the shape and format of our configuration object.

Finally, in the init function, we send the desired configuration to the configure port. Here we’re specifying that we want to jump straight to page 2 of the document and show thumbnails of the document pages in the sidebar.

ℹ️ Note: In a production app, rather than sidebarMode : String, you’d instead define a custom type (i.e. type SidebarMode = Thumbnails | Annotations | ...) and encode it before passing it to the port.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
port module Main exposing (..)

import Browser
import Html exposing (div)
import Html.Attributes exposing (id, style)



-- MODEL


type alias Model =
    { pdf : String
    , container : String
    , licenseKey : String
    , viewState : ViewState
    }


type alias ViewState =
    { currentPageIndex : Int
    , sidebarMode : String
    }


type alias Flags =
    { licenseKey : String }


init : Flags -> ( Model, Cmd Msg )
init flags =
    let
        model =
            { pdf = "example.pdf"
            , container = "#PSPDFKitContainer"
            , licenseKey = flags.licenseKey
            , annotations = []
            , viewState =
                { currentPageIndex = 1
                , sidebarMode = "THUMBNAILS"
                }
            }
    in
    ( model, configure model )



-- UPDATE


type Msg
    = Model


update msg model =
    ( model, load model )



-- PORT


port configure : Model -> Cmd msg



-- VIEW


view model =
    div [ id "PSPDFKitContainer", style "height" "100vh" ] []



-- PROGRAM


main =
    Browser.element
        { init = init
        , update = update
        , view = view
        , subscriptions = \_ -> Sub.none
        }

On the JS side, we subscribe to the configure port, which receives the configuration object and uses it to initialize PSPDFKit:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
const app = Elm.Main.init({
  node: document.body,
  flags: {
    licenseKey: YOUR_LICENSE_KEY_GOES_HERE
  }
});

app.ports.configure.subscribe(data => {
  const initialViewState = new PSPDFKit.ViewState(data.viewState);
  const config = { ...data, initialViewState };

  PSPDFKit.load(config);
});

Here’s how our second iteration looks in the browser:

Third Iteration: Interaction

For our third and final iteration, our aim is to be able to add annotations to the document using Elm.

To do this, we’ll add a button with an onClick handler that calls our update function. If it receives the CreateAnnotation message, our update function creates a new Annotation and updates our Model. Finally, it dispatches our updated model to a new annotate port:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
port module Main exposing (..)

import Browser
import Html exposing (Html, button, div, footer, text)
import Html.Attributes exposing (id, style)
import Html.Events exposing (onClick)



-- MODEL


type alias Model =
    { pdf : String
    , container : String
    , licenseKey : String
    , viewState : ViewState
    , annotations : List Annotation
    }


type alias ViewState =
    { currentPageIndex : Int
    , sidebarMode : String
    }


type alias Annotation =
    { pageIndex : Int
    , text : String
    , fontSize : Int
    , isBold : Bool
    , fontColor : String
    , backgroundColor : String
    , horizontalAlign : String
    , verticalAlign : String
    , boundingBox : Rect
    }


type alias Rect =
    { left : Int
    , top : Int
    , width : Int
    , height : Int
    }


type alias Flags =
    { licenseKey : String }


init : Flags -> ( Model, Cmd Msg )
init flags =
    let
        model =
            { pdf = "example.pdf"
            , container = "#PSPDFKitContainer"
            , licenseKey = flags.licenseKey
            , annotations = []
            , viewState =
                { currentPageIndex = 1
                , sidebarMode = "THUMBNAILS"
                }
            }
    in
    ( model, configure model )



-- UPDATE


type Msg
    = SetConfig
    | CreateAnnotation


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        SetConfig ->
            ( model, configure model )

        CreateAnnotation ->
            let
                annotation =
                    { pageIndex = 1
                    , text = "Hello from Elm 🌳"
                    , fontSize = 50
                    , isBold = True
                    , fontColor = "WHITE"
                    , backgroundColor = "GREEN"
                    , horizontalAlign = "center"
                    , verticalAlign = "center"
                    , boundingBox =
                        { left = 100
                        , top = 100
                        , width = 500
                        , height = 200
                        }
                    }
            in
            ( model, annotate { model | annotations = [ annotation ] } )



-- PORT


port configure : Model -> Cmd msg


port annotate : Model -> Cmd msg



-- VIEW


view model =
    div
        []
        [ div [ id "PSPDFKitContainer", style "height" "90vh" ] []
        , footer [ style "text-align" "center", style "line-height" "10vh" ]
            [ button [ onClick CreateAnnotation ] [ text "Create Annotation" ]
            ]
        ]



-- PROGRAM


main =
    Browser.element
        { init = init
        , update = update
        , view = view
        , subscriptions = \_ -> Sub.none
        }

The only significant change on the JS side is that we now need to subscribe to the annotate port to receive the updated model. There we simply loop through the annotations and coerce their attributes into the types that PSPDFKit is expecting:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { Elm } from "./Main";
import PSPDFKit from "pspdfkit";

let instance;

const app = Elm.Main.init({
  node: document.body,
  flags: {
    licenseKey: YOUR_LICENSE_KEY_GOES_HERE
  }
});

app.ports.configure.subscribe(data => {
  const initialViewState = new PSPDFKit.ViewState(data.viewState);
  const config = { ...data, initialViewState };

  PSPDFKit.load(config).then(async pspdfkit => {
    instance = pspdfkit;
  });
});

app.ports.annotate.subscribe(data => {
  data.annotations.forEach(a => {
    const annotation = new PSPDFKit.Annotations.TextAnnotation({
      ...a,
      fontColor: new PSPDFKit.Color(PSPDFKit.Color[a.fontColor]),
      backgroundColor: new PSPDFKit.Color(PSPDFKit.Color[a.backgroundColor]),
      boundingBox: new PSPDFKit.Geometry.Rect(a.boundingBox)
    });

    instance.createAnnotation(annotation);
  });
});

Here’s how our third iteration looks in the browser:

Conclusion

I hope this post has given you further insight into how JS interop works in Elm. These principles can be applied to working with any JavaScript library, and the basic pattern is the same: We define explicitly what and how data flows between Elm and the browser via ports, which gives us access to the things we need from JS while allowing us to keep the core of our application logic in Elm.

This might seem like a lot of overhead, but in many ways, it is not that different from talking to an API or delegating to some native code, and the beauty of the Elm language, architecture, and compiler really make it worth exploring.

PSPDFKit for Web

PDF viewing, annotating, and collaboration for web apps.

Try Now