NAME

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

VERSION

Version 2.3661

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;

NOTICE!

This POD is being rewritten and may appear incomplete. If so please refer to SweetPea::Overview for the original documentation, keep in mind that the original documentation may/is probably out-dated.

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';

To install SweetPea, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SweetPea

CPAN shell

perl -MCPAN -e shell
install SweetPea

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

SYNOPSIS

NOTICE!

METHODS

new

run

test

mock

mock_data

_plugins

_load_path_and_actions

_init_dispatcher

_url_parser

start

finish

forward

detach

redirect

store

application

content_type

request_method

request

push_download

controller

action

uri

url

path

cookies

flash

file

upload

html

debug

output

plug

unplug

routes

param

sweet

VARIABLE LEGEND

\%actions

\%options

$route

$self

@data

$url

$content_type

$method

$file_or_data

$path

$flash_message

$flash_type

$filemode

$filename

$output_what

$output_where

$seperator

$accessor_name

$code_ref

$param_name

$param_type

$param_value

Module Install Instructions