view release on metacpan or  search on metacpan

bin/mfile-www  view on Meta::CPAN

on the JavaScript side will translate to C<HTTP_ROOT/js/foobar/bazblat.js>

=item * in this particular case, of course, C<MFILE_APPNAME> is set to
C<mfile-www>

=item * persuades RequireJS via magic incantations to "play nice" together
with jQuery and QUnit

=item * by calling C<requirejs.config>, brings in site configuration
parameters needed on the JavaScript side so they can be accessed via the
C<cf> JS module

=item * passes control to the C<app/main> JS module

=back

What happens on the JavaScript side is described in a different section of
this documentation.


=head2 Derived distribution mode

Nice as the demo may be, the real purpose of L<App::MFILE::WWW> is to provide a
structure for writing "real" web frontends. For this purpose, C<bin/mfile-www>
is run in "derived distribution mode". 

Here is a "play-by-play" description of what happens in this scenario when
the startup script is run. Again, refer to the script source code
for better understanding:

=over

=item * C<$ddist> is set to the string given in the C<--ddist> option, e.g.
C<App-Dochazka-WWW> (or 'App::Dochazka::WWW' in which case it will be converted
to the correct, hyphen-separated format)

=item * C<$ddist_dir> is set to C<File::ShareDir::dist_dir( $ddist )>, i.e.
the derived distro sharedir (extending the above example, the distro sharedir
of L<App::Dochazka::WWW>)

=item * the presence of the C<--ddist> option triggers a special routine
whose purpose is to ensure that the derived distro exists and that its
sharedir is properly set up to work with L<App::MFILE::WWW>:

=over

=item * error exit if the distro referred to by the C<--ddist> option
doesn't exist 

=item * error exit if the distro lacks a sharedir

=item * C<css> and C<js/core> need to exist and be symlinks to the same
directories in the L<App::MFILE::WWW> sharedir. If this is not the
case, the script displays a message asking the user to re-run the
script as root with --init

=item * if already running as root, the symlinks are created and the
script displays a message asking to be re-run without --init as a normal user

=item * once the symlinks are in place, the script runs some sanity
checks (mainly verifying the existence of certain files in their
expected places)

=back

=item * the script calls the C<App::MFILE::WWW::init> routine, which loads
the configuration parameters stored in the following places:

=over

=item * the L<App::MFILE::WWW> distro sharedir (under C<config/WWW_Config.pm>)

=item * the derived distro sharedir (also under C<config/WWW_Config.pm>)

=item * finally and optionally, if a sitedir was specified on the
command line -- for example C<--sitedir=/etc/dochazka-www> --,
configuration parameters are loaded from a file C<WWW_SiteConfig.pm> in
that directory, overriding the defaults

=back

=item * the derived distro's configuration should override the
MFILE_APPNAME parameter -- in our example, it could be set to 'dochazka-www'

=item * also refer to the previous section to review the explanation of the
MFILE_WWW_LOG_FILE parameter

=item * the HTTP server is started by calling L<Plack::Runner>, and the
script reports to the user at what port number it is listening (5001 by
default)

=item * the HTTP server always interprets URL paths it receives relative to
its "root" (called C<HTTP_ROOT> for the purposes of this document), which
is set to the I<derived distro's sharedir>

=item * the rest of the description is the same as for L<Standalone
operation>

=back

=cut

# global variables
my $mfile_sharedir = File::ShareDir::dist_dir( 'App-MFILE-WWW' ); 
my $sharedir_writable = ( -w $mfile_sharedir ) || 0;
my ( $ddist_distro, $dispatch_module, $ddist_sharedir );


sub _get_sharedir {
    my ( $distro ) = @_;

    # for distro, we allow both formats My::Distro and My-Distro
    # distro might be just Foo, or Foo::Bar, or Foo-Bar
    my @tmp_c;
    if ( $distro =~ m/\:/ ) {
        @tmp_c = split( '::', $distro ); 
    } elsif ( $distro =~ m/\-/ ) {
        @tmp_c = split( '-', $distro );
    } else {
        @tmp_c = ( $distro );
    }