Forum OpenACS Development: Is there any method for documenting <include>able templates?

Collapse
1: Is there any method for documenting <include>able templates?
Posted by Dave Bauer on 06/01/03 09:16 PM
Is there any standard method for documention the paramters an includable adp fragment accepts, and what datasources it exports similar to ad_page_contract?

Also I am interested in ideas for handling forms in includable templates. Generally, I think, passing in a return_url is necessary so the form knows where to go after processing.

Collapse
2: Re: Is there any method for documenting &lt;include&gt;able templates? (response to 1)
Posted by Lars Pind on 06/02/03 09:46 AM
Not yet, unfortunately.

I've tried to maintain a habit of documenting the parameters are the top like this:

# Expects:
#  foo:onevalue -- some explanation
#  bar:multirow (col1, col2, col3) -- explanation
#  baz:onevalue,optional -- more explanation

But I'm afraid I haven't been consistent.

I would really like to make ad_page_contract work with includeable templates, which wouldn't be terribly hard, we'll just have to make it look in the caller's scope instead of in the page form.

If we want people to actually take ad_page_contract seriously, we'd probably need to make it unset all local vars except those you specify.

And if we want people to take it really seriously, but also break existing code, we should change the templating system so it passes variables/properties not by just magically setting them as local variables, but through some other namespace (e.g. an ns_set like the current query variables), which ad_page_contract can read for you.

/Lars

Collapse
3: Re: Is there any method for documenting &lt;include&gt;able templates? (response to 1)
Posted by Robert Locke on 06/02/03 10:05 AM
<blockquote> I would really like to make ad_page_contract work with
includeable templates, which wouldn't be terribly hard,
we'll just have to make it look in the caller's scope
instead of in the page form.
</blockquote>

ad_page_contract does work in includeable templates to the extent that it looks in the form data of whatever page it was included from.

I don't know of any included templates that actually use ad_page_contract this way, but perhaps someone out there actually relies on this default behavior.  Can anyone make a case for retaining this behavior?

If not, then I agree with your suggestion.  (Though it does seem a bit strange having the same command do different things depending on the context.)

Collapse
4: Re: Is there any method for documenting &lt;include&gt;able templates? (response to 1)
Posted by Lars Pind on 06/02/03 03:19 PM
I wouldn't have a problem with adding another one, ad_component_contract, or something, which would simply call ad_page_contract, but with a special switch that directs it to look somewhere else than it otherwise would.

That would also make it explicitly clear whether a tcl/adp pair was supposed to be included or requested directly from the browser.

In fact, it could even return a 404 if called requested directly.

Collapse
5: Re: Is there any method for documenting &amp;lt;include&amp;gt;able templates? (response to 4)
Posted by Tom Jackson on 06/02/03 05:10 PM
In fact, it could even return a 404 if called requested directly.

That sound like a great idea. sub-templates should probably not be accessible directly.

Collapse
6: Re: Is there any method for documenting &amp;lt;include&amp;gt;able templates? (response to 4)
Posted by Jade Rubick on 06/02/03 07:18 PM
I also really like this idea.
Collapse
7: Re: Is there any method for documenting &lt;include&gt;able templates? (response to 1)
Posted by Dave Bauer on 06/24/03 05:03 PM
We can use ad_page_contract for includes. Just do not specify the query section.

I haven't tested if you can do this:

ad_page_contract {
doc
} -properties {
properties
}

If not, I will fix it :)

Also I want another switch for ad_page_contract to specify default values for parameters.

So either this can be part of ad_page_contract, or a seperate proc. Any ideas?