classparser.pm

该软件可以方便的把HTML网页解析成一棵Tree

B<IT WILL BE REMOVED IN A FUTURE RELEASE.>

=item C<check::>I<key>

Set the C<CHECKED> attribute of the current C<INPUT> element
for checkboxes and radio buttons only if a value is true.
The I<key> is the key into $this that contains the value to test.
This example selects the checkbox
only if C<$this-E<gt>S<{ sprinkles }>> is true.

    <INPUT TYPE="checkbox" NAME="Sprinkles"
     CLASS="check::sprinkles">Sprinkles

=item C<check_value::>I<key>

Set the C<CHECKED> attribute of the current C<INPUT> element
for checkboxes and radio buttons
depending upon the value of the C<VALUE> attribute.
The I<key> is the key into $this that contains the value to compare against.
This example selects the radio button only where the C<VALUE> is equal to
C<$this-E<gt>S<{ flavor_id }>>:

    <INPUT TYPE="radio" NAME="Flavor" VALUE="0"
     CLASS="check_value::flavor_id">Chocolate
    <INPUT TYPE="radio" NAME="Flavor" VALUE="1"
     CLASS="check_value::flavor_id">Strawberry
    <INPUT TYPE="radio" NAME="Flavor" VALUE="2"
     CLASS="check_value::flavor_id">Vanilla

=item C<href::>I<key>

This is a shorthand for C<sub::href::>I<key> since it occurs frequently.

=item C<href_id::>I<key>

This is a shorthand for C<sub_id::href::>I<key> since it occurs frequently.

B<THIS BUILT-IN CLASS IS DEPRECATED IN FAVOR OF >C<href_param>.
B<IT WILL BE REMOVED IN A FUTURE RELEASE.>

=item C<href_param::>I<key>

This is a shorthand for C<sub_param::href::>I<key> since it occurs frequently.

=item C<if::>I<key>

Emit the HTML up to and including the end tag for the current element
only if a value is true.
The I<key> is the key into $this that contains the value to be tested.
This example emits a table only if C<$this-E<gt>S<{ results }>> is true:

    <TABLE CLASS="if::results">
      ...
    </TABLE>

=item C<select::>I<key>

Set the C<SELECTED> attribute of the current C<OPTION> element
depending upon the value of the C<VALUE> attribute.
The I<key> is the key into $this that contains the value to compare against.
This example selects the option only where the C<VALUE> is equal to
C<$this-E<gt>S<{ flavor_id }>>:

    <SELECT NAME="Flavor">
      <OPTION CLASS="select::flavor_id" VALUE="0">Chocolate
      <OPTION CLASS="select::flavor_id" VALUE="1">Strawberry
      <OPTION CLASS="select::flavor_id" VALUE="2">Vanilla
    </SELECT>

(This is just like C<check_value>, but for C<OPTION> elements.)

=item C<sub::>I<attribute>C<::>I<key>

Substitute the value of an attribute of the current element.
The I<attribute> is the name of the HTML attribute
whose old value is to be substituted
and I<key> is the key into $this that contains the new value to be substituted.
This example substitutes the value of the C<TYPE> attribute
with the value of C<$this-E<gt>S<{ form_type }>>:

    <INPUT TYPE="radio" NAME="flavor_id" VALUE="1"
     CLASS="sub::type::form_type">

=item C<sub_id::>I<attribute>C<::>I<key>

Substitute the "ID part" of the value of an attribute of the current element.
The I<attribute> is the name of the HTML attribute
that contains the value whose "ID part" is to be substituted
and I<key> is the key into $this that contains the new ID to be substituted.
The "ID part" matches the pattern C<\d+> within the value,
i.e., a numeric ID.
This example substitutes the "1" in the value of the C<HREF> attribute
with the value of C<$this-E<gt>S<{ flavor_id }>>:

    <A HREF="/cgi-bin/get?id=1"
     CLASS="sub_id::href::flavor_id">Go</A>

B<THIS BUILT-IN CLASS IS DEPRECATED IN FAVOR OF >C<sub_param>.
B<IT WILL BE REMOVED IN A FUTURE RELEASE.>

=item C<sub_param::>I<attribute>C<::>I<key>

Substitute the "parameter" of the value of an attribute of the current element.
The I<attribute> is the name of the HTML attribute
that contains the value whose "parameter" is to be substituted
and I<key> is the key into $this
that contains the new parameter to be substituted.
The "parameter" matches the pattern I<key>C<=[^&=]+> within the value,
i.e., a name=value pair.
This allows multiple parameters to be substituted.
This example substitutes "joe" with the value of C<$this-E<gt>S<{ user }>>
and "1" with the value of C<$this-E<gt>S<{ pref_id }>>:

    <A HREF="/cgi-bin/get?user=joe&pref_id=1"
     CLASS="sub_param::href::user sub_param::href::pref_id">Go</A>

(See B<Multiple CLASS Values> below
for information about using multiple classes
in the value of a C<CLASS> attribute.)

=item C<text::>I<key>

