ceddlyburge / elm-league-tables-from-google-sheets

A website to show league tables and fixtures, from results stored in Google Sheets

I am a software developer passionate about social and environmental justice. I mostly program in Elm, C#, Python, Typescript and Delphi. I mentor on Exercism, for Code First Girls and You Make It, and maintain the Elm track on Exercism.

I find that books can be an excellent way to learn ideas and concepts, and I wish I had discovered the good ones earlier in my career. It's easier to discover them now that we have virtual communities on the internet, and ratings websites and similar. You can read my book recommendations, and see a full list of books I have read / reviewed on goodreads.

I also find that writing is an excellent way to make sure I have understood something, and to spread knowledge. We should format code on demand, Cost effective Coding Guidelines, Embedding Domain Concepts in Code and Writing Describable Code are hopefully interesting reads, and are applicable to all programming languages. The full list is on LinkedIn.

I have created a few frameworks, CustomerTestsExcel, DocsFromTests and Configuration. I play canoe polo in my spare time, and have a couple of related hobby projects, a website to show league tables based on a google spreadsheet, and one to help orgranise tournaments.

elm-league-tables-from-google-sheets's Issues

Improve display of goal scorers in results fixtures

At the moment, if a player scores 2 or more goals in a game, their name is repeated in the results / fixtures page.

It would be better if the name was just displayed once, and the number of goals (if there are multiple) scored displayed in brackets afterwards.

For example "Cedd Burge, Cedd Burge" would become "Cedd Burge (2)"

A further enhancement would be to allow the time when the goal was scored to be entered in to the google spreadsheet, and then the results fixtures could show this if it was available.

For example "Cedd Burge, Cedd Burge" would become "Cedd Burge (12, 15)", as long as the time of the goal was entered in the spreadsheet.

Add logging of problems

Some sort of logging would be useful, probably behind a serverless function.

For example the api key of the deployment, or the id of the spreadsheet could be wrong. Possibly the api key could expire, or run out of credit. Possibly the spreadsheet could change permissions so that it wasn't accessible from the web, and so on.

Potentially things like this could be emailed to the league organiser (the deployment would have to be given the email for this person)

Maybe use papertrail

Architecture diagrams

It would be good to add some high level architecture diagrams, to aid development. Probably using mermaid.

To include

• Concept (Editing google sheets is easy and familiar for most people, so entering fixtures and results is easy, and from this you can get a fully fledged league table type website for teams and players)
• Types of users (Owner / Administrator, League Editor, League Viewer)
• Inputs (environment variables and google sheet)
• High level code flow
• Maybe high level code structures (although the Model basically describes most of these, so might not be required)

From simon brown's 4s model:

system context diagram

• scope?
• who is using it
• what are they doing
• how do they do it

container diagram

• high level tech blocks
• what are their responsibilities
• how do they communicate

Cache results from the Google Sheets Api

This will make the app more robust when the network is patchy / slow, but introduces ui and code complications.

Saving the api results to local storage is quick and easy.

Restoring them on app startup and supplying them via ports is also quick and easy.

The ui changes to provide a good user experience are harder though. When results already exist, a temporary, probably animated, message would be useful to let the user know whether a refresh has succeeded or failed. This means that they will know if the data is stale and can choose to refresh again. If there is no existing data, then the message should be permanent, as there is nothing else to display.

The code currently caches the api result once it is loaded, so a mechanism to refresh the cache ocassionally would be useful.

Rough plan as follows (just for League List page)

AnimationTimer
 state : Inactive, SuccessfulFetch, FailedFetch
 percentageElapsed : Int

Add leagueListAnimation : AnimationTimer to model.

The logic is as follows

If Just leagueSummaries then
Show loading message if loading (push leagues down below loading message, possibly animate)
Show success message for 5 seconds if AfterSuccessfulFetchAndExistingData
Show failure message for 5 seconds if AfterFailedFetch
Show the leagues
else
Show loading message if loading
Show failure message if failed fetch
Show code bug if not asked

Probably want to remove any animations when changing page as well. A navigate away and a navigate back might cause this.

Tests

Update (it now has an additional responsibility to set the AfterFetchAnimationTimer)

• WhenFetchFailsAnimationTimerIsFailedFetch
• WhenFetchSucceedsAnimationTimerIsSuccessfulFetch
• WhenTimerTicksAnimationProgresses

View

• ShowLoadingsMessage if loading and no existing data
• ShowFailureMessage if failed and no existing data
• ShowBug if notasked and no existing data
• ShowLoadingsMessage if loading and some existing data (maybe animate)
• ShowSuccessAnimation if Animation is SuccessfulFetch
• ShowFailureAnimation if Animation is FailedFetch

End to end
I don't think it will be possible to set up local storage, which will make things difficult
Can have one without a http request so can check the view when there is no pre existing data
See if I can pass somthing to init

Failure response from the api are cached, and then are not retried

