Author image Al Newkirk
and 1 contributors

NAME

SweetPea - A web framework that doesn't get in the way, or suck.

VERSION

Version 2.3664

DESCRIPTION

SweetPea is a modern web application framework that is fast, scalable, and light-weight. SweetPea has no dependencies so it runs everywhere Perl does. SweetPea has a short learning curve and a common sense object-oriented API.

SYNOPSIS

Oh how Sweet web application development can be ...

    # from the command-line (requires SweetPea::Cli)
    sweetpea make -s
    
    use SweetPea;
    sweet->routes({
    
        '/' => sub {
            shift->forward('/way');
        },
        
        '/way' => sub {
            shift->html('I am the way the truth and the light!');
        }
        
    })->run;

DOCUMENTATION

Learn more about SweetPea here, SweetPea::Documentation

Also Note! The sweetpea application generator script has been moved to SweetPea::Cli and the usage and syntax has changed a bit.

METHODS

new

the `new` method is used to instantiate a new SweetPea object.

new arguments

options

new usage and syntax

    $self = SweetPea->new(\%options)
    
    takes 1 argument
        1st argument  - optional
            \%options - sweetpea runtime options
            
    example:
    my $self = sweet;
    
    my $self = SweetPea->new({
        local_session => 1
    });
    
    my $self = SweetPea->new({
        session_folder => '/tmp/site1'
    });

run

the `run` method is used to discover controllers and actions then executes internal pre and post request processing routines.

run arguments

no arguments

run usage and syntax

    $self = $self->run
    
    takes 0 arguments
    
    example:
    my $self = sweet;
    $self->run;

test

the `test` method is used to simulate processing requests from the command line. Equivalent to the `run` method.

test arguments

route options

test usage and syntax

    $self = $self->test($route, \%options)
    
    takes 2 arguments
        1st argument  - optional
            $route    - sweetpea url route
        2nd argument  - optional
            \%options - sweetpea runtime options
            
    example:
    my $self = sweet->test;

mock

the `mock` method is used to process a sub-request and return the output without breaking the existing request. Useful for fetching pages to display or attach in email messages.

mock arguments

route

mock usage and syntax

    $self = $self->mock($route, \%options)
    
    takes 2 arguments
        1st argument  - required
            $route    - url path
        2nd argument  - optional
            \%options - sweetpea runtime options
    
    example:
    my $self = sweet;
    my @content = $self->mock('/path');

mock_data

the `mock_data` method is used by the `mock` method to store output from various stages of the sub-processing.

mock_data arguments

data

mock_data usage and syntax

    $self->mock_data(@data);
    
    takes 1 argument
        1st argument  - required
            @data     - content to be pushed into the mock datastore for
                        later retrieval
            
    example:
    This method is/should be only used by the `mock` method.

_plugins

the `_plugins` method, used by the `run` method, is used to process pre-defined plugins and load user-defined plugins.

_plugins arguments

no arguments

_plugins usage and syntax

    $self = $self->_plugins;
    
    takes 0 arguments
            
    example:
    This method is used mainly by the `run` method.

_load_path_and_actions

the `_load_path_and_actions` method is used to auto-discover Controllers and Actions, create the actions table, by treversing the Controllers folder.

_load_path_and_actions arguments

no arguments

_load_path_and_actions usage and syntax

    \%actions = $self->_load_path_and_actions;
    
    takes 0 arguments
            
    example:
    This method is use by the `run` method. And is not called manually.

_init_dispatcher

the `_init_dispatcher` method is used to process the global, local, and current request routines.

_init_dispatcher arguments

no arguments

_init_dispatcher usage and syntax

    $self->_init_dispatcher;
    
    takes 0 arguments
            
    example:
    This method is use by the `run` method and is not called manually.

_url_parser

the `_url_parser` method is used to determine the true environment of the current request as well as parse vaiable data in the url path.

_url_parser arguments

no arguments

_url_parser usage and syntax

    $boolean = $self->_url_parser;
    
    takes 0 argument
            
    example:
    This method is use by the `run` method and is not called manually.

start

