Forum OpenACS Development: suggestion about callback documentation

Hi,

I tried to post this to bugtracker, but there was an error, so am posting here:

Hi,

I've read api-doc for ad_proc and callbacks, and see callbacks invoked in some package.info files. Yet, these are insufficient to understand how to create an implementation, or to assess if it worth the time in learning about them ie to know if they will be useful with the suite of packages I'm writing. In particular:

1. api-doc for ad_proc and callbacks don't mention the defined apm triggers in apm_supported_callback_types. It would be handy if these are referenced via @see somewhere in api-doc that is at an appropriate location, and to havemore @see cases for interlinking related info.

2. Does the apm provide any extra info not otherwise available via a proc in an tcl/*-init.tcl on startup?

If so, PLEASE HIGHLIGHT these cases, as they may be extra useful for package developers.

For example, does after-instantiate have the package_id available? If so, how to access via the callback?

Either refer to an existing case as example, or provide one. It is 10,000 times easier, less time consuming, and less of a learning curve to be able to copy/adapt instead of understand the abstract jargon created for this context or borrowed from multiple other contexts.

3. Are there any callback type triggers for parameter value changes?

This may be valuable for a suite of packages with extended services that share the same subsite.

thank you,
cheers,
Ben

Collapse
Posted by Benjamin Brink on
ps. My first attempt at posting here also errored with default Format "Extended Text" input, works with "plain text" format..

Error is:

Error in forums::message::new - can't read "has_links_p": no such variable

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] 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
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