ASP4

 view release on metacpan or  search on metacpan

README.markdown  view on Meta::CPAN

Within the included ASP script, `\%args` is accessible like this:

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

### $Response->TrapInclude( $path, %args )

Or if you need to capture the result of executing an ASP script and use it within
a variable, use `$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 );

`\%args` is optional.

Within the included ASP script, `\%args` is accessible like this:

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

## $Session

The `$Session` object is an instance of a subclass of [ASP4::SessionStateManager](http://search.cpan.org/perldoc?ASP4::SessionStateManager)
(depending on your website's configuration).

The `$Session` object is a simple blessed hashref and should be used like a hashref.

Examples:

### Set a session variable

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

    $Session->{thing} = {
      banana  => "yellow",
      cherry  => "red",
      peach   => "pink,
    };

### Get a session variable

    my $foo = $Session->{foo};

### $Session->save()

Called automatically at the end of every successful request, causes any changes
to the `$Session` to be saved to the database.

### $Session->reset()

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

## $Config

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

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

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

See [ASP4::Config](http://search.cpan.org/perldoc?ASP4::Config) for full details on the ASP4 `$Config` object and its usage.

## $Stash

The `$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 `$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 `$Stash` as a great place to store a piece of data for the duration of
a single request.

# DATABASE

While ASP4 __does not require__ its users to choose any specific database (eg: MySQL or PostgreSQL)
or ORM (object-relational mapper) the __recommended__ ORM is [Class::DBI::Lite](http://search.cpan.org/perldoc?Class::DBI::Lite)
since it has been completely and thoroughly tested to be 100% compatible with ASP4.

For full documentation about [Class::DBI::Lite](http://search.cpan.org/perldoc?Class::DBI::Lite) please view its documentation.

__NOTE:__ [Class::DBI::Lite](http://search.cpan.org/perldoc?Class::DBI::Lite) must be installed in addition to ASP4 as it is a separate library.

# ASP4 QuickStart

Here is an example project to get things going.

In the `data_connections.main` section of `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,

README.markdown  view on Meta::CPAN

    

    # Verify an email/password combination and return the user if a match is found:
    sub check_credentials {
      my ($self, %args) = @_;
      

    my ($result) = $self->search(
      email     => $args{email},
      password  => $self->hash_password( $args{password} ),
    );
    

      $result ? return $result : return;
    }
    

    # Convert a password string into its hashed value:
    sub hash_password {
      my ($self, $str) = @_;
      

      my $key = ASP4::ConfigLoader->load->system->settings->signing_key;
      return md5_hex( $str . $key );
    }
    

    1;# return true:

`lib/App/db/message.pm`

    package App::db::message;
    

    use strict;
    use warnings 'all';
    use base 'App::db::model';
    

    __PACKAGE__->set_up_table('messages');
    

    __PACKAGE__->belongs_to(
      sender  =>
        'App::db::user' =>
          'from_user_id'
    );
    

    __PACKAGE__->belongs_to(
      recipient =>
        'App::db::user' =>
          'to_user_id'
    );
    

    1;# return true:

Create your MasterPage like this:

File: `htdocs/masters/global.asp`

    <%@ MasterPage %>
    <!DOCTYPE html>
    <html>
      <head>
        <title><asp:ContentPlaceHolder id="meta_title"></asp:ContentPlaceHolder></title>
        <meta charset="utf-8" />
      </head>
      <body>
        <h1><asp:ContentPlaceHolder id="headline"></asp:ContentPlaceHolder></h1>
        <asp:ContentPlaceHolder id="main_content"></asp:ContentPlaceHolder>
      </body>
    </html>