the `start` method is used to print header information to the browser as well as perform other pre-print activities.

start arguments

no arguments

start usage and syntax

    $self->start;
    
    takes 0 arguments
            
    example:
    This method is use by the `_init_dispatcher` method and is not called
    manually.

finish

the `finish` method is used to finalize the request and perform all last-minute activities.

finish arguments

no arguments

finish usage and syntax

    $self->finish;
    
    takes 0 arguments
            
    example:
    This method is use by the `_init_dispatcher` method and is not called
    manually.

forward

the `forward` method is used to jump between actions (sub routines) to process related information then returns to the original action to finish processing.

forward arguments

route
self

forward usage and syntax

    $self->forward($route, $self);
    
    takes 2 arguments
        1st argument  - required
            $route    - display help for a specific command
        2nd argument  - optional
            $self     - The current class, used as a reference
            
    example:
    my $self = sweet;
    $self->routes({
        '/' => sub {
            shift->forward('/more');
            print ', buddy';
        }
        '/more' => sub {
            print '... here i am :)';
        }
    });
    
    # prints here i am, buddy

detach

the `detach` method is used to jump between actions (sub routines) to process related information but does NOT return to the original action to finish processing. Actually it invokes the finalization routines and the exits.

detach arguments

route
self

detach usage and syntax

    $self->detach($route, $self);
    
    takes 2 arguments
        1st argument  - required
            $route    - display help for a specific command
        2nd argument  - optional
            $self     - The current class, used as a reference
            
    example:
    my $self = sweet;
    $self->routes({
        '/' => sub {
            shift->detach('/more');
            print ', buddy';
        }
        '/more' => sub {
            print '... here i am :)';
        }
    });
    
    # prints here i am

redirect

the `redirect` method is used to redirect the browser to an alternate resource.

redirect arguments

url

redirect usage and syntax

    $self->redirect($url);
    
    takes 1 argument
        1st argument  - required
            $url      - absolute or relative url
            
    example:
    my $self = sweet;
    $self->redirect('http://www.sweetpea.com');
    $self->redirect('/static/index.html');

store

the `store` method is used to return the SweetPea application stash object.

store arguments

no arguments

store usage and syntax

    my $stash = $self->store;
    
    takes 0 arguments
            
    example:
    my $self = sweet;
    my $stash = $self->store;
    $self->store->{foo} = 'bar';
    print $self->store->{foo};
    
    # prints 'bar'

application

the `application` method is used to return a special section of the sweetpea stash reserved for application configuration variables.

application arguments

no arguments

application usage and syntax

    $self->application;
    
    takes 0 arguments
            
    example:
    my $self = sweet;
    my $stash = $self->application;
    $self->application->{foo} = 'bar';
    print $self->application->{foo};
    
    # prints 'bar'

content_type

the `content_type` method is used to set the type of content the browser should expect to be returned.

content_type arguments

content_type

content_type usage and syntax

    $self->content_type($content_type);
    
    takes 1 argument
        1st argument        - required
            $content_type   - type of content to be returned
            
    example:
    my $self = sweet;
    $self->content_type('text/html');
    $self->content_type('text/plain');

request_method

the `request_method` method is used to determine the method used by the browser to request the specified resource.

request_method arguments

method

request_method usage and syntax

    $self->request_method;
    
    takes 1 argument
        1st argument  - optional
            $method   - method to match against the current request
            
    example:
    my $self = sweet;
    my $foo = $self->request_method;
    # $foo equals Get, Post, etc
    
    my $foo = $self->request_method('get');
    # foo is 1 if current request method is 'get' or 0 if not

request

the `request` method is a synonym for the `request_method` method.

push_download

the `push_download` method is used to force a browser to prompt it's user to download the specified content rather than to display it.

push_download arguments

file_or_data

push_download usage and syntax

    $self->push_download($file_or_data);
    
    takes 1 argument
        1st argument        - required
            $file_or_data   - file or data to be sent as a download
            
    example:
    my $self = sweet;
    $self->push_download('/tmp/text_file.txt');
    $self->push_download('this is a test');

controller

the `controller` method is used to determine the current controller.

