Skip to content

docs(mobile/4): document the screen lifecycle events - #452

Open
sylvesterdamgaard wants to merge 1 commit into
NativePHP:mainfrom
sylvesterdamgaard:docs/screen-lifecycle-events
Open

docs(mobile/4): document the screen lifecycle events#452
sylvesterdamgaard wants to merge 1 commit into
NativePHP:mainfrom
sylvesterdamgaard:docs/screen-lifecycle-events

Conversation

@sylvesterdamgaard

Copy link
Copy Markdown

Docs for the events added in NativePHP/mobile-air#248, as requested there. That PR is approved but not yet merged — happy to hold this until it lands.

What's here

A new Observing the lifecycle from outside section on Lifecycle Hooks, covering ScreenMounted / ScreenResumed / ScreenUnmounted: when each fires, what they carry, and how to listen.

It leads with why they exist rather than what they are, because that's the part a reader can't infer. The hooks are the app's to override, so a base class's mount() is the wrong home for anything cross-cutting — a screen defining its own mount() silently replaces it, and the observer goes quiet on exactly the screens with the most logic in them. That failure mode is invisible until you go looking for missing data, so it seemed worth stating outright.

Two behaviours are documented that a reader would otherwise have to find in the source:

  • a listener that throws is caught and logged rather than propagated, so "my listener isn't running" has a place to look
  • restoring a preloaded stack after a hot reload stays quiet, since those screens are restored rather than navigated to

Also added a short pointer from Events, which until now only covered component-targeted native events — a reader looking for "how do I observe navigation" would land there first and find nothing.

Notes

  • v4 only. The events are on the v4 line, and v3 has no digging-deeper section.
  • No new page, so no index or ordering changes.
  • Table separator style and the relative-anchor convention match the surrounding pages.
  • Section placed before Related so the hook reference stays contiguous.

Verified the uri claim against the router rather than assuming it: unmountComponent() runs before array_pop() at all seven call sites, so ScreenUnmounted reports the unmounting screen's own uri, not the one underneath it.

Covers ScreenMounted / ScreenResumed / ScreenUnmounted from
NativePHP/mobile-air#248 — a new 'Observing the lifecycle from outside'
section on the Lifecycle Hooks page, plus a pointer from the Events page,
which until now only covered component-targeted native events.

Leads with why they exist rather than what they are: the hooks are the
app's to override, so a base class's mount() is the wrong home for
anything cross-cutting. Also documents the two behaviours a reader would
otherwise have to discover from the source — listener exceptions are
logged rather than propagated, and restoring a preloaded stack after a
hot reload stays quiet.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant