Being fairly new to Elm, I’d like hear your approach to planning an Elm front end.
Let’s assume that we have at least a wire-frame or a mock-up of the application we want to implement.
Do you have any tips or best practices on how to plan your Elm application before jumping into code?
Do you draw some diagrams or flow charts or do you write down all the models, sub models, messages?
Would be grateful to hear of your experiences, especially for the inexperienced elm developer.
I grab a piece of paper and draw a state machine representing the possible states of the UI and possible ways the user can be allowed to move between them. The states consist of labels circled on the page, and the transitions as arrows between them. I definitely prefer this to be a pen and paper exercise and not done on a screen, simply because it is so much faster to do it that way.
I will typically iterate this 2 or 3 times before I get it right. As the sketches improve in quality I will also begin to flesh out the data model that each state needs, just writing field names and types next to each state. I will also add some more details to the transitions, name of the event and any associated data model and so on.
Once I have got that far, its a quick and fairly mechanical job to turn that into a Model, Msg and update function. Then I can start on building a view on top of that foundation.
At some point I would quite like to put a short talk on this together, and I did include it in an introductory talk on Elm that I gave. From that I have a sketch of a vending machine that I can share to illustrate this. Although this particular one was done on Inkscape, it is a direct copy of my first pen and paper sketch:
I use the elements of user experience as a guideline. I try to understand what are the data structures involved and what is the functionality that will be available. After that I move to site structure then to layout.
In the latest adaptation of this pattern I have a Data folder holding all the business objects, a Pages folder holding all the pages and a Ui folder holding all the user interface views. I usually have Api.elm, Route.elm, Ports.elm, Main.elm and a Common.elm that would hold a bunch of helpers. If the API is complex enough, it can become a folder with its own modules.
I usually don’t plan all the small details of an application up front. Certainly not listing all the messages and sub-models.
If I’m planning on the scope of a whole application, I’m thinking more at the product/design level. What problem is the application solving? What interactions does the app need to facilitate to solve those problems? What pages does the app need to create those interactions?
For the actual implementation details, I tend to take an iterative development approach. Elm’s compiler makes this particularly easy because it has my back when I make changes. Even big architectural things like “how are we going to structure pages?” and “how are we going to share layout code?” can start out dead simple and then evolve over time.
I do most of my planning is when I’m introducing types. This is where I do a lot of data modeling. I take time to understand what I’m modeling and try to make sure the type reflects that. In particular, I try to make impossible states impossible.
This can also be an iterative process. For example, I was working with our designer to build a filterable-dropdown input to choose a value from a giant list on the server. He’d built some mockups of the open and closed states. Based on some back and forth, we added a few more states. As I started implementing things in Elm, the type system started to push back against me and I realized we needed to handle loading, invalid, and network failure cases (yay type system! )
I went back to our designer and we discussed how to handle these states. After a few rounds of this, his mockup ended up kind of like @rupert’s state machine diagram:
)