controller arguments

route

controller usage and syntax

    $self->controller;
    
    takes 1 argument
        1st argument  - optional
            $route    - route to append to the current route
            
    example:
    my $self = sweet;
    my $foo = $self->controller;
    # foo equals '/by' if current url path is '/by'
    
    my $foo = $self->controller('/theway');
    # foo equals '/by/theway' if current url path is '/by/theway'

action

the `action` method is used to determine the current action being requested.

action arguments

no arguments

action usage and syntax

    my $action = $self->action;
    
    takes 0 arguments
            
    example:
    my $action = $self->action;
    # $action equals 'test' if url is http://localhost/do/test
    # $action equals '_index' if url is http://localhost/do/test and
    # controller is Do::Test

uri

the `uri` method is can be used to provide access to various parts of the URL or return the existing/new URL.

uri arguments

route

uri usage and syntax

    $self->uri($route);
    
    takes 1 argument
        1st argument  - optional
            $route    - route for use in the creation of the url
            
    example:
    my $self = sweet;
    my $url = $self->uri;
    # if the current url is http://localhost/newapp/by/theway and newapp
    # is a subfolder under the docroot where our app is stored
    # $url->{here} equals http://localhost/newapp/by/theway
    # $url->{root} equals http://localhost/newapp
    
    my $url = $self->uri('/my_friend');
    # $url equals http://localhost/newapp/by/theway/my_friend

url

the `url` method is a synonym for the `uri` method.

path

the `path` method is used to determine the current root path of the application or return a new path based on the specified path.

path arguments

path

path usage and syntax

    $self->path($path);
    
    takes 1 argument
        1st argument  - optional
            $path     - path to append to the root path to be returned
            
    example:
    my $self = sweet;
    my $doc_root = $self->path;
    # $doc_root equals /var/www/site01 if /var/www/site01 is where the
    # application root is
    
    my $path = $self->path('/sweet/sessions');
    # $path equals /var/www/site01/sweet/sessions if /var/www/site01
    # is where the application root is

cookies

the `cookies` method is used to return an array of all currently existing browser cookies.

cookies arguments

no arguments

cookies usage and syntax

    my @cookies = $self->cookies;
    
    takes 0 arguments
    
    example:
    my @cookies = $self->cookies;
    # where each @cookies element is a CGI::Cookie object

flash

the `flash` method is used to store and retrieve messages in the session store for use across requests.

flash arguments

flash_message flash_type

flash usage and syntax

    $self->flash($message, $type);
    $self->flash($type);
    
    takes 2 arguments
        1st argument  - required
            $message  - display help for a specific command
        2nd argument  - optional
            $type     - type of message to flash [error|info|warn|success]
            
    example:
    my $self = sweet;
    $self->flash('info', 'something weird happened');
    $self->flash('warn', 'something weird happened');
    $self->flash('error', 'something really bad happened');
    $self->flash('success', 'something went terribly right');
    # the above commands all set (flash) session messages in thier
    # respective stores, stores being info, warn, error or success
    
    $self->flash('success', 'something went terribly right');
    # now the flash `success` store is an array and the new entry has
    # been appended
    
    my $success_message = $self->flash('success');
    my $warn_message = $self->flash('warn');
    ...
    # now $success_message, and $warn_message, etc are equal to the last
    # messages stored in thier respective stores and the stores themselves
    # are cleared

file

the `file` method is used to read and write files under the application root with ease.

file arguments

filemode filename data

file usage and syntax

    my $content = $self->file($filemode, $filename, @data);
    
    takes 3 arguments
        1st argument  - required
            $filemode - method used to open a file, e.g. [>>, >, <]
        2nd argument  - required
            $filename - name and path of the file to read or write to
        3rd argument  - optional
            @data     - content to be written to the specified file
            
    example:
    my $self = sweet;
    my $data = $self->file('>', 'new_folder/new_text.txt', 'a test');
    # creates a file new_text.txt in folder new_folder with one line
    
    my $data = $self->file('<', 'new_folder/new_text.txt');
    # read in file content from new_folder/new_text.txt
    