Substitute the text of the first child node (which B<must> be a text node).
The I<key> is the key into $this that contains the text to be substituted.
This example substitutes the text "Tooty Fruity"
with the value of C<$this-E<gt>S<{ flavor_name }>>:

    <SPAN CLASS="text::flavor_name">Tooty Fruity</SPAN>

=item C<unless::>I<key>

Emit the HTML up to and including the end tag for the current elemment
only if a value is false.
(This is the opposite of C<if::>I<key>.)
The I<key> is the key into $this that contains the value to be tested.
(See the example for C<if::>I<key>.)

=item C<value::>I<key>

This is a shorthand for C<sub::value::>I<key> since it occurs frequently.

=item C<value_id::>I<key>

This is a shorthand for C<sub_id::value::>I<key> since it occurs frequently.

B<THIS BUILT-IN CLASS IS DEPRECATED IN FAVOR OF >C<value_param>.
B<IT WILL BE REMOVED IN A FUTURE RELEASE.>

=item C<value_param::>I<key>

This is a shorthand for C<sub_param::value::>I<key> since it occurs frequently.

=back

=head2 Multiple CLASS Values

The value of a C<CLASS> attribute may contain multiple classes
separated by whitespace.
When that is the case,
the function that each maps to is called in turn
and the return result is the logical-and of the functions.
Just as with Perl's C<&&> operator,
the first to return false "short-circuits" the evaluation.

However, that is true only when the functions are being called
for the start tag;
when being called for the end tag,
only the first function is called regardless of its return value.

In light of this, the first example can be rewritten as:

    <SELECT NAME="Flavors" CLASS="query_flavors">
      <OPTION CLASS="next_flavor value::flavor_id text::flavor_name"
       VALUE="0">Tooty Fruity
    </SELECT>

This would call C<next_flavor()> as before, but, if it returns true,
it would also call the remaining functions in turn.

The C<next_flavor()> function would also have to change to:

    sub next_flavor {
        my( $this, $node, $class, $is_end_tag ) = @_;
        return 1 if $is_end_tag;
        ( $this->{ flavor_id }, $this->{ flavor_name } ) =
		$this->{ sth }->fetchrow();
        unless ( $this->{ flavor_name } ) {
            # ... same as before ...
        }
        return 1;
    }

The switch to using
S<C<$this-E<gt>{ flavor_id }>>
and
S<C<$this-E<gt>{ flavor_name }>>
is necessary since all the built-in CLASSes use
S<C<$this-E<gt>{> I<key> C<}>>
for the values they use.

Because the built-in CLASSes are called to do the substitutions, the lines:

    $node->att( 'value', $flavor_id );
    $node->children()->[0]->text( $flavor_name );

that are present in the original version of C<next_flavor()> have been removed.

=head2 Improved Performance via C<bind_values()>

Although the following has more to do with DBI than C<ClassParser>,
it's presented here since it will improve the overall performance
when using the two together.

Generally, the DBI function C<bind_values()> should be used
when retrieving multiple tuples from a database query.
The C<query_flavors()> function can be rewritten to use it as follows:

    sub query_flavors {
        # ... same as before ...
        $this->{ sth }->bind_values(
            \$this->{ flavor_id }, \$this->{ flavor_name }
        );
        return 1;
    }

(See the DBI manual page for details.)
In this case, the result attributes B<must> to be bound to
S<C<$this-E<gt>{> I<key> C<}>>
so the values can be accessed by the C<next_flavor()> function
that can be rewritten as follows:

    sub next_flavor {
        my( $this, $node, $class, $is_end_tag ) = @_;
        return 1 if $is_end_tag;
        unless ( $this->{ sth }->fetch() ) {
            # ... same as before ...
        }
        return 1;
    }

Notice that C<fetchrow()> has been replaced by C<fetch()>
and that there are no assignments.

=head2 Handling GET Requests

Dynamically generated web pages often need parameters
to determine the content.
Such paramaters can be passed via the query string as in:

    http://www.icecream.com/flavor/detail.chtml?flavor_id=4

It's desirable to perform parameter validation
before displaying any part of a web page
because, if you start to display the page and discover an invalid parameter,
it's too late.
For example, the C<flavor_id> should be checked to ensure that it
refers to an existing flavor in the database:
if it doesn't, a redirection can be done to an error page.

