[dancer-users] Dancer Advent Calendar 2015

[Sawyer X]

On Sat, Oct 24, 2015 at 1:16 AM, Warren Young <wyml at etr-usa.com> wrote:
> On Oct 23, 2015, at 2:38 PM, Sawyer X <xsawyerx at gmail.com> wrote:
>>
>> email back to the list (or to me) your suggestions.
>
> The generated dancer -a code and the examples mostly show simple cases which are fine starting points, but they don’t tell you how to scale the app if it starts getting large.  General Perl-in-the-large principles help, but there are aspects of how that interacts with Dancer that aren’t obvious.
>
> If you start with the generated code and extend it in the most straightforward manner, you end up with all your code in lib/App.pm, with a flat route definition set.  This is bad, and it is the problem I want to address.
>
> When you write a program with thousands of lines and a deep URL hierarchy, you start to want to break it up, but the current docs don’t really tell you how to do that sensibly.  Dancer is not a policy-free framework, which means that it not only doesn’t force you to do it the right way, it doesn’t even give hints about what the right way might be.

I generally agree that you need to take care when growing on how to
extend. Rather than because we're "policy-free" (I like the term), we
just haven't realized that we should (and if this is your point, I
agree with you) make an effort to document how we recommend doing it,
rather than just making it possible.

I wrote an article about the "appname" feature which helps with that,
and the "setup" method practice I have, but those probably haven't
done a good job at addressing the issue.

Having an article that says "here's how we recommend extending your
application" sounds like a worthwhile goal.

>
> It may be too much for a single article, but I would like to cover topics such as:
>
> 1. Nested route definitions:
>
>         # User management pages
>         prefix ‘/user’ => sub {
>             get  ‘/login’ => …
>             post ‘/logout’ => …
>         };
>
>         # Major user-visible web app feature for logged-in users
>         prefix ‘/feature’ => sub {
>             prefix ‘/record’ => sub {
>                 # Define RESTful CRUD API for /feature/record objects
>                 del  ‘/:id’ => …
>                 get  ‘/:id’ => …
>                 post ‘/’ => …
>                 put  ‘/’ => …
>             };
>         };
>
>         # An API for use by the site’s JS code and possibly third parties
>         prefix ‘/api’ => sub {
>             prefix ‘/something’ => …
>         };
>
> Not only does defining your URL hierarchy this way instead of in the flat way that is most obvious avoid a lot of redundancy (‘/feature/record/:id’), defining things this way often makes patterns jump out at you, allowing an improvement in the way you design your URL scheme.
>
> 2. Moving almost all code out of the generated lib/App.pm into other *.pm files in that directory, possibly nested into a directory hierarchy. (lib/App/Module.pm, etc.)  Naming schemes, how to call between modules, etc.
>
> 3. Given 1 and 2, how to shard the route definitions among lib/App/*.pm, so that each Perl module includes only the routes that it defines code to handle, rather than dumping the whole route definition into the main lib/App.pm file generated by dancer -a.
>
> 4. Given 1 and 2, how to name the content of the views directory.  (e.g. views/app/feature.tx or views/app/feature/page-fragment.tx)  Policy-heavy frameworks use the calling URL to work out where the template files are, but Dancer doesn’t enforce that.  Working out a good naming scheme is essential for maintainability.
>
> 5. Your ideas here!

I think this is a wonderful idea for not just a single article, but
multiple articles. Also, I think we can turn this into user
documentation article that stays with Dancer.

We've discussed at the conference having documentation that relates to
meta-topics. For example, one person has took it upon herself to try
and write some documentation on how to configure Dancer2 on Apache or
FCGI or how to transition from CGI to Dancer2. We can take an
additional direction of code on tips, recommendations, and so on. All
of these can be apart from the core documentation (could be in the
same distribution) and could be a good resource to point users to.

What do you think about making it a series of posts and merging them
into the core distribution under some class not under the manual, so
it could be distributed with Dancer?