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

2022-07-18 about to implement this...

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

• FetchRendered() returns the value set by StoreRendered(), and clears it (so it won't be used more than once)

History

• 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().

Obsolete

Tried to do things this way for about a week, but ran into problems and then came up with the above. 2022-07-18

• OnRender(): public function OnRender(cEventNodeRender $oe) : void
  • This is the method called by the rendering event. It defaults (in tExecutableTwig) to a stub which does nothing.
• 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:

• OnRender() calls:
  • RenderOutput() calls:
    • RenderValue()
    • RenderBranch()
      • if ShouldDoTwigs(), calls RenderTwigs()

This tree can be overridden at any point, but generally it's best to do so at the lowest level in order to cause the least disruption to offspring classes.