Skip to content

Update documentation for runtime events and metadata extraction#64

Open
phoyo008 wants to merge 17 commits intoortus-boxlang:v1.xfrom
phoyo008:v1.x
Open

Update documentation for runtime events and metadata extraction#64
phoyo008 wants to merge 17 commits intoortus-boxlang:v1.xfrom
phoyo008:v1.x

Conversation

@phoyo008
Copy link
Copy Markdown

@phoyo008 phoyo008 commented Mar 12, 2026

Ten core interceptor event files were previously stubs — they listed event names but provided no information about what data each event carries, when it fires, or how to write a listener. This PR fully documents all of them with typed data payload tables and BoxLang listener examples.

All core interceptor event files follow a consistent three-part structure per event:

1. Event Description

Each event opens with a plain-language explanation of when it fires and what it is useful for. Example:

Fired after the runtime has fully started up. Use this to run startup logic that depends on the runtime being ready.


2. Files Updated

File Events Documented
runtime-events.md onRuntimeStart, onRuntimeShutdown, onRuntimeConfigurationLoad, onRuntimeBoxContextStartup, onServerScopeCreation, onConfigurationLoad, onConfigurationOverrideLoad, onParse, onMissingMapping
application-events.md onApplicationStart, onApplicationEnd, onSessionStart, onSessionEnd, onRequestStart, onRequestEnd, onAbort, onError, onMissingTemplate
request-context-events.md onRequestContextStart, onRequestContextEnd, onRequestContextClose
template-invocations.md preTemplateInvoke, postTemplateInvoke
function-invocations.md preFunctionInvoke, postFunctionInvoke
life-cycle-events.md onBIFInvoke, onComponentInvoke, onComponentCreate, onComponentDestroy
object-marshalling-events.md beforeObjectMarshallSerialize, afterObjectMarshallSerialize, beforeObjectMarshallDeserialize, afterObjectMarshallDeserialize
cache-object-store-events.md onCacheObjectStoreSet, onCacheObjectStoreGet, onCacheObjectStoreDelete, onCacheObjectStoreClear
logging-events.md logMessage
dump-events.md onDump

3. What Each File Now Contains

Every event section includes:

  • Description — when the event fires and why it's useful
  • Data Structure table — every key the event passes, its type, and what it represents
  • Example — a working BoxLang class listener showing how to handle the event

This reverts commit d35ac59.
This reverts commit 30a0910.
# Cache Object Store Events
completed the documentation for this part
Runtime Events, BIF & Component Lifecycle, Application & Request, Session, Template & Function Invocations, Serialization / Marshalling, Logging & Dump
Pablo updates Runtime Events, BIF & Component Lifecycle, Application & Request, Session, Template & Function Invocations, Serialization / Marshalling, Logging & Dump
@phoyo008 phoyo008 marked this pull request as ready for review March 12, 2026 04:10
Comment thread workbench/bif_metadata_extractor.py Outdated
Comment thread book.json Outdated
Comment thread package-lock.json Outdated
@lmajano
Copy link
Copy Markdown
Contributor

lmajano commented Mar 13, 2026

Few comments and we can merge

@bdw429s
Copy link
Copy Markdown
Contributor

bdw429s commented Mar 13, 2026

@phoyo008 You have this many times in the examples

class myListener{

but this is not proper syntax for BoxLang as we don't declare the class name there. Make these just be

class {

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.

3 participants