[Zope3-dev] Re: Source API

[Fred Drake]

On 9/6/05, Stuart Bishop <stuart at stuartbishop.net> wrote:
> It was more problematic in the Vocabulary code, because IVocabulary extended
> IIterableVocabulary, forcing all vocabularies to implement that interface.
> Sources give us the opportunity to reverse and fix that, making
> IIterableSource extend ISource.

Agreed.

> The docstrings don't make it clear what an ISourceQueriables is supposed to
> achieve, how one is constructed or how it is to be used.
> 
> I would imagine that the interfaces should look like:
> 
> class ISourceItem(Interface):
>     key = TextLine('Unique key', required=True)
>     title = TextLine('Descriptive text to display to users. Plain text.')
>     value = Attribute('Object represented by this ISourceItem')
> 
> class ISource(Interface):
>     context = Attribute(
>         "context the source is bound to. Generally an IChoiceField"
>         )

Many sources won't need this, so it shouldn't be necessary for them
all to implement this.

>     def __contains__(key):
>         """Returns true if the key exists in this source"""
> 
>     def __getitem__(key):
>         """Returns the ISourceItem for this key"""

See my comments about items (term objects) below.

>     def search(query):
>         """Return a sequence of ISourceItem matching the given query.
> 
>            query is a Unicode string or None. The meaning of this query
>            is ISource specific.
>         """

I wouldn't want to see search() at this point; many iterable sources
won't want to support this at all.  There should probably be an
IQueryableSource that provides this instead.

> I wouldn't like to use the title as the key, because the title might be
> changed where as keys should be unchanging (or at least more so).

Of course.

> I think the ISourceItem is important, as it allows people to extend what is
> being returned by their sources. In particular, we would have
> IIterableSource sources that return IRichSourceItem which also provides a
> snippet() method or view. This would provide an XHTML fragment which would
> be used to render a list of radio buttons or check boxes with markup in the
> descriptive text.

Aside from how context-sensitive sources are bound and the specific
arrangement of interface relationship (which needed help), you've very
much described vocabularies.  I think moving away from having the term
objects provided by the source was specifically something Jim wanted,
which is why he uses adaptation to get the ITerms object for sources. 
While I find this somewhat tedious, it actually makes a good bit of
sense, given that the terms are really only used to support the UI,
while the sources themselves are essential to the applications we
build with them.

The current ITerms approach for sources makes terms essentially views
on the values from the source, so that's a good way to provide things
like XHTML snippets that can be used in the UI.


  -Fred

-- 
Fred L. Drake, Jr.    <fdrake at gmail.com>
Zope Corporation