Acme-CPANModulesBundle-Import-PerlDancerAdvent-2018

 view release on metacpan or  search on metacpan

LICENSE  view on Meta::CPAN

    you changed the files and the date of any change; and

    b) cause the whole of any work that you distribute or publish, that
    in whole or in part contains the Program or any part thereof, either
    with or without modifications, to be licensed at no charge to all
    third parties under the terms of this General Public License (except
    that you may choose to grant warranty protection to some or all
    third parties, at your option).

    c) If the modified program normally reads commands interactively when
    run, you must cause it, when started running for such interactive use
    in the simplest and most usual way, to print or display an
    announcement including an appropriate copyright notice and a notice
    that there is no warranty (or else, saying that you provide a
    warranty) and that users may redistribute the program under these
    conditions, and telling the user how to view a copy of this General
    Public License.

    d) You may charge a fee for the physical act of transferring a
    copy, and you may at your option offer warranty protection in
    exchange for a fee.

LICENSE  view on Meta::CPAN

                     END OF TERMS AND CONDITIONS

        Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) 19yy  <name of author>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 1, or (at your option)
    any later version.

LICENSE  view on Meta::CPAN

    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA  02110-1301 USA


Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19xx name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your

devdata/http_advent.perldancer.org_2018_13  view on Meta::CPAN

by Dancer2 can get in the way. To get around this, veryrusty added a 
<code>no_default_middleware</code> configuration option to Dancer2's <i>config.yml</i> file
to keep your application from using the default bundling of Plack middleware.</p>
<h2><a name="better_documentation"></a>Better Documentation</h2>

<p>Several dozen bug fixes, clarifications, and other enhancements have been made
to the documentation, primarily by the Dancer2 community. As a result, the 
quality of existing docs has been greatly improved.</p>
<p>Several new examples have been added to both the Dancer2 distribution as well
as the tutorial.</p>
<p>Sawyer has started a significant project to rebuild the Dancer2 documentation 
from scratch. The current docs lack a good description of why Dancer does 
things a certain way, and doesn't give new users a good grounding in web 
application design to know how and why some things should be done the way
we've recommended. The new doc project aims to address this by detailing 
important concepts in a clear and simple way.</p>
<h2><a name="performance_improvements"></a>Performance Improvements</h2>

<p>Several important performance improvements were made to Dancer2, the most
important of which being the migration from <code>MooX::Types</code> to <code>Type::Tiny</code>. 
When <code>Type::Tiny::XS</code> is used, the boost is even more significant.</p>

devdata/http_advent.perldancer.org_2018_14  view on Meta::CPAN

</ul>
</div>


<div id="content">
<div class="pod-document"><h1><a name="dancer_survey_result_recap"></a>Dancer Survey Result Recap</h1>

<p>Well, it's been way longer than it should have been, but I wanted to provide some information about the results of the 2017 Dancer Survey.</p>
<h2><a name="statistics"></a>Statistics</h2>

<p>Let's start off with some overall statistics:</p>
<ul>
<li><a name="item_There_were_112_responses_to_the_survey"></a><b>There were 112 responses to the survey</b>
</li>
<li><a name="item_86_respondents__76_8___are_currently_using_Dancer_1_"></a><b>86 respondents (76.8%) are currently using Dancer(1)</b>
</li>
<li><a name="item_60_5__of_those_who_responded_are_using_Dancer2"></a><b>60.5% of those who responded are using Dancer2</b>
</li>
<li><a name="item_89_5__of_respondents_would_recommend_Dancer_to_another_Perl_developer__and_46_5__would_recommend_it_to_a_non_Perl_developer"></a><b>89.5% of respondents would recommend Dancer to another Perl developer, and 46.5% would recommend it ...
</li>
<li><a name="item_41_2__of_Dancer_1__users_are_planning_to_migrate_Dancer2"></a><b>41.2% of Dancer(1) users are planning to migrate Dancer2</b>

devdata/http_advent.perldancer.org_2018_14  view on Meta::CPAN

