2020-07-31

An Engineering Notebook (ENB)

I’m not a newbie when it comes to software development. But I’m an absolute beginner when it comes to Phoenix/LiveView.

This is my first attempt to create something useful in Elixir/Phoenix/LiveView. I don’t yet know where this journey will end. I consider my posts in this thread as a progress report or as something like an ENB (Engineering Notebook) where I record my design reasoning and decisions.

This idea of an ENB fascinates me. I came across this idea on the Leo Google group. Leo is a Python-based outliner/IDE/development platform. In this group, the creator of Leo, Edward K. Ream, frequently writes up his reasoning about certain aspects of Leo for everybody to see and invites comments. So an outsider can better understand why what is done or left out (example).

I’ve done some prior work in this field. Out of some nostalgia and for documentation, a horribly buggy version of a Javascript-based calendar converter is included in assets/javascript/index.html. The whole user interface (mainly entry and display fields) and the scripts (calendar conversions) are contained in this single file. You can double-click on this file to open it in a browser. Its interface gives you some idea what Yacco will look like.

As Yacco will be based on my packages Calixir and Calendars I will try to show all the calendars contained in these package on one page. Changing but one field of one calendar should result in an update of all the fields of all the other calendars.

I don’t yet know how to achieve this in Phoenix, but first I want to try two approaches:

• Put every field of every calendar in its own process or agent, or
• put every every calendar with its subfields in its own process or agent.

The main idea of any reasonable calendar converter is to use a denominator that is common to all calendars. In Calixir and Calendars, this is the RataDieor fixed date. This is an artificial common denominator created by Dershowitz and Reingold in their book Calendrical Calculations. Alternately - and my preference - the Julian Day or JD was and is used, i.e. in astronomical calendars. Conversions between RataDie and JD are trivial.

The main interaction

A conversion using Yacco translates roughly into the folling steps:

• User enters a field of a calendar (any calendar).
  • This triggers an on_field_enter event that will store the current value of this field
    in a temporary variable.
• User inputs some data in the field.
• User leaves the field.
  • This triggers an on_field_left event.
  • The event_handler will compare the old and the new value of this field.
    • If they are the same, the event_handler just exits.
    • If they are different, the event_handler continues.
  • The event_handler will validate the new date.
    • On :error it will display an error message replace the new value with the new and put the cursor back into the field.
    • On :ok it it will recalculate the fixed date corresponding to the new date using its to_fixed function and brodcast the new fixed date to the other calendars.
  • Each other calendar recalculates its native date using its from_fixed function and puts it into its display fields.
• Loop repeats or user exits.

TODO: Handle different on_field_left event`s, i.e.

• an on-escape should leave the date unchanged

How to proceed

As the ‘business logic’ or ‘model’ (the calendar conversions) are all done and via Calendars available, there remain two main tasks:

• Implement the user interface (the View).
• Implement the controller.

I’ll begin with the View, because…
Show the user as soon as possible, what the product will look like.