The failure from a http request is cached in the model, so when navigating to top scorers, results / fixtures or league tables you might immediately get the failure screen. It should try another http request at this point.

The problem is that we just check if there is an item in the dictionary, but we don't check if the relevant entry contains a success or a failure response.

This happens for the top scorers, results / fixtures and the league table, and is controlled by leagues : Dict String (WebData League) in the model.

Run cypress tests against built website

The cypress tests on the build server, and indeed locallyl, currently run against the webpack development server.

This means that errors could creep in from differences between the webpack dev server / build and the full build.

So it would be better to npm run build to create the same code that will get deployed, use serve (or similar) to serve it and then test against that, which would remove this possibility.

Add a team page

At the moment there is no page to show the details for an individual team.

It would be good to have such a page, which should probably show the following:

• position in the league
• upcoming fixtures
• past results
• top scorers
• worst offenders (when this feature is implemented)

Maybe check formatting with a github action

This GitHub action does it, and it looks quite easy, so probably worth doing

https://github.com/sparksp/elm-format-action

Add top / leading scorers page

The scorers for each game are now parsed from the google sheet and stored in the model, so it shouldn't be too hard to create a new page to show the leading scorers for a league

Convert to elm 0.19

elm-spec doesn't work in elm 0.19, so I will need to rewrite the end to end tests in something else. Probably cypress.io.

Call Google Api in an AWS Lambda

This will allow some more control over calls to the Api, such as caching and rate limiting and suchlike. There will only be one lamda for a deployment, so it will be able to do this, whereas there may be many users running the front end app at one time, so they are only able to cache / rate limit / etc their own use.

Netflify has good support for serverless functions so hopefully it will be quite doable

https://www.netlify.com/products/functions/
https://www.netlify.com/products/dev/
https://css-tricks.com/netlify-functions-for-sending-emails/
https://functions.netlify.com/examples/
https://www.netlify.com/blog/2019/04/24/zero-config-yet-technology-agnostic-how-netlify-dev-detectors-work/

Administrator Page

The application is written in elm, and atomically deployed by netlify only after passing all of the tests, so it is relatively hard to crash it.

However it talks to the Google Sheets Api, and there can definitely be problems with the connection to the api, and with the data in the sheet.

It would be good to create a page to look for nd display such problems, and to suggest solutions. League administrators / editors can then look at this page and make any changes necessary.

There should probably be an overall section (with global problems such as connection to the api), and then a section for each league (with problems specific to a particualr league).

Global section problems

• There could be a problem with the Google Api key, such as it hitting a rate limit, being set up wrongly, or being disabled
• The spreadsheet might not be published to the web, which stops it being accessible to the api.

League specific problems

• The dates in the "Date Played" column might not be formatted as dates, and not converted by the elm code.
• A team name might be spelt / misspelt in different ways, which the code will interpret as two separate teams
• A player name might be spelt / misspelt in different ways, which the code will interpret as two separate players
• A comma might be missing in the "Home Scorers" or "Away Scorers" sections, which would result in the player name being wrong.

Run google lighthouse during CI

I think the website isn't that good for accessibility at the moment so need to improve that, and looking in to progressive web app and seo metrics would also be enlightening.

This might be the way to do it
https://www.freecodecamp.org/news/how-to-use-lighthouse-in-github-actions/

Add notes to results / fixtures

It would be good to show any notes for a game in the results / fixtures page, in a similar way to which goal scorers are currently shown. Being as the notes are per game (as opposed to per team), they would probably be center aligned, rather than going on the right or the left.

Split model, msg and cmd per page

As in this article

https://jezenthomas.com/how-i-write-elm-applications/?utm_campaign=Elm%20Weekly&utm_medium=email&utm_source=Revue%20newsletter

This isn't really necessary for an app of this size, but it is just about worth it, and I think it is the best way of structuring large apps, so it would be good to get a feel for it

Add worst offenders page

In much the same way as #28, it would be good to show a list of the players with the most penalty cards.

This should happen after #38, which will invovle parsing the card details from the api response and updating the model with new types to represent the cards.

Different sports have different meaning for their cards, and different colours, so the code can't really know the relative importance of each, so instead it should use a heuristic. The cards that appear most rarely in the spreadsheet will be assumed to be the worst, and be given higher rankings tha those that appear more commonly.

The players will be ordered according to this ranking primarily, and then by player name and team name.

The cards should be displayed using their icons as in #38, along with the number of them that the player received.

Ca

Restore html tests

The html tests were removed during the upgrade to elm 0.19, and ideally should be restored.

The problem is that the elm package (eeue56/elm-html-test) I was using doesn't seem to exist in elm 0.19, and there don't seem to be any alternatives.

The following files were removed

• ResultsFixturesViewForPlayedGameTest.elm.not
• ResultsFixturesViewForUnPlayedGameTest.elm.not
• ResultsFixturesViewForUnplayedGameWithNoDateTest.elm.not
• ResultsFixturesViewHelpers.elm.not
• LeagueListViewTest.elm.not
• LeagueTableViewTest.elm.not

