Ferreteria/v0.5/layout/event

Ferreteria: layout system: event subsystem

About

The event objects allow element objects in a layout element tree to coordinate their actions. Each event object corresponds to a particular event; an event is triggered in an object by calling OnEvent() with an event-object of the appropriate class. Core events are triggered in this order:

1. cEventNodeBuild: create any subsidiary nodes which might themselves need to receive events

2. cEventNodeFigure: do any calculations involving other nodes (which will have been created by this point)

• This allows, for example, the number of visible twigs to be calculated before rendering. Some elements may only display themselves if they have at least one visible twig -- or may display differently if they don't.
  • ...although that kind of process could probably be done without an event-system. One that can't, however, is where one element needs to access another one that is outside of its branch, to read or write data. There needs to be a means of ensuring that all required nodes will have been created by a certain point, and the layout system's event-subsystem is what does that.
  • The event-subsystem also provides an unambiguous waystation for ensuring that those calculations (which may be relatively expensive) are done exactly once.

3. cEventNodeRender: assemble the string representing the markup for the object's appearance within the output (typically the screen, but in theory could also be a document or even audio markup of some kind).

The core event objects are defined in layout/elem/event.php.

Methods

Events

• OnEvent() calls OnEventLocal()
  • OnEventLocal() calls DoLocalMethod()
    • DoLocalMethod()
• ShouldDoTwigs(): protected function ShouldDoTwigs() : bool
  • Action: Determine whether events (including rendering) should be passed down to twigs. This typically returns a flag that is set during the calculations event.
• Dispatch methods -- these each default (in tExecutableTwig) to a stub which does nothing:
  • OnBuild()
  • OnFigure(): this event should use StoreRendered() to store its rendering results.
  • OnRender()

Rendering

Much of this usage is defined/modeled in cElement.

• FetchRendered() returns the value set by StoreRendered() (which clears the stored value to prevent duplicate output)
• RenderOutput(): public function RenderOutput() : string
  • Action: Assemble the entirety of the object's output, including any twigs.
• RenderValue(): protected function RenderValue() : string
  • Action: Assemble the object's own output (separate from twig outputs).
• RenderBranch(): protected function RenderBranch() : string:
  • Action: Assemble the twig outputs, applying any whole-list formatting (e.g. <ul>) or conditionals.
• RenderTwigs(): protected function RenderTwigs() : string
  • Action: Assemble the basic twig outputs, applying any list-item formatting (e.g. <li>.

The canonical/typical method tree for rendering:

• OnFigure(), after doing any other needed calculations, calls a locally-defined method typically called RenderSelf() and sends its output to StoreRendered().
  • RenderSelf() checks conditions and (if favorable) returns the value of RenderOutput().
    • RenderOutput() calls:
      • RenderValue()
      • RenderBranch()
        • if ShouldDoTwigs(), calls RenderTwigs()

History

• 2022-07-21 The Render*() events are now less deeply integrated into the dispatch process but still may end up with some interdependencies, so it's best to use the canonical names where applicable.
• 2022-07-18 Scrapping some pieces of the current refactoring attempt.
  • Renamed:
    • OnCreateElements() → OnBuild()
    • OnRunCalculations() → OnFigure()
  • Rendering calculations will be done during OnFigure() instead of OnRender().
  • OnRender() now returns the output of FetchRendered().
    • Formerly: "This is the method called by the rendering event. It defaults (in tExecutableTwig) to a stub which does nothing."