[Rt-commit] r2587 - in experiments/Bamboo/lib/Bamboo: . Guide
autrijus at bestpractical.com
autrijus at bestpractical.com
Wed Apr 6 09:38:08 EDT 2005
Author: autrijus
Date: Wed Apr 6 09:38:07 2005
New Revision: 2587
Added:
experiments/Bamboo/lib/Bamboo/Guide/
experiments/Bamboo/lib/Bamboo/Guide.pod
experiments/Bamboo/lib/Bamboo/Guide/Actions.pod
Log:
* bamboo docs
Added: experiments/Bamboo/lib/Bamboo/Guide.pod
==============================================================================
--- (empty file)
+++ experiments/Bamboo/lib/Bamboo/Guide.pod Wed Apr 6 09:38:07 2005
@@ -0,0 +1,149 @@
+
+=head1 NAME
+
+Bamboo::Guide - Introduction to Bamboo
+
+=head1 DESCRIPTION
+
+A Bamboo environment is represented by a single B<Bamboo> object.
+It can make use of three kinds of helpers:
+
+=head2 Model
+
+Model helpers builds I<facades> around existing classes and objects,
+and register them into the Bamboo environment.
+
+The B<Naive> model simply copies methods and attributes defined in the
+class symbol table. Additionally, Bamboo may come with models for:
+
+ Class::DBI
+ Perl6::Subs
+ DBIx::SearchBuilder
+ Tangram
+
+ XXX Unsorted stuff
+ - Facade buys you
+ - encapsuation
+ - only registered methods can be called
+ - only registered parameters can be used
+ - introspection
+ - list of methods
+ - and their parameters
+ - not type, but validator-as-type
+ - validation
+ - arbitary code callbacks
+ - yields true or false?
+ - no transformers/canonicalizers at that level
+ - transformers --- XXX TBD
+
+=head2 Controller
+
+Controller helpers translates inputs from various sources, such as B<CGI>
+form parameters, turn them into I<actions>, then run them inside the
+Bamboo environment.
+
+ XXX Unsorted stuff
+
+ * The virtual machine cleans up the lexical pad
+ * Global "persistent" objects/classes may still remain, like $dbh
+ * Useful in FastCGI/ModPerl environments
+ * The virtual machine loads the ops:
+ * From the action-specific components
+ * From the HTTP GET/POST query string
+ * From other sources that has a loader backend defined
+ * The virtual machine compiles the ops:
+ * Validates that all ops are runnable
+ * Type-checks the validity of op parameters
+ * If any parameter isn't valid, throw an error
+ * In a webby context, this should give us the option of an error page
+ * OR a page redisplay with all fields "saved" and errors highlighted
+
+ * The virtual machine runs all ops
+ * The view renders, possibly calling back into the VM
+ * The host application may invoke the VM again, or instrument it some more
+
+=head2 View
+
+View helpers generate widgets suitable for a presentation medium, such as
+B<HTML> forms. This is the bit that lets you describe your presentation
+layer. When the user gets to a certain place, what should they see? Where can
+the user go from here?
+
+What can it do:
+
+ XXX Unsorted stuff
+
+ - Model-presentation form
+ -- draws objects
+ -- arranges show/hide/whatever relations
+ -- sets and maintains the "current topic" in the stash
+ -- skinnable and themable and whatever
+ -- "widget kit"
+
+ * Display arbitrary html
+ * Build a form, containing:
+ * Display values, labels or edit widgets for
+ a given model class attribute
+ * Display labels and edit widgets for any class
+ method's parameters
+
+ XXX RESTish serializations
+ POST /Bamboo/Counter/increment
+ value: 5
+
+ GET /Bamboo/Counter/current_count
+
+=head1 EXAMPLE
+
+ XXX Totally unsorted, should factor out to Cookbook Guide
+
+ # with the 'Naive' helper
+ $bamboo->model('Naive')->import(
+ class => 'My::Class'
+ );
+
+ # with Class::DBI helper
+ $bamboo->model('CDBI')->import(
+ dsn => 'dbi:SQLite2:/tmp/myapp.db',
+ relationships => 1
+ );
+
+ # without helper, just fallback to the "base" passthru
+ $bamboo->model->import(
+ class => 'My::Facade::Class::Lalala'
+ );
+
+ # ->controller creates a object that remembers the $bamboo
+ # it's just a helper function to obtain a specific argument
+ # unpacking backend -- exactly like the model above
+ my $c = $bamboo->controller('CGI');
+ $c->run(%ARGS);
+
+ # without helper, just run bare commands
+ $bamboo->controller->run("")
+
+ # To draw out a hidden form field that encapulates the
+ # OP that calls the 'counter' object's increment method
+ my $f = $bamboo->view('HTML');
+ my $action = $bamboo->action(
+ type => 'new',
+ class => 'Counter',
+ label => 'cnt',
+ );
+ print $f->input( action => $action, type => 'hidden' );
+ print $f->input( action => 'call counter increment', type => 'hidden' );
+
+ my $facaded_counter = $c->var('counter');
+ print $f->input(
+ type => 'hidden'
+ action => $facaded_counter->call('increment'),
+ );
+
+=head1 AUTHORS
+
+Copyright 2005 by Jesse Vincent, Autrijus Tang.
+
+This library is free software; you can redistribute it
+and/or modify it under the same terms as Perl itself.
+
+=cut
Added: experiments/Bamboo/lib/Bamboo/Guide/Actions.pod
==============================================================================
--- (empty file)
+++ experiments/Bamboo/lib/Bamboo/Guide/Actions.pod Wed Apr 6 09:38:07 2005
@@ -0,0 +1,83 @@
+
+=head1 NAME
+
+Bamboo::Actions - Bamboo actions
+
+=head1 DESCRIPTION
+
+Actions are operation codes for the Bamboo environment.
+
+ XXX totally unsorted, many wrong, more outdated
+
+ - Orthogonal to the Facade Model
+ - HTTP FORM POST controls everything
+ - We may use GET just to note a particularly nondestructive
+ sequence of events, but that is not tied to the URI at all --
+ in this regard we are fundamentally SOAPish and RPCish.
+
+ - what you can pass in is not only method calls
+ - but also factory objects
+
+ 0-PetStore::Product-SomeMoniker-new = 1
+ 1-PetStore::Product-SomeMoniker-Load-__1 = 26
+ GET /Pets?=23
+ $foo = new Bar;
+ $foo = new Bar; $foo->Load(26);
+
+ - an imperative, sequential, assembly language complete
+ with LINE NUMBERS and GOTOs!
+
+ - assuming the line number is generated by the form compiler
+ in a sequential unique fashion:
+
+ # $object may be a class or a previously obtained moniker
+ "Class::Name-ObjectId"
+
+ "Class::Name-FooObj-new"
+ "Class::Name-FooObj-currentVal--_1" = 6
+
+ $FooObj = Class::Name->new()
+ $FooObj->currentVal( _1 => 6 )
+
+ $moniker = $object -> method ( %params )
+
+ - "new" is special; it is the only method that returns an object; in
+ other words, any other methods just return the invoker.
+
+ # arguments may be objects, but never classes
+ my $obj = Class.new(...);
+ my $rv = $obj.method(...);
+ $obj.some_attr = 3;
+
+ my $x = $obj.some_attr;
+ push $obj.some_attr, "hello";
+ delete $obj.some_attr{"blah"};
+
+ class Counter {
+ method doSomething {
+ $.val = rand();
+ }
+ }
+
+ # $counter is loaded first
+ <input type="button"
+ onclick="sub { $counter.val = rand() }">
+ onclick="<% serialize_call($counter, "doSomething", ()) %>">
+
+ thaw {
+ frozen objects
+ - Class
+ - Attributes
+ - mandatory ones
+ - non-mandatory that we nevertheless care about
+ - HMAC_SHA'ed with a server secret
+ }
+
+=head1 AUTHORS
+
+Copyright 2005 by Jesse Vincent, Autrijus Tang.
+
+This library is free software; you can redistribute it
+and/or modify it under the same terms as Perl itself.
+
+=cut
More information about the Rt-commit
mailing list