Forum OpenACS Development: Re: suggestion about callback documentation

Collapse
Posted by Gustaf Neumann on
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] http://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] http://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

Collapse
Posted by Benjamin Brink on
Thank you, Gustaf. This is very helpful. I woud not have figured that out.

And thank you for the invite to help with documentation. Once I've written and released a suite of package, I'll write documentation for OpenACS. Until then, I'm posting suggestions when I run into issues that I think others may have also --in case someone else in the community is looking for ways to improve documentation too.

Maybe one day I will understand enough to contribute an extension to the api-browser that you suggest --if someone else doesn't do it first.

Until then, I will be glad to add entries to the OpenACS FAQ site, to help identify a glossary of terms for OpenACS --if someone grants write privilege to my account for it.

It sounds like you are busy in a good way,
best wishes,
cheers,
Ben