upload

the `upload` method is used to simplify uploading files from clients to the application server space.

upload arguments

upload_field path filename

upload usage and syntax

    my $filename = $self->upload($upload_field, $path, $filename);
    
    takes 3 arguments
        1st argument      - required
            $upload_field - name of the field input element
        2nd argument      - required
            $path         - path to folder where file will be saved
        3rd argument      - optional
            $filename     - name of file to be created
            
    example:
    my $self = sweet;
    $self->upload('form_field', '/tmp/uploads');
    # uploads a file from the client to the server using localtime to 
    # create the filename

html

the `html` method is used to store data at various stages of the request and return that data for output.

html arguments

data

html usage and syntax

    my @data = $self->html;
    
    takes 1 argument
        1st argument  - optional
            @data     - data to be stored for output
            
    example:
    my $self  =sweet;
    $self->html('save this for me', 'oh yeah, and this too');
    my @data = $self->html;
    # @data equals ['save this for me', 'oh yeah, and this too']
    my @data = $self->html;
    # @data equals [] because $self->html (no args) clears the store
    
    # Note! This method is called automatically and rendered if no
    # template is specified.

debug

the `debug` method is used to store data to be output at the command-line for debugging purposes.

debug arguments

data

debug usage and syntax

    $self->debug;
    
    takes 1 argument
        1st argument  - optional
            @data     - data to be stored for output
            
    example:
    my $self  =sweet;
    $self->debug('something happened here', "\$var has a val of $var");
    my @data = $self->data;
    # @data equals ['something happened here', "$var has a val of blah"]
    my @data = $self->data;
    # @data equals [] because $self->data (no args) clears the store

output

the `output` method is used to render stored data to the browser or command-line.

output arguments

output_what output_where seperator

output usage and syntax

    $self->output($output_what, $output_where, $seperator);
    
    takes 3 arguments
        1st argument     - required
            $output_what - what data store to render [html|debug]
        2nd argument     - optional
            $output_where- where to render content [web|cli]
        3rd argument     - optional
            $seperator   - printable line seperator
            
    example:
    my $self = sweet;
    $self->output('html'); # print html store to browser using <br/>
    $self->output('debug'); # print debug store to browser using <br/>
    
    $self->output('html', 'cli');
    # print html store to the command-line using \n
    
    $self->output('debug', 'cli', ',');
    # print debug store to the command-line using `,` as a seperator

plug

the `plug` method is used to create accessors to add-on module classes.

plug arguments

accessor_name code_ref

plug usage and syntax

    $self->plug($accessor_name, $code_ref);
    
    takes 2 argument
        1st argument        - required
            $accessor_name  - name to be used in the app to access the code
        2ns argument        - required
            $code_ref       - code that instantiates an object of a class
            
    example:
    my $self = sweet;
    $self->plug('cgi', sub {
        shift;
        CGI->new(@_);
    });
    
    # elsewhere in the code
    $self->cgi->param('foo'); # etc
    $self->cgi->url_param('bar'); # same instance, different method call
    
    $self->unplug('cgi')->cgi->param('foo'); # new instance

unplug

the `unplug` method is used to delete the existing class object instance so a new one can be created.

unplug arguments

accessor_name

unplug usage and syntax

    $self = $self->unplug($accessor_name);
    
    takes 1 argument
        1st argument       - required
            $accessor_name - name to be used in the app to access the code
            
    example:
    my $self = sweet;
    $self->unplug('cgi');
    # creates a new instance of the CGI class object the next time
    # $self->cgi is called.

routes

the `routes` method is used to define custom routes, routing urls to controllers and actions.

routes arguments

actions

routes usage and syntax

    $self = $self->routes($actions);
    
    takes 1 argument
        1st argument  - required
            \%actions - hashref of urls and coderef
            
    example:
    my $self = sweet;
    $self->routes({
        '/' => sub {
            my $s = shift;
            $s->html('Im an index page.');
        },
        '/about' => sub {
            my $s = shift;
            $s->html('Im an about us page');
        }
    });

param

the `param` method is used to access get, post and session parameters.