</li>
<li><a name="item_Configuration"></a><b>Configuration</b>
</li>
<li><a name="item_Be_more_community_active"></a><b>Be more community active</b>
<p>This last item refers to the core team being more active on Stack Overflow, Perl Monks, and the like. To the best of our abilities, we will
try to do so!</p>
</li>
</ul>
<p>This comment in particular stood out to me:</p>
<pre class="prettyprint">"More tutorials. Especially about deployment. I believe the greatest 
hurdle for new developers (as in new new, who start doing web stuff 
in Perl, or programming in general, with Dancer) is not to get started, 
but to get done. There is a lot of good content in all the major 
frameworks in the Perl ecosystem on how to build an application, but 
all of them lack in-depth tutorials with different alternatives for how 
to deploy them. This includes telling inexperienced users what hosting a 
web application means, what the different deployment types with PSGI do 
and which one to pick. I think having a really good guide would set 
Dancer apart from other frameworks."</pre>

<p>This is certainly one area we have set out to improve in the documentation.</p>
<h2><a name="cool_uses_of_dancer"></a>Cool uses of Dancer</h2>

devdata/http_advent.perldancer.org_2018_15  view on Meta::CPAN

</li>
</ul>
</div>


<div id="content">
<div class="pod-document"><h1><a name="dancer2__plugin__paginator___born_again"></a>Dancer2::Plugin::Paginator - Born Again</h1>

<h2><a name="history"></a>HISTORY</h2>

<p>I would call it re-birth. It all started during end of July 2017, I was going through the documentation of <a href="https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Plugins.pod">Dancer2::Plugins</a> and stumbled upon <a href="https://meta...
<h2><a name="rebirth"></a>REBIRTH</h2>

<p>Following the <a href="http://neilb.org/2014/01/31/adoption-request.html">advise</a> from Neil Bowers, I contacted the author <b>Blabos de Blebe</b> by email, if he was happy for me take it forward. He not only encouraged me but also gave me permi...
<h2><a name="challenge"></a>CHALLENGE</h2>

<p>After getting the push from the author, my first challenge was to make it compatible with <a href="https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Plugins.pod">Dancer2::Plugins</a>. Having done this with other plugins e.g. <a href="https...
<h2><a name="example"></a>EXAMPLE</h2>

<p>Let me show you an example as described in the official document for <a href="https://metacpan.org/release/Dancer2-Plugin-Paginator">Dancer2::Plugin::Paginator</a>.</p>
<pre class="prettyprint">use Dancer2;

devdata/http_advent.perldancer.org_2018_15  view on Meta::CPAN

   <br/>
   <hr/>
   <a href="/books/<% prev_l %>">[prev]</a>...<a href="/books/<% next_l %>">[next]</a>
   <hr/>
<% ELSE %>
   <ul><li><b>No book found.</b></li></ul>
&lt;% END %&gt;</pre>

<h2><a name="conclusion"></a>CONCLUSION</h2>

<p>This is all you need to get started. If you feel lucky, you can take a look at <a href="https://metacpan.org/pod/Paginator::Lite">Paginator::Lite</a> for more insights. Any questions/suggestions, feel free to get in touch mohammad.anwar@yahoo.com....
<h2><a name="author"></a>AUTHOR</h2>

<p>This article has been written by Mohammad S Anwar for the Perl Dancer Advent Calendar 2018.</p>
<h2><a name="copyright"></a>COPYRIGHT</h2>

<p>No copyright retained. Enjoy.</p>
<p>Mohammad S Anwar</p>
</div>

 <div id="disqus_thread"></div>

devdata/http_advent.perldancer.org_2018_16  view on Meta::CPAN

        $logger->error( $error );
    });
});</pre>

<p>To help us for future capacity planning, we want our workers to tell us if they are running at peak capacity, so log when this event occurs:</p>
<pre class="prettyprint">$worker-&gt;on( busy =&gt; sub( $worker ) {
    my $max = $worker-&gt;status-&gt;{ jobs };
    $logger-&gt;log( "$0: Running at capacity (performing $max jobs)." );
});</pre>

<p>Now, we apply the configuration (read below) to the worker. When the worker starts, it tells us information about how it was configured (this was really useful during development):</p>
<pre class="prettyprint">my $max_jobs = $hostconfig-&gt;{ max_children };
my @queues   = @{ $hostconfig-&gt;{ queues }};

if( $minion-&gt;has_invalid_queues( @queues ) ){
    print "Invalid job queues specified: " . join( ',', 
        $minion-&gt;get_invalid_queues( @queues ) );
    say ". Aborting!";
    exit 1;
}

devdata/http_advent.perldancer.org_2018_19  view on Meta::CPAN

log4perl.appender.LOG1.mode      = append
log4perl.appender.LOG1.layout    = Log::Log4perl::Layout::PatternLayout
log4perl.appender.LOG1.layout.ConversionPattern = %d %p %m %n</pre>