File: `htdocs/index.asp`

    <%@ Page UseMasterPage="/masters/global.asp" %>
    

    <asp:Content PlaceHolderID="meta_title">Register</asp:Content>
    

    <asp:Content PlaceHolderID="headline">Register</asp:Content>
    

    <asp:Content PlaceHolderID="main_content">
    <%
      # Sticky forms work like this:
      if( my $args = $Session->{__lastArgs} ) {
        map { $Form->{$_} = $args->{$_} } keys %$args;
      }
      

      # Our validation errors:
      my $errors = $Session->{validation_errors} || { };
      $::err = sub {
        my $field = shift;
        my $error = $errors->{$field} or return;
        %><span class="field_error"><%= $Server->HTMLEncode( $error ) %></span><%
      };
    %>
    <form id="register_form" method="post" action="/handlers/myapp.register">
      <p>
        <label>Email:</label>
        <input type="text" name="email" value="<%= $Server->HTMLEncode( $Form->{email} ) %>" />
        <% $::err->("email"); %>
      </p>
      <p>
        <label>Password:</label>
        <input type="password" name="password" />
        <% $::err->("password"); %>
      </p>
      <p>
        <label>Confirm Password:</label>
        <input type="password" name="password2" />
        <% $::err->("password2"); %>
      </p>
      <p>
        <input type="submit" value="Register Now" />
      </p>
    </form>
    </asp:Content>

The form submits to the URL `/handlers/app.register` which means `handlers/app/register.pm`

File: `handlers/app/register.pm`

    package app::register;
    

    use strict;
    use warnings 'all';
    use base 'ASP4::FormHandler';
    use vars __PACKAGE__->VARS; # Import $Response, $Form, $Session, etc
    use App::db::user;
    

README.markdown  view on Meta::CPAN

      my ($self) = @_;
      

    $self->trim_form;
    

    my $errors = { };
    no warnings 'uninitialized';
    

    # email:
    if( length($Form->{email}) ) {
      # Basic email validation:
      unless( $Form->{email} =~ m{[^@]+@[^@]+\.[^@]+} ) {
        $errors->{email} = "Invalid email address";
      }
    }
    else {
      $errors->{email} = "Required";
    }
    

    # password:
    unless( length($Form->{password} ) {
      $errors->{password} = "Required";
    }
    

    # password2:
    if( length($Form->{password2}) ) {
      if( length($Form->{password}) ) {
        unless( $Form->{password} eq $Form->{password2} ) {
          $errors->{password2} = "Passwords don't match";
        }
      }
    }
    else {
      $errors->{password2} = "Required";
    }
    

    # Bail out of we already have errors:
    return $errors if keys %$errors;
    

    # See if the user already exists:
    if( App::db::user->count_search( email => $Form->{email} ) ) {
      $errors->{email} = "Already in use";
    }
    

      # Errors or not?:
      keys %$errors ? return $errors : return;
    }
    

    1;# return true:

File: `htdocs/profile.asp`

    <%@ Page UseMasterPage="/masters/global.asp" %>
    

    <asp:Content PlaceHolderID="meta_title">My Profile</asp:Content>
    

    <asp:Content PlaceHolderID="headline">My Profile</asp:Content>
    

    <asp:Content PlaceHolderID="main_content">
    <%
      if( my $msg = $Session->{msg} ) {
    %>
      <div class="message"><%= $msg %></div>
    <%
      }# end if()
    %>
    

    <%
      # Get our $user:
      use App::db::user;
      my $user = App::db::user->retrieve( $Session->{user_id} );
    %>
    

    <div style="float: left; width: 40%; border-right: solid 1px #000;">
      <h3>Incoming Messages</h3>
    <%
      foreach my $msg ( $user->messages_in(undef, { order_by => "created_on ASC"} ) ) {
    %>
      <div class="msg">
        <span class="from"><%= $msg->sender->email %></span> says:<br/>
        <div class="body"><%= $Server->HTMLEncode( $msg->body ) %></div>
        <span class="date"><%= $msg->created_on %></span>
      </div>
    <%
      }# end foreach()
    %>
    </div>
    

    <div style="float: right; width: 40%; border: dotted 1px #000;">
      <h3>Send New Message</h3>
      <form id="send_form" method="post" action="/handlers/app.send">
        <p>
          <label>Recipient:</label>
          <select name="to_user_id">
    <%
      my @users = App::db::user->search_where({
        user_id => {'!=' => $user->id }
      }, {
        order_by => "email"
      });
      foreach my $user ( @users ) {
    %>
            <option value="<%= $user->id %>"><%= $Server->HTMLEncode( $user->email ) %></option>
    <%
      }# end foreach()
    %>
          </select>