hi ben,
i am not sure whether you aim for a better documentation, how the callback mechanism of ad_proc works in general or for a better documentation, how "callbacks" are used by apm. In either case, we are an open source project, where everyone can contribute.
AFIKT, the apm callbacks are not using the callbacks as defined ad_proc. No idea, why this is so, maybe predating the callback implementation in ad_proc.
Here is a short summary, how callbacks defined by ad_proc work (see [1]):
- such callbacks are defined by "ad_proc ... -callback ..."
where the proc has an empty body (no "implementation";
(see e.g. the search package [2]). This signature of the callback
is called the callback "contract".
- every package that wants to provide an implementation for this
callback can provide an implementation, defined via
"ad_proc -callback ... -impl ..." (see e.g. [3])
- internally, all callback definitions (contracts and implementations) are
stored under the Tcl namespace ::callback
- AFIKT, there is no web-interface to query/inspect callbacks definitions.
But fortunately, it is not to complex to get such information.
below is a short example, how to list from a ds/shell
all currently defined callback contracts
- you will see, there are no definitions for apm management there.
Concerning apm-callbacks (similar concept, different implementation):
- Practically all definitions around the apm-callbacks are defined in [4]
- This file has a functions to define argument lists for the apm-callbacks [5]
- In order to define an apm-callback, simply define an ad_proc and register it
via the apm manager in the web interface. if the proc has the right signature,
it is accepted
- Examples for apm-callbacks are e.g. [6], but as well in most packages.
Concerning parameter changes:
- yes, there are callbacks for parameter changes defined [7]
- an example for an implementation of the callback is in [8]
A welcome contribution would be e.g. an extension of the api-browser for callbacks (listing contracts/implementations, etc.).
Sorry for the problem with "has_links_p". This was a bug introduced yesterday afternoon by me (pushing changes to early) and fixed this morning. i am very busy right now, semester starts, everything is quite crazy right now.
Hope this helps
-gn
[1] https://openacs.org/api-doc/proc-view?proc=callback&source_p=1
[2] https://github.com/openacs/openacs-core/blob/oacs-5-9/packages/search/tcl/search-procs.tcl#L309
[3] https://github.com/openacs/forums/blob/master/tcl/forums-callback-procs.tcl#L104
[4] https://github.com/openacs/openacs-core/blob/oacs-5-9/packages/acs-tcl/tcl/apm-procs.tcl
[5] https://openacs.org/api-doc/proc-view?source_p=1&proc=apm_arg_names_for_callback_type
[6] https://github.com/openacs/xowiki/blob/oacs-5-9/tcl/xowiki-callback-procs.tcl
[7] https://github.com/openacs/openacs-core/blob/oacs-5-9/packages/acs-subsite/tcl/subsite-callback-procs.tcl#L69
[8] https://github.com/openacs/xotcl-core/blob/oacs-5-9/tcl/06-param-procs.tcl#L386
proc lookup {ns cmd} {
set result [info commands ${ns}::$cmd]
foreach subns [lsort [namespace children $ns]] {
lappend result {*}[lookup $subns $cmd]
}
return $result
}
join [lookup ::callback contract] \n