So I think where we went wrong with the whole "unicorns" thing was to choose the unicorns half of "unicorns and blueberries", so this time around I'm going to choose the "blueberries" as my metaphor.
All joking aside, I think it is possible to draw up the requisite set of metaphors and classes using the idea of blueberries, their constituent parts and their packaging to map to the ideas we have about cards.
As much as possible, I am going to try and avoid using the word "card" anywhere in this document after the overview, but many of the blueberry terms map on to one or another notion of "card" that we have had over the years.
This document is written entirely from the perspective that everything is being served using a Ziniki stack and the Ziniki recipe/cardmix functionality. It doesn't have to be that way, but that is the case that I/we really care about and if we can get that working, I'm sure we can get any other case working in the fullness of time.
At the current time of writing, Ziniki does support basic packaging and transpiling of code and the tasks are out there to up this to the next level of delivery of integrated units of functionality and libraries so that it offers something "above" simple transpilation and that makes sense in terms of implementing "Cardalog".
The desire is to write a front-end application in Javascript in a composable manner. Theoretically, different parts of the application could use different frameworks to manage their operations. While this is planned to be supported, everything I write will assume that all the components are using Ember. I believe there would be technical limitations on nesting if nested components are not using the same framework as their containers.
The application comes into being when a user visits an application URL. This is (in Ziniki terms specifically) a request to a Ziniki server for an application. This returns an HTML file which is automatically generated to contain all the relevant links for the basic application modules (such as the framework libraries). It also contains all of the code needed to describe the application itself and the services that are provided through contracts to nested cards.
Depending on the setup of the server, it is also possible that some body HTML will be sent over, but it is expected that this will generally be generated by the container and its constituent cards.
It is generally to be expected that the root application will contain enough to get started, but in order for it to be a card-based application, it will have to have at least one card container in its UI area.
In order to populate this, it needs to obtain some "cards" from the data store. There is a Ziniki request for this, based on the context in mind, which returns a set of "cardmix" objects. For the purpose of the blueberry metaphor, we will introduce these here as "blueberry seeds".
These are simple JSON objects which identify at least:
A preferred "card identity" which we will call a BlueberryVariety.
Basically this is a string identifier of a package of code which could
be called upon in some contexts to render the data and provide other
services.
A unique handle by which the application or the BlueberryVariety can
locate and load the data associated with the object, either directly
or mapped to an "envelope" which enables it to be interpreted in an
abstract form without consulting the blueberry itself.
A handle pointing to state data associated with this blueberry used by this user. The first time a user interacts with a particular blueberry, there is a default state but subsequently user interactions (such as changing filters etc) can be recorded independently from the object data on a per-user basis.
The overall form of this request returns a hierarchy which corresponds in shape to the hierarchy of nested blueberries as displayed on the screen.
The containing environment then attempts to instantiate each of these blueberries and organize them on the screen real estate in their respective container groupings. The exact mechanism by which the blueberries are instantiated depends on a number of factors including the availability and suitability of the BlueberryVariety object.
Blueberries are intended to be an abstraction. While everything here is currently written in terms of either plain JavaScript or Ember, it should be possible to use the blueberry concepts and some variant of the API to implement blueberries in an arbitrary framework.
Blueberries can either be instantiated within the containing environment, in which case they must use the same framework as the containing environment, or nested inside exactly one level deep of iframes, in which case the top-level blueberry in the iframe "chooses" a framework and any sub-nested blueberries must use the same framework.
If these rules cannot be obeyed, then the data must be presented using an envelope projection and a suitable template in the framework's template engine.