Permalink
Browse files

Add the first revision of the article written by Adam D.

  • Loading branch information...
1 parent 8aba32b commit 6cd64dd411207ccf9448ab532a2766d5caa7ecab @StylusEater committed Nov 24, 2012
Showing with 184 additions and 0 deletions.
  1. +184 −0 2012/articles/2012-12-nn.pod
@@ -0,0 +1,184 @@
+Title: Expanding Your CGI Parameters with CGI::Expand
+Topic: CGI::Expand
+
+=head1 CGI and parameters
+
+The Common Gateway Interface (CGI) restricts developers to structuring parameters
+into C<name=value> pairs. For instance, let's say you have a page (index.pl) that
+prints the pairs of parameters passed to the page. So when you access the page
+ through the GET method with the following Universal Resource Identifier (URI)
+C<index.pl?animal=camel&language=perl> you see:
+
+ #!code
+ animal: camel
+ language: perl
+
+Accessing the same page with the POST method through the form on the page, submits
+the values to the target on the server, in this case the page itself, prints:
+
+ #!code
+ animal: camel
+ language: perl
+
+The relevant code from the page, index.pl, that performs these operations looks like:
+
+ #!code
+ for my $param_name (param)
+ {
+ print "$param_name: ";
+ my @param_values = param($param_name);
+ print join(", ", @param_values), "<br />\n";
+ }
+
+C<param> is the method we're interested in discussing. When called without a parameter,
+C<param> or C<param()>, the method returns a list of parameter names. When accessed
+with a parameter, C<param("animal")>, the method returns the value of the parameter.
+
+But what happens when you want to give name and value pairs more structure? Building
+the logic to generate and consume the new structure would be one option. Another is
+to leverage an existing Comprehensive Perl Archive Network (CPAN) module called
@rjbs

rjbs Nov 24, 2012

Everybody who is reading this will know what the CPAN is. :-)

+C<CGI::Expand> that provides three utility methods to developers leveraging the module
+along with another component like C<CGI> that provides a compatible C<param> method.
+
+
+=head1 CGI::Expand and Parameters
+
+The methods provided by C<CGI::Expand> include C<expand_cgi>, C<expand_hash> and
+C<collapse_hash>. The expand and collapse utility methods provide the developer with
+the ability to build a hashref from a parameter string and collapse a hashref into a
+parameter string accordingly.
+
+In addition to being able to subclass the C<expand_cgi> method to change the default
+logic used to expand the parameter string, the behavior of the methods provided by
+C<CGI::Expand> can also be influenced by adjusting two class attributes, C<max_array>
+and C<separator> and/or two helper functions, C<split_name()> and C<join_name()>.
+
+The first of the two class attributes, C<max_array>, sets the size limit for arrays
@rjbs

rjbs Nov 24, 2012

I think you're getting ahead of yourself. You're explaining how to limit the size of arrays constructed before you've shown what the tool does or how arrays fit into it. The reader won't know what max_array or separator do, even though you're telling them, because they don't know what the tool does yet. I'd probably save these for later or, actually, just omit them entirely. They're not going to sell anybody on using the library, in the end.

+used in the hashref, which by default is set to 100. The second attribute, C<separator>,
+sets the character used to separate the packed parameter string, which by default is a
+period. Each of these options need to be overridden to change the default behavior of
+the C<expand_cgi> method.
+
+The first of the two helper functions, C<split_name(), implements the logic used to
+parse the parameter string and split it into segments while the second helper function,
+C<join_name()> implements the logic used to join the split segments back into a
+parameter string.
+
+## NOTE: Not sure if this is used properly??? I wanted to have an enumerated list with a
@rjbs

rjbs Nov 24, 2012

In this case, I'd probably just use the good old "=over" and "=item *" or possibly =head2 or =head3.

Those work better when you have a chunk of stuff for each item. The :list shortcut is better for very compact lists.

