[Grok-dev] Re: proposal: grok.title() and grok.description()

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martijn Faassen wrote:
> Hi there,
> 
> Inspired by Tres's idea of grok.describe(), I'd like to propose two new 
> grok directives:
> 
> grok.title()
> 
> and
> 
> grok.description()
> 
> The arguments to both is a unicode string or a message id: human 
> readable text.

Can we stay with the grokkish convention that ASCII strings are alllowed
as well?  I *hate* the dead chicken of the leading 'u'.

> These directives should be usable on just about any class, ranging from 
> Model to View to Permission.
> 
> The idea is then that an application's user interface can access this 
> data (this means we need to come up with a good API to access this kind 
> of grok-defined attribute in the grok module. Anyone have any ideas?). 

How about assigning '__doc__' on the object ;)?  Actually, one might
hack the directives so that they *returned* the values when passed a
non-basestring / message ID object.

> The application's UI can then use this information to display things 
> like menus and add lists, or lists of permissions, etc, etc.
> 
> The idea is to standardize a simple mechanism for this that people can 
> start using for their own purposes.
> 
> Of course, the admin UI can probably also productively use this 
> information. If needed I could imagine some grok.info() directive or 
> somesuch that contains only information to be used by the admin UI as 
> opposed to information for end-user consumption (though docstrings might 
> serve this purpose). The admin UI would of course also be able to use 
> 'title' and 'description' on the application object.
> 
> We need sensible defaults for these two attributes. grok.description() 
> should default to grok.title().

I'd rather see it default to empty.

> What about grok.title()? I think it 
> would be bad if grok.title() defaulted to the empty string, as these 
> don't show up in the user interface and give no clue as to what object 
> you're dealing with. I therefore propose grok.title() should default to 
> the class name. This gives a good hint on what's going on in a user 
> interface where someone hasn't spelled out grok.title() yet for a 
> particular class, which can then be easily fixed.

Defaulting to '__name__' is probably fine.  Another option is to do the
"first line, rest" splitting of '__doc__'.

> What do people think?

+1 overall.


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFG2Cyw+gerLs4ltQ4RAgBEAJwNf/m0I48rL2J9KueyJpYiUDysMgCfQphr
5ic/PQ+vdKtuHQtILAqrcG4=
=pPDG
-----END PGP SIGNATURE-----