This repository is intended to provide the Elm beginner and intermediate with a playground for exploring different parts of Elm in the context of a working application, and in a format that is suitable when time is limited e.g. at an Elm Coding Meetup.
- Start by forking this repository Github
- Clone your own fork of the repository
Forking the repository instead of just cloning it directly, will allow you to look at, and compare with solutions created by fellow Elm'ers when you push to Github. Simply go the the Network view of the main repository and select the forks/branches to compare.
Download and install the Elm compiler, elm-test, elm-format plus all needed Elm packages, locally in your working folder.
npm install
Just install the needed Elm packages.
elm-package install --yes
If you are completely new to Elm I suggest you spend a little time exploring the basic syntax and libraries.
Some good resources are:
- Interactive examples on elm-lang.org
- Exercises in functional programming with Elm on excercism.io
The Elm syntax reference is also good to have handy.
The application is a simple graph editor and viewer. You specify the graph in a textual format, the parsed graph specification is sent to an external JS library dagre, which calculates the layout given certain contstraints. The layout specifcation is passed back to the Elm part of the application where the graph is drawn using SVG.
To compile and run the application
npm run-script build
npm start
which just executes the following commands:
elm make --debug --output elm.js src/Main.elm
elm-reactor
Open the application http://localhost:8000/index.html, and poke around. Open the Elm Debug window and look at the Message flow.
This repository is structured in a way such that you can remove a slice of the application by doing
git checkout <slice branch>
If possible each slice comes in "small" and "medium" sizes. For a "small" slice the feature is partially implemented and needs to be completed. For a "medium" slice the part is completely stubbed out and needs to be added.
For both sizes the idea is for you to work your way back to the functionality that is in the master
branch. E.g. for slice-json-decode-small
, the Json decoder is partially in place but more fields needs to be decoded and added to the Model. The intention is not for you to match the code line-by-line with the code in master, just the functionality.
You can also go for a "large" slice, here you checkout the "medium" branch, but instead of working back towards the master
, you complete the feature using a completely different path, e.g. for the slice-view-svg-medium
, you build the graph visualization using Canvas or WebGL or something else.
The repository is currently prepared with branches for these slices:
- Json Encode
- relevant docs: Json.Encode
- branch:
slice-json-encode-small
- Encode some of the fields needed to pass to the
dagre
javascript library.
- Encode some of the fields needed to pass to the
- branch:
slice-json-encode-medium
- Convert the GraphData into Json to pass to the external layout engine.
- Json Decode
- relevant docs:
- branch:
slice-json-decode-small
- Decode a few missing fields
- branch:
slice-json-decode-medium
- Add Json decoding to the application, taking the raw Json string and turning it in to a GraphData value
- Javascript Interop/Ports
- relevant docs:
- branch:
slice-ports-small
- Send the graph layout data from
dagre
library into the Elm Elm application
- Send the graph layout data from
- branch:
slice-ports-medium
- tbd
- View - SVG
- relevant docs: Svg
- branch:
slice-view-svg-small
- Here the graph rendering only renders the nodes. Add support for drawing the edges.
- branch:
slice-view-svg-medium
- Look at the documentation Svg module to figure out how to render the graph data. Nodes are expected to be rectangular, and the GraphData contains information about size of image and nodes/edges.
- View - General tbd
- relevant docs:
- branch:
slice-view-small
- tbd
- branch:
slice-view-medium
- Use of bootstrap has been removed. Only basic Html is there. Make things look nice for graph editor, error messages and svg graph.
- Tests
- branch:
slice-tests-small
- Here you will find a single passing test. Try to add more tests for the GraphParser module.
- branch:
slice-tests-medium
- Here the project does not yet have any tests setup. Look at the documentation for elm-test for how to add tests to the project.
- branch:
- Parser tbd
- Tasks - debounce tbd
- Application structure tbd
- Elm tools installation platform specific instructions and Editor plugin links in the official guide
- The Elm syntax reference is also good to have handy.
- Javascript and Elm syntax side-by-side
Simply leave a comment on this Github Issue
- Application
- Add settings panel to adjust graph properties
- Improve parser error messages
- Header and github link
- Add more test (add html tests)
- Repository
- More slice branches
- Code documentation
- Write Slice intros (wiki?)
- Setup discuss/feedback github issues