param arguments

param_name param_type param_value

param usage and syntax

    my $value = $self->param($param_name, $param_type);
    
    takes 2 argument
        1st argument    - required
            $param_name - name of the get, post or session parameter
        2nd argument    - optional
            $param_type - type of parameter
            
    example:
    my $self = sweet;
    my $value = $self->param('foo');
    my $value = $self->param('foo', 'get');
    
    my $new = $self->param('foo', 'session', 'something new');
    # sets value as well
    

sweet

the `sweet` method is shorthand for instantiating a new SweetPea object.

sweet arguments

options

sweet usage and syntax

    $self = sweet;
    
    takes 1 argument
        1st argument  - optional
            \%options - sweetpea runtime options
            
    example:
    my $s = sweet;
    my $s = sweet({ session_folder => '/tmp' });

VARIABLE LEGEND

\%actions

    my $routes = {
        '/url_path' => sub {
            $sweetpea_object = shift;
            ...
        },
        'other_url_path' => sub {
            $sweetpea_object = shift;
            ...
        }
    };
    

\%options

    my $sweetpea_runtime_options = {
        local_session => 1,
        session_folder => '/tmp/site1'
    };

$route

    my $route = '/'; # index/default page
    my $route = '/contact'; # good
    my $route = 'contact'; # bad

$self

    my $self = sweet; # a SweetPea object
    my $self = SweetPea->new;

@data

    my @data = qw(this is a test);
    # a simple array of data to be stored

$url

    my $url = '/path/under/application/root/'; # good
    my $url = 'http://www.somesite.com/path/under/blah'; #bad

$content_type

    my $content_type = 'text/html';
    my $content_type = 'text/plain';
    # etc

$method

    my $method = 'get'; # valid request method
    my $method = 'post'; # valid request method
    my $method = 'put'; # valid request method
    # etc

$file_or_data

    my $file_or_data = 'c:\tmp\file.txt'; # cool
    my $file_or_data = '/tmp/file.txt'; # good
    my $file_or_data = 'this is some content'; # works
    
    my $file_or_data = sweet->file('<', 'file.txt'); #bad
    my $file_or_data = join "\n", sweet->file('<', 'file.txt'); #better

$path

    my $path = 'c:\tmp\file.txt'; # bad
    my $path = '/tmp/file.txt'; # bad
    my $path = '/under/application/root'; # yes, very nice
    my $path = 'under/application/root'; # works as well

$flash_message

    my $flash_message = 'anything you need to convey to the user';

$flash_type

    my $flash_type = 'info'; #good
    my $flash_type = 'warn'; #good
    my $flash_type = 'error'; #good
    my $flash_type = 'success'; #good
    my $flash_type = 'blah'; #bad

$filemode

    my $filemode = 0666; # good
    my $filemode = 0777; #good
    my $filemode = 755; # bad
    my $filemode = 'catdog'; #bad

$filename

    my $filename = 'c:\tmp\file.txt'; # cool
    my $filename = '/tmp/file.txt'; # good

$output_what

    my $output_what = 'html'; # good
    my $output_what = 'debug'; # good
    my $output_what = 'textile'; # bad

$output_where

    my $output_where = 'web'; # good
    my $output_where = 'cli'; # bad

$seperator

    my $seperator = 'whatever'; # works, makes no sense though
    my $seperator = ',';
    my $seperator = "\n";
    my $seperator = "\r\n"; # windows
    my $seperator = "\t";

$accessor_name

    my $accessor_name = 'math'; # good
    my $accessor_name = 'math_calc'; # good
    my $accessor_name = '_math_calc'; # ok
    
    my $accessor_name = '132'; # bad
    my $accessor_name = 'math-calc'; # very bad

$code_ref

    my $code_ref = sub {
        my $sweetpea = shift; # always the first object
        ...
    };

$param_name

    my $param_name = 'whatever';

$param_type

    my $param_type = 'get'; # good
    my $param_type = 'post'; # good
    my $param_type = 'session'; # good
    
    my $param_type = 'csv'; # bad

$param_value

    my $param_value = 'whatever';