<p>The first one defines our root application logger. The first parameter after the equals sign says
what is the minimum level we should log. Since we are saying the minimum log level should be <code>DEBUG</code>,
any messages from Dancer2 itself, and anything logged at the <code>core</code> level will be ignored.</p>
<p>After the minimum log level is a comma-separated list of appenders to write to. For now, we will create a
single appender named <code>LOG1</code> (we will see how to add a second appender below).  This will write
to a file in the <i>logs/</i> directory named <i>mylog.log</i>, using the <a href="https://metacpan.org/pod/Log::Log4perl::Appender::File">Log::Log4perl::Appender::File</a>
appender. When the app is started, it will append to an existing log file of that name (or create the file
if necessary), and will write to it with a format specified by <a href="https://metacpan.org/pod/Log::Log4perl::Layout::PatternLayout">Log::Log4perl::Layout::PatternLayout</a>.</p>
<p>Each appender can have its own configuration directives. Please consult the pod for each appender for a list
of its configuration parameters.</p>
<p>Next, we have to tell our application that we are using <code>Dancer2::Logger::Log4perl</code> as our preferred logger.
Edit your <i>environments/development.yml</i> file, and comment out the <code>logger: "console"</code> line. Replace it
with the following:</p>
<pre class="prettyprint">logger: log4perl
log: core
engines:
   logger:

devdata/http_advent.perldancer.org_2018_19  view on Meta::CPAN

add another section to our <i>log4perl.conf</i> file:</p>
<pre class="prettyprint">log4perl.appender.SCREEN         = Log::Log4perl::Appender::Screen
log4perl.appender.SCREEN.stderr  = 0
log4perl.appender.SCREEN.layout  = Log::Log4perl::Layout::PatternLayout
log4perl.appender.SCREEN.layout.ConversionPattern = %m %n</pre>

<p>This creates another appender named <code>SCREEN</code>. We then need to tell our root logger to use this appender
as well:</p>
<pre class="prettyprint">log4perl.rootLogger = DEBUG, LOG1, SCREEN</pre>

<p>Now, restart your application, and visit a route that has logging installed, and you will see your log
message not only goes to the <i>logs/mylog.log</i> file, but also displays on the console running your
application. Easy!</p>
<h2><a name="some_gotchas"></a>Some Gotchas</h2>

<p>There are a couple of important nuances you should be aware of:</p>
<ul>
<li><a name="item_Environment_configuration_replaces_logging_configuration"></a><b>Environment configuration replaces logging configuration</b>
<p>If you put your logging configuration in <i>config.yml</i> rather than one of your environment-specific
configuration files (such as <i>environments/development.yml</i>), you stand a good chance of not using
the logging configuration you think you are using. The default configuration file for the development

devdata/http_advent.perldancer.org_2018_20  view on Meta::CPAN

<p>Authors of Dancer (and other) PSGI applications are probably accustomed to <a href="https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Manual.pod#TESTING">testing</a> with <a href="https://metacpan.org/pod/Plack::Test">Plack::Test</a>, and ...
<p>During advent last year, I wrote about <a href="https://mojolicious.org/perldoc/Test/Mojo">Test::Mojo</a>, showing the many easy and (dare I say) fun ways that you can use it to test your Mojolicious applications.
If you missed it, go <a href="https://mojolicious.io/blog/2017/12/09/day-9-the-best-way-to-test/">check it out</a>.</p>
<p>I expect there are at least a few of you out there who read that and think, "I'd love to use that, but I don't use Mojolicious!"; well, you're in luck!
With just a little role to bridge the gap, you can use Test::Mojo to test your PSGI applications too!</p>
<h2><a name="mounting_psgi_applications"></a>Mounting PSGI Applications</h2>

