SweetPea - A web framework that doesn't get in the way, or suck.
Version 2.3664
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.
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;
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.
the `new` method is used to instantiate a new SweetPea object.
new arguments
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'
});
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;
the `test` method is used to simulate processing requests from the command line. Equivalent to the `run` method.
test arguments
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;
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
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');
the `mock_data` method is used by the `mock` method to store output from various stages of the sub-processing.
mock_data arguments
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.
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.
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.
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.
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.
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.
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.
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
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
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
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
the `redirect` method is used to redirect the browser to an alternate resource.
redirect arguments
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');
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'
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'
the `content_type` method is used to set the type of content the browser should expect to be returned.
content_type arguments
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');
the `request_method` method is used to determine the method used by the browser to request the specified resource.
request_method arguments
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
the `request` method is a synonym for the `request_method` method.
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
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');
the `controller` method is used to determine the current controller.
controller arguments
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'
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
the `uri` method is can be used to provide access to various parts of the URL or return the existing/new URL.
uri arguments
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
the `url` method is a synonym for the `uri` method.
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 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
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
the `flash` method is used to store and retrieve messages in the session store for use across requests.
flash arguments
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
the `file` method is used to read and write files under the application root with ease.
file arguments
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
the `upload` method is used to simplify uploading files from clients to the application server space.
upload arguments
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
the `html` method is used to store data at various stages of the request and return that data for output.
html arguments
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.
the `debug` method is used to store data to be output at the command-line for debugging purposes.
debug arguments
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
the `output` method is used to render stored data to the browser or command-line.
output arguments
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
the `plug` method is used to create accessors to add-on module classes.
plug arguments
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
the `unplug` method is used to delete the existing class object instance so a new one can be created.
unplug arguments
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.
the `routes` method is used to define custom routes, routing urls to controllers and actions.
routes arguments
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');
}
});
the `param` method is used to access get, post and session parameters.
param arguments
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
the `sweet` method is shorthand for instantiating a new SweetPea object.
sweet arguments
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' });
my $routes = {
'/url_path' => sub {
$sweetpea_object = shift;
...
},
'other_url_path' => sub {
$sweetpea_object = shift;
...
}
};
my $sweetpea_runtime_options = {
local_session => 1,
session_folder => '/tmp/site1'
};
my $route = '/'; # index/default page
my $route = '/contact'; # good
my $route = 'contact'; # bad
my $self = sweet; # a SweetPea object
my $self = SweetPea->new;
my @data = qw(this is a test);
# a simple array of data to be stored
my $url = '/path/under/application/root/'; # good
my $url = 'http://www.somesite.com/path/under/blah'; #bad
my $content_type = 'text/html';
my $content_type = 'text/plain';
# etc
my $method = 'get'; # valid request method
my $method = 'post'; # valid request method
my $method = 'put'; # valid request method
# etc
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
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
my $flash_message = 'anything you need to convey to the user';
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
my $filemode = 0666; # good
my $filemode = 0777; #good
my $filemode = 755; # bad
my $filemode = 'catdog'; #bad
my $filename = 'c:\tmp\file.txt'; # cool
my $filename = '/tmp/file.txt'; # good
my $output_what = 'html'; # good
my $output_what = 'debug'; # good
my $output_what = 'textile'; # bad
my $output_where = 'web'; # good
my $output_where = 'cli'; # bad
my $seperator = 'whatever'; # works, makes no sense though
my $seperator = ',';
my $seperator = "\n";
my $seperator = "\r\n"; # windows
my $seperator = "\t";
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
my $code_ref = sub {
my $sweetpea = shift; # always the first object
...
};
my $param_name = 'whatever';
my $param_type = 'get'; # good
my $param_type = 'post'; # good
my $param_type = 'session'; # good
my $param_type = 'csv'; # bad
my $param_value = 'whatever';