+## bullet point for each method
+=for :list
+
+C<expand_cgi()>
+This method takes a CGI object and returns a hashref for the expanded data structure.
+This becomes important when you build structure into your parameters like in the
+following example:
+
+ #!code
+ $parameters = 'skill.0=technology&skill.1=writing&language.0=perl&language.1=python
+ &language.2=php&language.3=c&language.4=java';
+
+ expanded with
+
+ $hash = expand_cgi( CGI->new($parameters) );
+
+ expands to
+
+ {
+ skill => ['technology', 'writing'],
+ language => ['perl', 'python', 'php', 'c', 'java']
+ }
+
+The above is a trivial example. More complex examples are given on the CPAN page for
+C<CGI::Expand> as listed in the references section. One can see how useful such structures
+might be when used with complex forms such as those used to select components from more
+and more restrictive lists like those found in preferences pages on shopping sites and
+job search sites.
+
+
+C<expand_hash()>
+The C<expand_hash()> method implements the logic used to expand the keys of the parameter
+hash. The CPAN page for C<CGI::Expand> provides a great example:
+
+ #!code
+ $args = expand_hash({ 'a.b.1' => [1,2] });
+
+ where the value of $args is
+
+ { a => { b => [undef, [1,2] ] } }
+
+
+
+C<collapse_hash()>
+The C<collapse_hash()> method implements the logic used to collapse the hashref into the
+parameter string. Again, the CPAN page for C<CGI::Expand> provides a great example:
+
+ #!code
+ $flat = collapse_hash({ a => { b => [undef, [1,2] ] } });
+
+ where the value of $flat is
+
+ { 'a.b.1.0' => 1, 'a.b.1.1' => 2 }
+
+
+=head1 Conclusion
+C<CGI::Expand> can make your life much easier by giving you a way to structure your parameters
+in a way you want while also giving you a way to embed meaning into the structure. These two
+benefits should reduce the amount of code you write which should reduce time to market and
+improve maintainability. Hopefully this article provided you with a quick introduction to
+C<CGI::Expand> and if you decide to use it in your code you should probably read about the
+C<EXCEPTIONS>, C<DEPRECATIONS> and C<LIMITATIONS> at the links provided in the C<References>
+section. Good luck with your code! and Happy Holidays!
+
+=head1 Full Code Example
+
+ #!code
+ #!/usr/bin/perl
+
+ use strict;
+ use warnings;
+
+ use CGI ':standard';
+
+ my $form = '
+ <p>Select your skill: </p>
+ <select name="skill">
+ <option name="technology">Technology</option>
+ <option name="writing">Writing</option>
+ </select>
+ <select name="software">
+ <option name="perl">Perl</option>
+ <option name="python">Python</option>
+ <option name="php">PHP</option>
+ <option name="c">C</option>
+ <option name="java">Java</option>
+ </select>
+ <input type="submit" value="SUBMIT" />
+ ';
+
+ my $query = CGI->new();
+ print $query->header();
+ print $query->start_html("Perl Advent 2012");
+ print $query->startform(-method => "POST", -target => "#");
+
+ print $form;
+
+ print $query->endform();
+
+ print "You submitted ... <br /><br />";
+ print "METHOD: " . request_method() . "<br />";
+ for my $param_name (param)
+ {
+ print "<strong>$param_name</strong> -> ";
+ my @param_values = param($param_name);
+ print join(", ", @param_values), "<br />\n";
+ }
+
+ print $query->end_html();
+
+# NOTE: Are these formatted properly?
@rjbs

rjbs Nov 24, 2012

You're missing the =for :list in front of it, which would need to come after a blank after the head1. That said, don't sweat this stuff. I can always futz with the formatting. Getting the content right is the interesting work. :-)

+=head1 References
+* L<CGI::Expand|http://search.cpan.org/dist/CGI-Expand/Expand.pm>
+* L<CGI::Expand README|http://cpansearch.perl.org/src/BOWMANBS/CGI-Expand-2.03/README>
+* L<CGI::Expand EXCEPTIONS|http://search.cpan.org/dist/CGI-Expand/Expand.pm#EXCEPTIONS>
+* L<CGI::Expand DEPRECATIONS|http://search.cpan.org/dist/CGI-Expand/Expand.pm#DEPRECATIONS>
+* L<CGI::Expand LIMITATIONS|http://search.cpan.org/dist/CGI-Expand/Expand.pm#LIMITATIONS>

0 comments on commit 6cd64dd

Please sign in to comment.