<p>Mojolicious itself doesn't use the <a href="https://metacpan.org/pod/PSGI">PSGI</a> protocol, owing to certain features that it doesn't provide and which are necessary for certain asynchronous operations.
That said, you can serve a Mojolicious application on a PSGI server by using <a href="https://mojolicious.org/perldoc/Mojo/Server/PSGI">Mojo::Server::PSGI</a>.
This Mojolicious-core module is automatically used for you when your Mojolicious-based app detects that it has started under a PSGI server (e.g. plackup or Starman).</p>
<p>While translating between a Mojo app and a PSGI server is core functionality, doing the opposite, translating between a PSGI app and a Mojolicious server (or app, as you'll see) is available as a third party module.
<a href="https://metacpan.org/pod/Mojolicious::Plugin::MountPSGI">Mojolicious::Plugin::MountPSGI</a>, as it's name implies, can mount a PSGI application into a Mojolicious-based one.
To do so, it builds a new, empty Mojolicious application that translates all requests to PSGI environments before dispatching to it as with any <a href="https://mojolicious.org/perldoc/Mojolicious/Plugin/Mount">mount</a>-ed application.</p>
<h2><a name="testing_using_test__mojo"></a>Testing using Test::Mojo</h2>

<p>Once you can do that, it is trivial to take a PSGI application, wrap it with MountPSGI, and set it as the application for use with Test::Mojo.
Still, to make it even easier, that has all been done for you in <a href="https://metacpan.org/pod/Test::Mojo::Role::PSGI">Test::Mojo::Role::PSGI</a>.</p>
<p>Like any <a href="https://mojolicious.io/blog/2017/12/13/day-13-more-about-roles/">Mojolicious Role</a>, we can use <code>with_roles</code> to create a (mostly anonymous) subclass with the role applied.
You can use the shortcut <code>+</code> to stand in for <code>Test::Mojo::Role::</code>.</p>
<pre class="prettyprint">use Test::Mojo;

devdata/http_advent.perldancer.org_2018_20  view on Meta::CPAN

any '/data' => sub {
  my $name = param('name') // 'world';
  send_as JSON => { hello => $name };
};

any '/html' => sub {
  my $name = param('name') // 'world';
  template 'hello' => { name => $name };
};

start;</pre>

<p>And the template (<code>hello.tt</code>) is</p>
<pre class="prettyprint">&lt;dl id="data"&gt;
  &lt;dt id="hello"&gt;hello&lt;/dt&gt;
  &lt;dd&gt;&lt;% name %&gt;&lt;/dd&gt;
&lt;/dl&gt;</pre>

<p>The <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl">dl</a>, <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt">dt</a> and <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd">dd</a> tags...
The HTML I've built, while nice for display isn't necessarily nice for querying programmatically, this is on purpose for the example.</p>
<h2><a name="the_tests"></a>The Tests</h2>

<p>Of course we could start the application with <a href="https://metacpan.org/pod/distribution/Plack/script/plackup">plackup</a> but that's not what we're trying to do.
I'll break the test script down a bit but if you want to see any of these files look at the <a href="https://github.com/MojoliciousDotIO/mojolicious.io/tree/master/blog/2018/12/20/testing-dancer/ex">blog repo</a> for a full listing.
Instead, let's load this into a test script.</p>
<pre class="prettyprint">use Mojo::Base -strict;</pre>

<p>Now if you aren't familiar, <code>use Mojo::Base -strict</code> is a quick way to say</p>
<pre class="prettyprint">use strict;
use warnings;
use utf8;
use IO::Handle;
use feature ':5.10';</pre>

devdata/http_advent.perldancer.org_2018_20  view on Meta::CPAN

done_testing;</pre>

<p>In this year's Mojolicious advent calendar, we've already seen <a href="https://mojolicious.io/blog/2018/12/05/compound-selectors/">some</a> <a href="https://mojolicious.io/blog/2018/12/14/a-practical-example-of-mojo-dom/">great</a> <a href="https...
The point remains however, testing HTML responses with CSS selectors allows you to make your tests targetd in a way that allows you to write more and better tests since you don't have to hack around extracting the bits you want.</p>
<h2><a name="testing_websockets"></a>Testing WebSockets</h2>

<p>Ok so that's great and all, but of course now it comes to the point you've all been waiting for: can you test WebSockets?
As Jason Crome mentioned in his <a href="http://advent.perldancer.org/2018/13">Twelve Days of Dancer</a> "State of Dancer", you can now dance with WebSockets via <a href="https://metacpan.org/pod/Dancer2::Plugin::WebSocket">Dancer2::Plugin::WebSocket...
<p>Well, so far not via the role I showed above.
It might be possible, but it would involve learning deep PSGI magick that I'm not sure I'm smart enough to do; patches welcome obviously :D.</p>
<p>Still I mentioned above that Test::Mojo can test anything it can access via an fully qualified URL, so let's just start up a server and test it!
I'll use the <a href="https://github.com/yanick/Dancer2-Plugin-WebSocket/tree/releases/example">example bundled with the plugin</a> for simplicty.</p>
<pre class="prettyprint">use Mojo::Base -strict;

use EV;
use Test::More;
use Test::Mojo;

use Twiggy::Server;
use Plack::Util;

devdata/http_advent.perldancer.org_2018_20  view on Meta::CPAN

my $url;
my $twiggy = Twiggy::Server->new(
  host => '127.0.0.1',
  server_ready => sub {
    my $args = shift;
    $url = "ws://$args->{host}:$args->{port}/ws";
  },
);
$twiggy-&gt;register_service($app);</pre>

<p>This starts Twiggy bound to localhost on a random port and starts the application using it.
When the server starts, the actual host and port are passed to the <code>server_ready</code> callback which we use to build the test url.
Now you just create a Test::Mojo instance as normal but this time open a websocket to the fully-qualified url that we built above.</p>
<pre class="prettyprint">my $t = Test::Mojo-&gt;new;

$t-&gt;websocket_ok($url)
  -&gt;send_ok({json =&gt; {hello =&gt; 'Dancer'}})
  -&gt;message_ok
  -&gt;json_message_is({hello =&gt; 'browser!'})
  -&gt;finish_ok;

done_testing;</pre>

devdata/http_advent.perldancer.org_2018_21  view on Meta::CPAN

<p>Why are CAPTCHAs bad for accessibility? I don't know about you, but even with good vision, I have a really 
hard time reading the text on many CAPTCHAs. I cannot begin to imagine how much more difficult it would be 
for a sighted user to attempt to read one. But many have audio, you say! Have you listened to a CAPTCHA
that's read to you? I am slightly hard of hearing, and I am unable to make them out many times. And some
clever developers have even found ways to circumvent the audio CAPTCHAs now. With more modern CAPTCHAs, users
with screen readers and other assistive devices/settings can often exhibit some of the same signs that bots
do, but unfortunately, you're not allowed to declare or prove your humanity - it's all up to a machine
learning algorithm, and once you're marked a bot, things are out of your control.</p>
<p>Even before I learned about the accessibility issues with CAPTCHAs, I knew adding one to my form was just
bad UX. It's shifting the burden of your problem onto your users. But when the only tool you think you possess 
is a hammer, all of your problems start to look a lot like nails.</p>
<p>The solution Job encouraged me to pursue was to have two form fields on my contact form that should never get 
filled in: one that is a standard form field, but using CSS, is visually hidden from the user, and the other is
to use a hidden form field. If any one of those fields is filled in, then you know you are dealing with a spambot,
and you can take the appropriate action.</p>
<h2><a name="backend_code"></a>Backend code</h2>

<p>Making this work in Dancer2 is really, really easy:</p>
<pre class="prettyprint">post '/contact' =&gt; sub {
    my $spam_1 = body_parameters-&gt;get( 'spam_one' );
    my $spam_2 = body_parameters-&gt;get( 'spam_two' );

devdata/http_advent.perldancer.org_2018_24  view on Meta::CPAN

changes for everyone!</p>
</li>
<li><a name="item_New_Website"></a><b>New Website</b>
<p>There's a lot of great information on the Dancer website, but it's looking tired. There's a 
lot of new information to be added, and with a fresh coat of paint, Dancer's website will be as
great as the software powering it.</p>
</li>
<li><a name="item_More_configuration_options"></a><b>More configuration options</b>
<p>Configuration in Dancer2 leaves a lot to be desired (and I'll admit that I am a big part of 
the reason for why that is). Look for an overhaul of the configuration system in 2019, which
starts with a barebones configuration system and allows for pluggable configuration engines
(much like loggers and sessions in Dancer2). Since we are dedicated to not breaking working 
code, all of the existing configuration logic would be packaged as a plugin and enabled
out of the box.</p>
</li>
<li><a name="item_Inline_parameter_type_checking"></a><b>Inline parameter type checking</b>
<p>Very similar in many ways to Sawyer's <a href="https://metacpan.org/pod/Dancer2::Plugin::ParamTypes">Dancer2::Plugin::ParamTypes</a>
plugin, but provided as core functionality. SysPete is actively developing a way to provide
(optional) type checking of parameters within the core of Dancer2.</p>
<p>In case you haven't read <a href="http://advent.perldancer.org/2018/22">Sawyer's article</a> 
about type checking parameters passed to your Dancer applications, I highly recommend