For this to work, the code file B<must> define a method named C<get()>.
The implementation for this example shall be presented in stages.
The C<get()> method begins simply as:

    sub get {
        my $this = shift;

The code then prepares an SQL query via DBI:

        my $dbh = DBI->connect( 'DBI:mysql:ice_cream:localhost' );
        my $sth = $dbh->prepare( '
            SELECT 1
            FROM   flavors
            WHERE  flavor_id = ?
        ' );

C<ClassParser> stores a copy of the reference
to the current C<Apache::Request> object
into S<C<$this-E<gt>{ r }>>
from which query parameters can be extracted:

        my $r = $this->{ r };

(The variable name $r is used by convention.)
A check is made to ensure C<flavor_id> was given as a parameter
and, if so, an attempt is made to execute the query and fetch the result row.
If anything fails, the display of the web page is aborted
by returning the standard Apache C<NOT_FOUND> error:

        return NOT_FOUND unless
	    $r->param( 'flavor_id' ) &&
            $sth->execute( $r->param( 'flavor_id' ) ) &&
            $sth->fetchrow();

If all succeeds, then the function simply returns C<OK>:

        return OK;
    }

The return value B<must> be one of the C<Apache::Constants>.
If the value is C<OK>,
then the display of the web page proceeds normally;
if the value is anything other than C<OK>,
then the web page is not displayed.
In either case, that return value is passed back to Apache.

=head2 Handling POST Requests

Ordinarily, the C<ACTION> attribute in an HTML C<FORM> element
contains a URI pointing at a CGI script, e.g.:

    <FORM ACTION="/cgi-bin/process_my_data.cgi" METHOD="post">

After processing form data,
some web page needs to be displayed to the user.
The CGI could either emit the HTML for that page itself
or do a redirect to an existing web page.
A C<ClassParser>-parsed HTML file, however,
can handle C<POST> requests itself, e.g.:

    <FORM ACTION="/my.chtml" METHOD="post">

For this to work, it B<must> define a method named C<post()>
such as:

    sub post {
        my $this = shift;
	# do something yummy with $this->{ r }->param( 'Flavors' ) ...
	return OK;
    }

Similarly to the GET request case,
C<ClassParser> stores a copy of the reference
to the current C<Apache::Request> object
into S<C<$this-E<gt>{ r }>>
from which form parameters can be extracted.
In the example,
C<Flavors> is the value of the C<NAME> attribute of the C<SELECT> element,
so S<C<$this-E<gt>{ r }-E<gt>>C<param('Flavors')>>
is the value of the C<VALUE> attribute of the selected C<OPTION> element,
or the flavor ID.

Identically to the GET request case,
the return value B<must> be one of the C<Apache::Constants>.

=head2 Using a Different Code File via C<pm_uri>

As previously described,
every HTML file B<must> have an associated code file
having the same name as the HTML file
except with an extension of C<.pm> rather than C<.chtml>.
However, if a FORM parameter C<pm_uri> has a value either via a GET or POST
(but most often via a POST),
then B<that> code file will be used instead
to handle either the GET or POST request.
This allows you to consolidate form-processing code into a single code file.
The easiest way to specify a value for C<pm_uri>
is using a hidden C<INPUT> element:

    <INPUT TYPE="hidden" NAME="pm_uri" VALUE="other.pm">

=head2 Persistence

A code file is loaded, compiled once, and stored in memory.
Additionally,
a single object is created via the constructor and stored in memory also.
Both the code and the object are used for all subsequent HTTP requests.
The code is reloaded, recompiled, and stored, and a new object is created
only if the modification time of the code file
is later than the last time it was loaded.

This code/object persistence is done for efficiency/performance reasons only.
In particular, although an object is persistent across multiple HTTP requests,
data can not be stored in the object to implement anything like "sessions" for
users.
The reason is because Apache forks multiple child processes
and code and objects are persistent only within a B<single> child process
and not among them.
Hence, it is most likely the case that a given user's HTTP requests
will be handled by multiple Apache child processes.
(There are several techniques for doing "sessions": see [Stein], Chapter 5.)

=head2 Web Page Caching

C<ClassParser> sets the C<no_cache> flag for the Apache request.
Since web pages generated with C<ClassParser> are dynamic,
they should always reflect the latest information.

=head1 SEE ALSO

perl(1),
Apache::DBI(3),
Apache::Filter(3),
DBI(3),
HTML::Tree(3).

Apache Group.
I<Apache HTTPD Server Project>,
C<http://www.apache.org/>

Apache/Perl Integration Project,
I<mod_perl>,
C<http://perl.apache.org/>

Dave Raggett, et al.
"On SGML and HTML: SGML constructs used in HTML: Elements,"
I<HTML 4.0 Specification, section 3.2.1>,
World Wide Web Consortium,
April 1998.
C<http://www.w3.org/TR/PR-html40/intro/sgmltut.html#h-3.2.1>

--.
"The global structure of an HTML document: The document body:
Element identifiers: the C<id> and C<class> attributes,"
I<HTML 4.0 Specification, section 7.5.2>,
World Wide Web Consortium,
April 1998.
C<http://www.w3.org/TR/PR-html40/struct/global.html#h-7.5.2>

Lincoln Stein and Doug MacEachern.
I<Writing Apache Modules with Perl and C>,
O'Reilly & Associates, Inc., Sebastopol, CA,
1999.

Larry Wall, et al.
I<Programming Perl, 2nd ed.>,
O'Reilly & Associates, Inc., Sebastopol, CA,
1996.

=head1 AUTHOR

Paul J. Lucas <I<[e-mail]>>

=head1 CREDIT

As far as I know,
the technique for using pure HTML to generate dynamic web pages
using only C<CLASS> attributes
was invented by Erik Ostrom.

=cut