Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

redid the README

  • Loading branch information...
commit eef08d4e15c6b90aea0ba122518191efcd455ee3 1 parent 3f54e5a
@beppu authored
Showing with 223 additions and 56 deletions.
  1. +90 −0 EARLY_NOTES
  2. +133 −56 README
View
90 EARLY_NOTES
@@ -0,0 +1,90 @@
+ RANDOM NOTES
+ ============
+
+ There is an example application in the eg/ directory
+ called "Example".
+
+ This is how you currently run this squatting application:
+
+ cd eg/
+ squatting Example
+
+ (Example.pm needs to be discoverable through @INC.)
+
+ - -*- -
+
+ If you're familiar w/ the Camping API,
+ the Squatting API will feel similar.
+
+ - -*- -
+
+ Example::Controllers is the package that contains all the controllers.
+
+ - -*- -
+
+ Controllers are objects (not classes)
+ that are constructed using the C() function.
+
+ - -*- -
+
+ Controllers represent HTTP Resources
+ that support HTTP Methods
+ like GET and POST with
+ the object methods
+ get and post.
+
+ This was the genius of Camping.
+ I can't think of a better way to
+ express RESTful controllers.
+
+ - -*- -
+
+ Example::Views is the package that contains all the views.
+
+ - -*- -
+
+ Views are also objects (not classes)
+ that are constructed using the V() function.
+
+ - -*- -
+
+ The methods of a view are thought of as templates.
+
+ - -*- -
+
+ The responsibility of a template is to
+ 1) take a hashref of variables and
+ 2) return a string.
+
+ You may use any templating system you want,
+ or even none at all.
+
+ - -*- -
+
+ You may define a layout template called 'layout'
+ which will be used to wrap the content of any other template.
+ If you don't want your template to be wrapped, you have
+ to give it a name with a '_' in front.
+
+ - -*- -
+
+ You may define a generic template called '_' for use when
+ a specific template can't be found.
+
+ - -*- -
+
+ You may have multiple views.
+
+ - -*- -
+
+ The first view you define is your default view.
+
+ - -*- -
+
+ The optional 2nd parameter to the render() method
+ lets you specify which view you want to use. For example,
+
+ $self->render('profile', 'json')
+
+ would render the 'profile' template using the 'json' view.
+
View
189 README
@@ -48,96 +48,173 @@
...
http://en.wikipedia.org/wiki/Squatting
- http://github.com/beppu/squatting/tree/master
+ https://github.com/beppu/squatting
+
+
+The API (should fit comfortably in your head with plenty of room to spare).
+---------------------------------------------------------------------------
+
+## [0] BEGINNING AN APP
+
+ package App;
+ use Squatting; # <-- This use statement is where the magic happens.
+ #
+ # %App::CONFIG
+ # &App::D
+ # &App::Controllers::R
+ # @App::Controllers::C
+ # %App::Controllers::C
+ # &App::Controllers::C
+ # &App::Views::R
+ # @App::Views::V
+ # %App::Views::V
+ #
+ # @App::ISA = qw(Squatting);
+ # # ...and Squatting->isa('Class::C3::Componentised')
+
+## [1] CUSTOMIZING AN APP
+
+ our %CONFIG = (
+ # App configuration goes in a hash.
+ );
+
+ # Code that needs to run when the app starts goes in init().
+ sub init {
+ my ($class) = @_;
+ $class->next::method();
+ }
+ # Code that needs to run on every request goes in service().
+ sub service {
+ my ($class, $controller, @args) = @_;
+
+ # before controller
- RANDOM NOTES
- ============
+ my $content = $class->next::method($controller, @args);
- There is an example application in the eg/ directory
- called "Example".
+ # after controller
- This is how you currently run this squatting application:
+ return $content;
+ }
- cd eg/
- squatting Example
+ 1;
- (Example.pm needs to be discoverable through @INC.)
+## [2] DEFINE CONTROLLERS
- - -*- -
+ package App::Controllers;
+ our @C = (
- If you're familiar w/ the Camping API,
- the Squatting API will feel similar.
+ C(
+ 'Home' => [ '/' ],
+ get => sub {
+ }
+ ),
- - -*- -
+ C(
+ 'Post' => [ '/(\d+)/(\d+)/(\w+)' ],
+ get => sub {
+ my ($self, $year, $month, $slug) = @_;
+ },
+ post => sub {
+ my ($self, $year, $month, $slug) = @_;
+ }
+ )
- Example::Controllers is the package that contains all the controllers.
+ C(
+ 'Comment' => [ '/comment' ],
+ post => sub {
+ }
+ )
- - -*- -
+ );
- Controllers are objects (not classes)
- that are constructed using the C() function.
+ 1;
- - -*- -
+## [3] DEFINE VIEWS
- Controllers represent HTTP Resources
- that support HTTP Methods
- like GET and POST with
- the object methods
- get and post.
+ package App::Views;
+ our @V = (
+ V(
+ 'Default',
- This was the genius of Camping.
- I can't think of a better way to
- express RESTful controllers.
+ layout => sub {
+ my ($self, $v, $content) = @_;
+ # This optional method allows you to wrap the content
+ # that your template methods return.
+ return "HEADER $content FOOTER";
+ },
- - -*- -
+ _partial => sub {
+ my ($self, $v) = @_;
+ # If you want a view to not be wrapped by the layout,
+ # its name should begin with "_".
+ return "exactly what you want";
+ },
- Example::Views is the package that contains all the views.
+ wrapped => sub {
+ my ($self, $v) = @_;
+ # This template's name does not begin with "_" so it
+ # WILL be wrapped by the layout.
+ return "wrapped content";
+ }
- - -*- -
+ _ => sub {
+ my ($self, $v) = @_;
+ # If a named template method is not found, this method
+ # will be run. Think of it as AUTOLOAD for views.
+ return "something";
+ },
- Views are also objects (not classes)
- that are constructed using the V() function.
+ ),
+ );
+
+ 1;
- - -*- -
- The methods of a view are thought of as templates.
+SUMMARY OF THE SQUATTING API
+----------------------------
- - -*- -
+%App::CONFIG Where your app configuration is expected to be
- The responsibility of a template is to
- 1) take a hashref of variables and
- 2) return a string.
+&App::init Code that runs on applicationn initialization
- You may use any templating system you want,
- or even none at all.
+&App::service Code that runs on every HTTP request
- - -*- -
+App::Controllers Package where controllers are expected to be
- You may define a layout template called 'layout'
- which will be used to wrap the content of any other template.
- If you don't want your template to be wrapped, you have
- to give it a name with a '_' in front.
+@App::Controllers::C Array where controllers are expected to be
- - -*- -
+&App::Controllers::C Helper function for creating Squatting::Controller
+ objects
- You may define a generic template called '_' for use when
- a specific template can't be found.
+&App::Controllers::R Helper function for generating URL paths;
+ Think "R" for "route".
- - -*- -
+App::Views Package where views are expected to be
- You may have multiple views.
+@App::Views::V Array where views are expected to be
- - -*- -
+&App::Views::V Helper function for creating Squatting::View objects
- The first view you define is your default view.
+&App::Views::R Helper function for generating URL paths;
+ It's the exact same function as &App::Controllers::R.
+ &App::Controllers::R == &App::Views::R
- - -*- -
- The optional 2nd parameter to the render() method
- lets you specify which view you want to use. For example,
+You should be able to memorize this quite easily, and I hope you
+never have to use a search engine to figure out how any of this works.
+The entire API should fit comfortably inside your mind with plenty of
+room to spare.
- $self->render('profile', 'json')
- would render the 'profile' template using the 'json' view.
+For more information:
+ `perldoc Squatting`
+ `perldoc Squatting::Controller`
+ `perldoc Squatting::View`
+
+
+For practical examples, see:
+ Rhetoric (a simple blogging system)
+ Pod::Server (a POD browser)
+ Stardust (a COMET server)
Please sign in to comment.
Something went wrong with that request. Please try again.