Invoices in Elm, part 1
Tags: functional, elm
Published: 2019-01-14 15:29:55

---
title: Invoices in Elm, part 1
series: Elm invoice
published: true
description: An example illustrating the theory so far
tags: #functional, #elm
---

_This tutorial assumes some knowledge of html and some css. I will often refer to the theory from the [functional fundamentals series](https://dev.to/drbearhands/a-series-on-functional-fundamentals-48mb), so even if you've written some Elm programs you might find use in how this math can benefit you in practice._

_This tutorial is intentionally fast. I always loathed the long sessions behind a replicator, so I've decided to be rather brief here. If you find it's going a little fast for you, you might want to look at [Elm's official guide](https://guide.elm-lang.org/) as well._

_If you have any questions or criticism or if you find something unclear, feel free to comment away._

## Introduction
After so many posts about the theory of functional programming, it's about time I showed some actual code. Since career and freelancing advice seems to get a lot of attention on dev.to, I've decided to build an invoice generator.

We're going to be using Elm, you can [install it locally](https://guide.elm-lang.org/install.html) or follow along online on [Ellie](https://ellie-app.com/new). At the time of writing Elm is at version 0.19.

## Hello, world!

I will assume you've setup your Elm programming environment and can compile/run the following hello world example:

```elm
module Main exposing (main)

import Html exposing (Html)


main : Html a
main = Html.text "Hello, world!"
```

For those new to FP or Elm, let's go through it line-by-line.

```elm
module Main exposing (main)
```

declares that this file is a module called `Main` and that the value `main` is visible outside of this module.

```elm
import Html exposing (Html)
```
This is an import declaration. The `import Html` part means we are importing the module called Html. The `exposing (Html)` makes the type `Html` directly visible from our code, without needing to specify the module name. I.e. it lets us write `Html` rather than `Html.Html`.

```elm
main : Html a
main = Html.text "Hello, world!"
```

These two lines denote the *type* and *value*, of the *term* called `main`. The first line is called the *type declaration*, the second line is the *term declaration*. In a less math-oriented context, such as day to day programming, they are called *function signature* and *function body*, respectively.

The function body *must* exclusively result in a type that matches the function signature. If this is not the case, compilation will fail. This is the [Curry-Howard isomorphism](https://dev.to/drbearhands/functional-fundamentals-types-as-propositions-programs-as-proofs-56gh) at work, ensuring that our program *will* give the right type.

The type in question is `Html a`. Remember [functors](https://dev.to/drbearhands/functors-monads-and-better-functions-26f3#functors)? `Html` is one of them, it takes a type `a` and makes a `Html a`. In this case, the `a` is still not bound to any type. Meaning we could treat `Html a` as `Html String`, `Html Int`, etc. We will ignore this for now as we're not going to use the `a` part of `Html a`.

The value of main is `Html.text "Hello, world!"`. This means it is the result of the function `Html.text` applied to the value `"Hello, world!"`.

Let's check the [documentation of `Html.text`](https://package.elm-lang.org/packages/elm/html/latest/Html#text) and see if we're indeed going to get the right type. You wouldn't usually do this, the compiler does it for you, but we'll do it now for didactic purposes. 
The type of `Html.text` is `String -> Html msg`. I.e. it is a function that when given a value of type `String` will produce a value of type `Html msg`. In turn, this would make `main` have type `Html msg`. This might look like a type mismatch, but in Elm, lower-case type names mean "any type"<sup><a href="#sup1">1</a></sup>. So both `msg` and `a` have the same meaning (any type). In other words, the term `main` has the right type.

`main` is a special value in Elm: it is your program's main entry point. 
`main` can only have a restricted set of types, which includes `Htm a`. If we use a `Html` value, main will simply build a static website.

Remember that [functional programming has no variables, only values](https://dev.to/drbearhands/functional-fundamentals-what-is-functional-l66). We are, in fact, not assigning a value to `main`, we are defining what main *is*.


## Invoice base design

We're going to create an invoice template based on the Latex template [dapper invoice](https://github.com/mkropat/dapper-invoice) by Michael Kropat.

![dapper invoice example](https://camo.githubusercontent.com/9ede2f444a5e0bce5e134f3051b85bbce30e66c2/687474703a2f2f692e696d6775722e636f6d2f7137386a7447752e706e67)
We're ignoring the arrow because, while cool, it is a bit too complicated.

The structure is as follows:
* One row with headers, *two columns*:
  * company name
  * invoice number and date
* One row with *two columns*:
  * sender info, a *list or rows* with
     * *key and value pairs*
  * receiver info, a *list of rows* with
     * *key and value pairs*
* A row with a left-aligned column
* A row with a table
* A row with a right-aligned column


## The first header

Recall that [it's better to write the most composable functions](https://dev.to/drbearhands/functors-monads-and-better-functions-26f3#function-signatures). Therefore, we're going to make small simple functions and later compose them.

The Latex template doesn't really do this, that's not what Latex is for, and suffers from it. For instance, my country has different legal requirements and taxation laws than the US, which I assume is what this template is based on. Because the template expected fixed arguments, rather than, say, a list of key-value pairs, I'd have to create an entire new template.

But enough rambling.

Let's make the simplest function first: one that takes a number, and converts it to a string of the form "INVOICE #\<number\>".

```elm
invoiceNrText : Int -> String
invoiceNrText n = "INVOICE #" ++ String.fromInt n
```

`++` is an *operator*, it's pretty much the same as a function that takes two arguments, but you write it between arguments rather than in front of it. In fact, you can enclose it in parentheses to make it act like a regular function. I.e. `a ++ b` is the same as `(++) a b`.
Using the documentation for [String.fromInt](https://package.elm-lang.org/packages/elm/core/latest/String#fromInt) and [(++) operator](https://package.elm-lang.org/packages/elm/core/latest/Basics#++), you should at this point be able to figure out the meaning of these lines. Note that functions bind stronger than operators, so the line is equivalent to `"INVOICE #" ++ ( String.fromInt n )`

Let's add the `invoiceNrText` funtion to our module and change `main`'s term declaration:

```elm
main = Html.text ( invoiceNrText 7 )
```

Note that the parentheses are *not* used to represent function evaluation, as common in imperative paradigms. Rather they declare that we apply `7` to `invoiceNrText` and apply the result to `Html.text`. Had we written `Html.text invoiceNrText 7`, we would apply `invoiceNrText` to `Html.text` and subsequently apply 7 to the result.

So far so good, but we'd like to use html tags, not just plain text. Let's make a function that turns the string from `invoiceNrText` into an h1 html element, we use [Html.h1](https://package.elm-lang.org/packages/elm/html/latest/Html#h1):

```elm
invoiceNrHeader : String -> Html a
invoiceNrHeader str =
  Html.h1 [] [ Html.text str ]
```
The function signature of `Html.h1` is `List (Attribute msg) -> List (Html msg) -> Html msg`, meaning it takes a list of attributes `List (Attribute msg)`, and yields a function with type `List (Html msg) -> Html msg`<sup><a href="#sup2">2</a></sup>. So when we apply the empty list `[]` to `Html.h1`, we are left with a new function, to which to apply `[ Html.text str ]`, a list of html elements `List (Html msg)`, and we're left with a `Html msg`<sup><a href="#sup3">3</a></sup>.

Functions in Elm are *curried*. Rather than applying all arguments at once, we apply them one by one and return new functions as intermediate results.

We can now replace `Html.text` in the main function with `invoiceNrHeader`.

Now is as good a time as any for a throwback to function composition. We've seen the [`∘` operator in category theory](https://dev.to/drbearhands/functors-monads-and-better-functions-26f3#composition), used for arrow composition. In Elm that is `<<`. We can use this to write the main function's body as `main = ( invoiceNrHeader << invoiceNrText ) 7`. By doing so, we first create a new function, the composition of `invoiceNrHeader` after `invoiceNrText`, and then apply 7 to it. 

We can just do `invoiceNrHeader ( invoiceNrText 7 )`, so there's little point to function composition in this case, but there's situations in which it comes in handy so it's good to know ahead of time.

Ok, but we want to add some style to this. We can do that with the `Attribute.style` function.
For this we'll need to import a new module:

```elm
import Html.Attributes as Att
```

the `as Att` parts lets us write `Att` rather than `Html.Attributes`. I'm lazy and don't like writing full module names. Of course, we could also just expose all the functions we need.

Let's replace the empty list inside `invoiceNrHeader` with:
```elm
    [ Att.style "font-weight" "400"
    , Att.style "font-size" "2.5rem"
    , Att.style "letter-spacing" "7px"
    ]
```
(See documentation for [`style`](https://package.elm-lang.org/packages/elm/html/latest/Html-Attributes#style) functions).
Voila, your list of attributes.

Although you could use external css, I personally think it makes no sense for Elm, as inlining css makes it possible to unify structure and layout in reusable functions, much like webcomponents. I'm also going to abuse it for demonstrative purposes in just a moment.


The full code should now look like this:

```elm
module Main exposing (main)

import Html exposing (Html)
import Html.Attributes as Att


main : Html a
main = invoiceNrHeader ( invoiceNrText 7 )

invoiceNrText : Int -> String
invoiceNrText n = "INVOICE #" ++ String.fromInt n

invoiceNrHeader : String -> Html a
invoiceNrHeader str =
  Html.h1
    [ Att.style "font-weight" "400"
    , Att.style "font-size" "2.5rem"
    , Att.style "letter-spacing" "7px"
    ]
    [ Html.text str ]
```

## Adding the sub-header
If you've managed to follow along thus far, you've gained a good grip on the basics. I think it's about time to throw you into the deep end, of a lake filled with alligators.

I'll change our imports to:
```elm
import Html exposing (..)
import Html.Attributes exposing (..)
```
This exposes *all* the functions of `Html` and `Html.Attributes` modules. This is generally bad practice, as it makes it harder to see where names are coming from. In this case it is acceptable, because most programmers will recognize the exposed names, so repeated module names merely fill the screen with uninformative symbols.

I want to separate styling such as colors and font types from layout. In particular, parent elements should determine the layout/position of their children, but children should be responsible for their own styles. Doing this the *right* way would require building an entire new layout spec, and people have [done just that](https://package.elm-lang.org/packages/mdgriffith/elm-ui/latest/). But we're not doing things the right way, we're going to do them the <del>wrong</del> <ins>educative</ins> way.

So, I want a function that will allow me to define my element in one place, and add style to it somewhere else (its parent). Unfortunately, once you have an `Html a` value, there's not much you can do with it. Instead we're going to define a function `makeStylabe` that constructs a `List (Attribute a) -> Html a`, so that we can apply style to it later.

Take a moment to parse this type signature, as it is a good exercise, but don't feel obliged to fully understand it before reading on.

```elm
makeStylable : 
  ( List (Attribute a) -> List (Html a) -> Html a ) --tag
  -> List (Attribute a) --attributes
  -> List (Html a) --children
  -> List (Attribute a) --later attributes
  -> Html a
```

The body of makeStylable:

```elm
makeStylable tag attributes childElements laterAttributes =
    tag (laterAttributes ++ attributes) childElements
```

This function allows us to write e.g.:
```elm
makeStylable h1 [style "color" "red"] [text "foo"]
```
which would result in a `List (Attribute a) -> Html a` (remember partial application/currying). Exactly what we want.



Let's complete the right header. I'll represent the date as a String, as dates are a can of worms the opening of which is not relevant for the purpose of this tutorial.

```elm
dateHeader : String -> List (Attribute a) -> Html a
dateHeader str =
  makeStylable h5
    [ style "color" "DarkGrey"
    , style "font-weight" "400"
    , style "font-size" "1.25rem"
    ]
    [ text str ]

rightHeaderLayout : 
    ( List (Attribute a) -> Html a ) 
    -> ( List (Attribute a) -> Html a )
    -> List (Attribute a)
    -> Html a
rightHeaderLayout topHtml bottomHtml =
  makeStylable div
    [ style "area" "number-header"
    , style "text-align" "center"
    ]
    [ topHtml
        [ style "margin" "0"
        , style "padding" "0"
        ]
    , bottomHtml
        [ style "margin-top" "-10px"
        ]
    ]
```

After changing the main function to use our new html, the full code should look something like this:

```elm
module Main exposing (main)

import Html exposing (..)
import Html.Attributes exposing (..)

main : Html a
main = 
  rightHeaderLayout 
    ( invoiceNrHeader ( invoiceNrText 17 ) )
    ( dateHeader "1 April 2012" )
    []

invoiceNrText : Int -> String
invoiceNrText n = "INVOICE #" ++ String.fromInt n


makeStylable : 
  ( List (Attribute a) -> List (Html a) -> Html a ) --tag
  -> List (Attribute a) --attributes
  -> List (Html a) --children
  -> List (Attribute a) --later attributes
  -> Html a
makeStylable tag attributes childElements laterAttributes =
    tag (laterAttributes ++ attributes) childElements


invoiceNrHeader : String -> List (Attribute a) -> Html a
invoiceNrHeader str =
  makeStylable h1
    [ style "font-weight" "400"
    , style "font-size" "2.5rem"
    , style "letter-spacing" "7px"
    ]
    [ text str ]


dateHeader : String -> List (Attribute a) -> Html a
dateHeader str =
  makeStylable h5
    [ style "color" "DarkGrey"
    , style "font-weight" "400"
    , style "font-size" "1.25rem"
    ]
    [ text str ]

rightHeaderLayout : 
    ( List (Attribute a) -> Html a ) 
    -> ( List (Attribute a) -> Html a )
    -> List (Attribute a)
    -> Html a
rightHeaderLayout topHtml bottomHtml =
  makeStylable div
    [ style "area" "number-header"
    , style "text-align" "center"
    ]
    [ topHtml
        [ style "margin" "0"
        , style "padding" "0"
        ]
    , bottomHtml
        [ style "margin-top" "-10px"
        ]
    ]
```

Since this tutorial is already rather long, I'll break it off here for now. Although we've covered only very little of the invoice, we've covered most of the basic principles, which we will recycle in future parts.

## Footnotes
1. <a name="sup1"></a> There are some exceptions, such as `number`, which have specific meanings - `Int` or `Float` in the case of `number` - but they are rare and usually self-explanatory.
2. <a name="sup2"></a> `->` is right associative.
3. <a name="sup3"></a> This does not necessarily mean that a new function is allocated for every argument. I'm describing a conceptual situation which the compiler is free to implement and optimize in various ways.