[jifty-devel] doc diff for Jifty::DBI::Schema

[Jesse Vincent]

On Thu, Feb 02, 2006 at 09:20:54AM -0700, Chris Fedde wrote:
> Below are diffs adding a partially filled out pod to Jifty::DBI::Schema.
> Please provide any feedback and I'll update and re-post

Woot! Thank you so much. I've made a couple notes below

> --
>     Chris Fedde
> --
> Index: lib/Jifty/DBI/Schema.pm
> ===================================================================
> --- lib/Jifty/DBI/Schema.pm	(revision 537)
> +++ lib/Jifty/DBI/Schema.pm	(working copy)
> @@ -3,6 +3,49 @@
>  
>  package Jifty::DBI::Schema;
>  
> +=head1 NAME
> +
> +Jifty::DBI::Schema - Use a simple syntax to describe a Jifty table.
> +
> +=head1 VERSION
> +
> +Version 0.03
> +
> +=cut
> +
> +our $VERSION = '$LastChangedRevision$' =~ /(\d+)/ ? $1 : 0;

We don't tend to do that, mostly because SVK doesn't do what you might
expect with local checkouts.

> +
> +=head1 SYNOPSIS
> +
> +package Wifty::Model::Page::Schema;
> +use Jifty::DBI::Schema;
> +
> +
> +=cut
> +
> +=head1 DESCRIPTION
> +
> +Each Jifty Application::Model::Class module describes a collection class

describes a record class.

> +for for a Jifty application.  Each column statement sets out the name and
> +attributes used to describe the column in a backend database, html form

"user interface" more generally than html forms ;)


> +and other processing.  For example:
> +
> +    column content =>
> +	type is 'text',
> +	label is 'Content',
> +	render_as 'textarea';
> +
> +defines a column called "content" that is of type "text".  It will be
> +rendered with the label "Content" (note the capital) and as a "textarea" in
> +a HTML form.
> +
> +Jifty::DBI::Schema builds a Jifty::DBI::Column.  That class defines other
> +attributes for database structure that are not exposed directly here.
> +One example of this is the  "refers_to" method used to create associations
> +between classes.
> +
> +=cut
> +
>  use Carp qw/carp/;
>  use Exporter::Lite;
>  our @EXPORT
> @@ -10,6 +53,17 @@
>  
>  our $SCHEMA;
>  
> +=head1 FUNCTIONS
> +
> +All these functions are exported.
> +
> +=head2 column
> +
> +Set forth the description of a column in the data store.
> +If the name ends with '_id' then it is taken to be a "primary key".
> 

Is that last statement actaully true? By default, Jifty::DBI forces you
to call it just 'id' and autocreates it for you.
+
> +=cut
> +
>  sub column {
>      my $name = lc(shift);
>  
> @@ -59,84 +113,177 @@
>      $from->COLUMNS->{$name} = $column;
>  }
>  
> +=head2 type
> +
> +type passed to our database abstraction layer, which should resolve it to
> +a database-specific type.
> +
> +=cut
> +
>  sub type ($) {
>      _list( type => shift );
>  }
>  
> +=head2 default
> +
> +Give a default value for the column.
> +
> +=cut
> +
>  sub default ($) {
>      _list( default => shift );
>  }
>  
> +=head2 validator
> +
> +=cut
> 

A subroutine reference (or possibly also a package and method name?)
that validates values for this method. iirc, it returns a tuple of
"success" and "message"


+
>  sub validator ($) {
>      _list( validator => shift );
>  }
>  
> +=head2 immutable
> +
> +=cut
> 
IS it changable once written? You might use this for "created by"

+
>  sub immutable () {
>      _item( [ writable => 0 ] );
>  }
>  
> +=head2 unreadable
> +
> +=cut
> 
Is it readable using the normal API once written? You might use this for
'password' fields.

+
>  sub unreadable {
>      _item( [ readable => 0 ] );
>  }
>  
> +=head2 length
> +
> +=cut
> +
>  sub length ($) {
>      _list( length => shift );
>  }
>  
> +=head2 mandatory
> +
> +Mark as a required.  May be used for generating ddl and for UI behaviors.
> +
> +=cut
> +
>  sub mandatory () {
>      _item( [ mandatory => 1 ] );
>  }
>  
> +=head2 distinct
> +
> +=cut
> +
>  sub distinct () {
>      _item( [ distinct => 1 ] );
>  }
>  
> +=head2 not_null
> +
> +used by the database abstraction to generate a constraint.
> +
> +=cut
> +
>  sub not_null () {
>      carp "'is not_null' is deprecated in favor of 'is mandatory'";
>      _item( [ mandatory => 1 ] );
>  }
>  
> +=head2 input_filters
> +
> +=cut
> +
>  sub input_filters ($) {
>      _list( input_filters => shift );
>  }
>  
> +=head2 output_filters
> +
> +=cut
> +
>  sub output_filters ($) {
>      _list( output_filters => shift );
>  }
>  
> +=head2 since
> +
> +what Application version this column was last changed
> +
> +=cut
> +
>  sub since ($) {
>      _list( since => shift );
>  }
>  
> +=head2 valid_values
> +
> +=cut

A list of valid values for this column. Jifty will use this to
autoconstruct a validator for you. (It will also construct a select-one
list in the UI.)


>  sub valid_values ($) {
>      _list( valid_values => shift );
>  }
>  
> +=head2 label
> +
> +=cut

A human readable label for this field in your application's UI

>
>  sub label ($) {
>      _list( label => shift );
>  }
>  
> +=head2 hints
> +
> +=cut

A sentence or two to display in long-form userinterface forms about what
might go in this column.

+
>  sub hints ($) {
>      _list( hints => shift );
>  }
>  
> +=head2 render_as
> +
> +Used in html generation to pick an field type.
> 

user interface generation.

+
> +=cut
> +
>  sub render_as ($) {
>      _list( render_as => shift );
>  }
>  
> +=head2 is
> +
> +=cut
> +
>  sub is ($) {
>      my $thing = shift;
>      ref $thing eq "ARRAY" ? _list( @{$thing} ) : _item($thing);
>  }
>  
> +=head2 by
> +
> +=cut
> +
>  sub by ($) {
>      _list( by => shift );
>  }
>  
> +=head2 are
> +
> +=cut
> +
>  sub are (@) {
>      _item( [@_] );
>  }
>  
> +=head2 on
> +
> +=cut
> +
>  sub on ($) {
>      _list( self => shift );
>  }
> @@ -158,4 +305,19 @@
>      $_[0];
>  }
>  
> +=head1 EXAMPLE
> +
> +=head1 AUTHOR
> +
> +=head1 BUGS
> +
> +=head1 SUPPORT
> +
> +=head1 COPYRIGHT & LICENSE
> +
> +This program is free software; you can redistribute it and/or modify it
> +under the same terms as Perl itself.
> +
> +=cut
> +
>  1;
> _______________________________________________
> jifty-devel mailing list
> jifty-devel at lists.jifty.org
> http://lists.jifty.org/cgi-bin/mailman/listinfo/jifty-devel
> 

--