Improve accessibility

This blog post / elm package makes the simple things super easy, and will throw compile errors if you are violating the guidelines, and its an almost drop in replacement for Html, so should be easy to do.

https://dev.to/nimmo/easier-paths-to-accessibility-in-elm-4ojo?utm_campaign=Elm%20Weekly&utm_medium=email&utm_source=Revue%20newsletter

Show scorers in the results / fixtures page

At the moment only the score is shown for the played games / results

It would be good to also show the names of the players that scored them. This data could then also be used to create a top scorers page.

Show cards in the results / fixtures page

It would be good to show the penalty cards that people recieved during games in the results / fixtures page, in much the same was as #27.

Cards should be entered in to the spreadsheet in "Player name: description" format. For example "Cedd Burge: Yellow". Multiple cards should be separated by commas.

Allow each deployment to have its own icon

At the moment there can be many deployments of this app, but they must all share the same icon.

It would be better if each deployment could have its own icon. A polo ball for polo leagues, a cricket bat for cricket leagues, etc.

Currently the icon is shown as the favicon in the brwoser bar, and as the application logo when adding it to the home screen of a mobile phone app.

favicon.ico is currently used for both purposes, which might be problematic (they have quite different size needs).

I think the plan would probably be to replace this file during the netlify build, by downloading another one from a url specified using an environment variable (which would be set up on netlify)

It is probably best to have a bash script to do this, so that it is easy to run it locally and see what is happening

Show historical results

At the moment the leagues have a single level of nesting, which is assumed to be the various divisions for a year (division 1, division 2 etc).

A lot of teams will persist between years, so it would be nice to be able to show some historical stats from previous years.

I'm not sure how this would work yet, but I'm not sure putting everything in the same google sheet is a good idea, as it could get unmanageable, and probably a lot of people will end up with permissions and nobody will have overall ownership and things like that. Although maybe it could work.

So maybe some environment variables with google sheet ids for previous years. Or maybe this information goes in the sheet for the current year (which would make copying and pasting from a previous year easy)

Add per tournament notes

I'm not sure how this would work yet, but probably if there is a row in the spreadsheet with something just in the first column, we could consider it some notes for a number of following games (as opposed to the notes for an individual game)

This could be used to communicate directions to the venue, details of officials and suchlike. Potentially it could even allow emojis or fontawesome icons or something, and then sports with specific needs could use them.

Refactor Calculations.LeagueTableFromLeagueGames

I did this in a hurry when my brain wasn't up to full speed, there is a lot of duplication. It's well tested and well contained though, so not actually a problem, but it would be satisfying to do.

I could use Sandi Metz flocking rules from 99 bottles of oop, and potentially write a blog post about it, and our submit it as an exercise to exercism

Invalid bookmarked urls when spreadsheet changes

If someone uses a url, but the name of the league / sheet / tab has changed, the api returns an error, and this is displayed in the UI.

It would be better to show a more user friendly message in this case, or just return to the home page, or something. Not a huge deal though as unlikely to happen at all often

Add visual testing

When converting to elm 0.19, at one point all the colours were white. This passed all the tests, but the screen looked blank and was completely unusable. This never got released, but is a hole in the tests nonetheless.

Visual testing would catch this (it basically compares pictures of how the website looks at various points, and flags if there are changes.

There are plug ins for cypress that allow visual testing, and it doesn't look like it would be very hard to set it up.

Upgrade elm-style-elements to elm-ui

elm-style-elements is deprecated, so I should probably upgraded to the newer thing which is elm-ui.

https://github.com/mdgriffith/elm-ui

https://github.com/mdgriffith/style-elements

I haven't been able to find any documentation on how to do this, but have asked a question here
https://discourse.elm-lang.org/t/upgrading-to-elm-ui/4700

Allow each deployment to have its own title

manfiest.json
"short_name": "League Tables",
"name": "League Tables",

At the moment there can be many deployments of this app, but they must all share the same title (currently "League Tables").

It would be better if each deployment could have its own title, for example "South East Regional Polo 2018/19"

Currently the title is in manifest.json, is shown on the LeagueList page and is in the <title> tag of index.html.

I could add the title to the config (which would come from an environment variable), which the LeagueList page could then use, which would be quite easy.

I could probably set the title of the page using javascript and the environnment variable, which would make the <title> tag in index.html mostly irrelevant.

I think the manifest.json file would need to be rewritten during the build step. It would probably be best to do this with a bash script so it can be easily tested locally

Add a deploy to netlify button

This will make it easier / possible to people other than me to create league table deployments.

It is probably one of the later things to do, once the code is suitable to be deployed by anyone. I think the main things to do are to add some specific theming for each deployment, and use a serverless function to call the google api

https://www.netlify.com/docs/deploy-button/