Ferreteria/v0.5/layout/event: Difference between revisions

From Woozle Writes Code
< Ferreteria‎ | v0.5‎ | layout
Jump to navigation Jump to search
No edit summary
No edit summary
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{fmt/title|Ferreteria: '''[[../|layout]]''' system: '''event''' subsystem}}
==About==
==About==
The '''layout''' system provides classes to encapsulate the rendering of serial-text output, working from the most general output concepts down to specific HTML tags. It should be adaptable to other forms of markup.
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 {{l/ver/meth|layout/event|OnEvent}} with an event-object of the appropriate class. Core events are triggered in this order:
: '''1.''' {{l/ver/class|cEventNodeBuild}}: create any subsidiary nodes which might themselves need to receive events
: '''2.''' {{l/ver/class|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.''' {{l/ver/class|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 {{l/ferreteria/code|layout/elem/event.php}}.


The basic layout classes use the <code>ferret\{{l/ver/class|layout}}</code> namespace.
==Methods==
==Methods==
===Events: general===
===Events===
* {{l/ver/meth|layout|ShouldDoTwigs}}: <syntaxhighlight lang=php inline>protected function ShouldDoTwigs() : bool</syntaxhighlight>
* {{l/ver/meth|layout/event|OnEvent}} calls OnEventLocal()
** {{l/ver/meth|layout/event|OnEventLocal}} calls DoLocalMethod()
*** {{l/ver/meth|layout/event|DoLocalMethod}}
* {{l/ver/meth|layout/event|ShouldDoTwigs}}: <syntaxhighlight lang=php inline>protected function ShouldDoTwigs() : bool</syntaxhighlight>
** '''Action''': Determine whether events (including rendering) should be passed down to twigs. This typically returns a flag that is set during the calculations event.
** '''Action''': Determine whether events (including rendering) should be passed down to twigs. This typically returns a flag that is set during the calculations event.
===Events: rendering===
* Dispatch methods -- these each default (in {{l/ver/class|tExecutableTwig}}) to a stub which does nothing:
* {{l/ver/meth|layout|OnRender}}: <syntaxhighlight lang=php inline>public function OnRender(cEventNodeRender $oe) : void</syntaxhighlight>
** {{l/ver/meth|layout/event|OnBuild}}
** This is the optional dispatch method which the rendering event looks for. If present, it is called.
** {{l/ver/meth|layout/event|OnFigure}}: this event should use {{l/ver/meth|layout/event|StoreRendered}} to store its rendering results.
* {{l/ver/meth|layout|RenderOutput}}: <syntaxhighlight lang=php inline>public    function RenderOutput() : string</syntaxhighlight>
** {{l/ver/meth|layout/event|OnRender}}
===Rendering===
Much of this usage is defined/modeled in {{l/ver/class|cElement}}.
* {{l/ver/meth|layout/event|FetchRendered}} returns the value set by {{l/ver/meth|layout/event|StoreRendered}} (which clears the stored value to prevent duplicate output)
* {{l/ver/meth|layout/event|RenderOutput}}: <syntaxhighlight lang=php inline>public    function RenderOutput() : string</syntaxhighlight>
** '''Action''': Assemble the entirety of the object's output, including any twigs.
** '''Action''': Assemble the entirety of the object's output, including any twigs.
* {{l/ver/meth|layout|RenderValue}}: <syntaxhighlight lang=php inline>protected function RenderValue()  : string</syntaxhighlight>
* {{l/ver/meth|layout/event|RenderValue}}: <syntaxhighlight lang=php inline>protected function RenderValue()  : string</syntaxhighlight>
** '''Action''': Assemble the object's own output (separate from twig outputs).
** '''Action''': Assemble the object's own output (separate from twig outputs).
* {{l/ver/meth|layout|RenderBranch}}: <syntaxhighlight lang=php inline>protected function RenderBranch() : string</syntaxhighlight>:
* {{l/ver/meth|layout/event|RenderBranch}}: <syntaxhighlight lang=php inline>protected function RenderBranch() : string</syntaxhighlight>:
** '''Action''': Assemble the twig outputs, applying any whole-list formatting (e.g. {{xml/tag|ul}}) or conditionals.
** '''Action''': Assemble the twig outputs, applying any whole-list formatting (e.g. {{xml/tag|ul}}) or conditionals.
* {{l/ver/meth|layout|RenderTwigs}}: <syntaxhighlight lang=php inline>protected function RenderTwigs()  : string</syntaxhighlight>
* {{l/ver/meth|layout/event|RenderTwigs}}: <syntaxhighlight lang=php inline>protected function RenderTwigs()  : string</syntaxhighlight>
** '''Action''': Assemble the basic twig outputs, applying any list-item formatting (e.g. {{xml/tag|li}}.
** '''Action''': Assemble the basic twig outputs, applying any list-item formatting (e.g. {{xml/tag|li}}.


The canonical/typical method tree for rendering:
The canonical/typical method tree for rendering:
* {{l/ver/meth|layout|OnRender}} calls:
* {{l/ver/meth|layout/event|OnFigure}}, after doing any other needed calculations, calls a locally-defined method typically called {{l/ver/meth|layout/event|RenderSelf}} and sends its output to {{l/ver/meth|layout/event|StoreRendered}}.
** {{l/ver/meth|layout|RenderOutput}} calls:
** {{l/ver/meth|layout/event|RenderSelf}} checks conditions and (if favorable) returns the value of RenderOutput().
*** {{l/ver/meth|layout|RenderValue}}
*** {{l/ver/meth|layout/event|RenderOutput}} calls:
*** {{l/ver/meth|layout|RenderBranch}}
**** {{l/ver/meth|layout/event|RenderValue}}
**** if {{l/ver/meth|layout|ShouldDoTwigs}}, calls {{l/ver/meth|layout|RenderTwigs}}
**** {{l/ver/meth|layout/event|RenderBranch}}
 
***** if {{l/ver/meth|layout/event|ShouldDoTwigs}}, calls {{l/ver/meth|layout|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.
==History==
* '''2022-07-21''' The <code>Render*()</code> 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() &rarr; OnBuild()
*** OnRunCalculations() &rarr; 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 {{l/ver/class|tExecutableTwig}}) to a stub which does nothing."

Latest revision as of 12:14, 22 July 2022

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

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:

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."