view release on metacpan or  search on metacpan

lib/ASP4.pm  view on Meta::CPAN

your subref and provide it the C<\@args> passed in.

This is useful for long-running or asynchronous processes that don't require the
client to wait for a response.

=head2 $Request

An instance of L<ASP4::Request>, the C<$Request> object contains specialized methods
for dealing with whatever the browser sent us.

Examples:

=head3 $Request->Cookies( $name )

  my $cookie = $Request->Cookies("some-cookie-name");

=head3 $Request->FileUpload( $field_name )

  if( my $file = $Request->FileUpload('avatar_pic') ) {
    # Handle the uploaded file:
    $file->SaveAs( "/var/media/$Session->{user_id}/avatar/" . $file->FileName );
  }

See also the L<ASP4::FileUpload> documentation.

=head2 $Response

An instance of L<ASP4::Response>, the C<$Response> object gives shortcuts for dealing
with the outgoing reply from the server back to the client.

Examples:

=head3 $Response->Write( $string )

The following example prints the string C<Hello, World!> to the browser:

  $Response->Write("Hello, World!");

Or, within an ASP script, C<< <%= "Hello, World" %> >>

=head3 $Response->Redirect( $url )

  $Response->Redirect( "/new/url/?foo=bar" );

=head3 $Response->SetCookie( %args )

Setting cookies works as follows:

  $Response->SetCookie(
    name  => "cookie-name",
    value => "the-value",
    
    # The rest of these arguments are optional:
    
    # Expires: (If you don't specify the "expires" argument, the cookie will
    # be deleted when the browser is closed.
    expires => "3D",  # 3 days
    expires => "3H",  # or 3 hours
    expires => "3M",  # or 3 minutes
    
    # Domain: (defaults to $ENV{HTTP_HOST})
    domain  => ".example.com",    # works for *.example.com
    domain  => "www.example.com", # will ONLY work for www.example.com
    
    # Path:
    path    => "/some/folder/"    # will ONLY work within /some/folder/ on your website
  );

=head3 $Response->Include( $path, %args )

ASP4's C<$Response> object offers 3 different include methods.

  <!-- Normal SSI-style Include -->
  <!-- #include virtual="/includes/page.asp" -->

If you want to supply arguments to the included ASP script you can use C<< $Response->Include($path, \%args) >>

  # Add the output of C</includes/page.asp> to the current output buffer:
  my %args = ( foo => "bar" );
  $Response->Include( $Server->MapPath("/includes/page.asp"), \%args );

C<\%args> is optional.

Within the included ASP script, C<\%args> is accessible like this:

  <%
    my ($self, $context, $args) = @_;
  %>

=head3 $Response->TrapInclude( $path, %args )

Or if you need to capture the result of executing an ASP script and use it within
a variable, use C<< $Response->TrapInclude($path, \%args) >>

  # Capture the output of C</includes/page.asp>:
  my %args = ( foo => "bar" );
  my $html = $Response->TrapInclude( $Server->MapPath("/includes/page.asp"), \%args );

C<\%args> is optional.

Within the included ASP script, C<\%args> is accessible like this:

  <%
    my ($self, $context, $args) = @_;
  %>

=head2 $Session

The C<$Session> object is an instance of a subclass of L<ASP4::SessionStateManager>
(depending on your website's configuration).

The C<$Session> object is a simple blessed hashref and should be used like a hashref.

Examples:

=head3 Set a session variable

  $Session->{foo} = "bar";

  $Session->{thing} = {
    banana  => "yellow",

lib/ASP4.pm  view on Meta::CPAN

Call C<< $Session->reset() >> to clear all the data out of the session and save 
it to the database.

=head2 $Config

The ASP4 C<$Config> object is stored in a simple JSON format on disk, and accessible
everywhere within your entire ASP4 application as the global C<$Config> object.

If ever you find yourself in a place without a C<$Config> object, you can get one
like this:

  use ASP4::ConfigLoader;
  my $Config = ASP4::ConfigLoader->load();

See L<ASP4::Config> for full details on the ASP4 C<$Config> object and its usage.

=head2 $Stash

The C<$Stash> is a simple hashref that is guaranteed to be the exact same hashref
throughout the entire lifetime of a request.

Anything placed within the C<$Stash> at the very beginning of processing a request -
such as in a RequestFilter - will still be there at the very end of the request -
as in a RegisterCleanup handler.

Use the C<$Stash> as a great place to store a piece of data for the duration of
a single request.

=head1 DATABASE

While ASP4 B<does not require> its users to choose any specific database (eg: MySQL or PostgreSQL)
or ORM (object-relational mapper) the B<recommended> ORM is L<Class::DBI::Lite>
since it has been completely and thoroughly tested to be 100% compatible with ASP4.

For full documentation about L<Class::DBI::Lite> please view its documentation.

B<NOTE:> L<Class::DBI::Lite> must be installed in addition to ASP4 as it is a separate library.

=head1 ASP4 QuickStart

Here is an example project to get things going.

In the C<data_connections.main> section of C<conf/asp4-config.json> you should have
something like this:

  ...
    "main": {
      "dsn":              "DBI:mysql:database_name:data.mywebsite.com",
      "username":         "db-username",
      "password":         "db-pAsswOrd"
    }
  ...

Suppose you had the following tables in your database:

  create table users (
    user_id     bigint unsigned not null primary key auto_increment,
    email       varchar(200) not null,
    password    char(32) not null,
    created_on  timestamp not null default current_timestamp,
    unique(email)
  ) engine=innodb charset=utf8;
  
  create table messages (
    message_id    bigint unsigned not null primary key auto_increment,
    from_user_id  bigint unsigned not null,
    to_user_id    bigint unsigned not null,
    subject       varchar(100) not null,
    body          text,
    created_on    timestamp not null default current_timestamp,
    foreign key fk_messages_to_senders (from_user_id) references users (user_id) on delete cascade,
    foreign key fk_messages_to_recipients (to_user_id) references users (user_id) on delete cascade
  ) engine=innodb charset=utf8;

B<NOTE:> It's best to assign every ASP4 application its own namespace.  For this
example the namespace is C<App::db::>

Create the file C<lib/App::db/model.pm> and add the following lines:

  package App::db::model;
  
  use strict;
  use warnings 'all';
  use base 'Class::DBI::Lite::mysql';
  use ASP4::ConfigLoader;
  
  # Get our configuration object:
  my $Config = ASP4::ConfigLoader->load();
  
  # Get our main database connection info:
  my $conn = $Config->data_connections->main;
  
  # Setup our database connection:
  __PACKAGE__->connection(
    $conn->dsn,
    $conn->username,
    $conn->password
  );
  
  1;# return true:

Add the following C<Class::DBI::Lite> entity classes:

C<lib/App/db/user.pm>

  package App::db::user;
  
  use strict;
  use warnings 'all';
  use base 'App::db::model';
  use Digest::MD5 'md5_hex';
  use ASP4::ConfigLoader;
  
  __PACKAGE__->set_up_table('users');
  
  __PACKAGE__->has_many(
    messages_in =>
      'App::db::message'  =>
        'to_user_id'
  );
  
  __PACKAGE__->has_many(
    messages_out  =>
      'App::db::message'  =>
        'from_user_id'
  );
  
  # Hash the password before storing it in the database:
  __PACKAGE__->add_trigger( before_create => sub {
    my ($self) = @_;