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