Forum OpenACS Improvement Proposals (TIPs): Re: Tip #79 Callbacks

Collapse
4: Re: Tip #79 Callbacks (response to 1)
Posted by Jeff Davis on
Core uses tcl introspection to find which callbacks exist and invokes them. eg
foreach proc [info procs ::callback::module::op::impl::*] { 
  $proc $args
}
The documentation is split from the procedure since the documentation is for the "callback" not the implementation.

eg: for the apm callbacks right now if you want to know what the after mount callback does you dig through the code to find where its called. under the new scheme you could just use the api-browser to look up apm::after-mount and the declaration would look like:

ad_proc -callback apm::after-mount {
  -package_id:required
  -node_id:required
} { 
   This callback is invoked by the apm when a package is 
   mounted, note that the package may already be mounted
   elsewhere or may have been mounted before and unmounted 
   so try to ensure that these cases are properly handled in 
   your callback implementation.

   Also the implementation name must match the package key 
   in order for the apm to invoke the correct procedure.

   ...
} -
and a specific implementation might also have it's own docs:
ad_proc -callback apm::after-mount -implementation file-storage {} {
  the after mount callback for file storage creates a 
  root folder and sets default permissions.
} {
   ...
}
Note that I think we could supress the parameters for the implementation version and use the arg parse constructed for the callback in each one which would make it far easier to add optional parameters to the callbacks.

Also note how much better our lives would be with respect to the apm callbacks if we did this!