The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-Plugin-Obrazi-0.12
River stage zero No dependents
++
/ Mojolicious::Command::Author::generate::obrazi

NAME

Mojolicious::Command::Author::generate::obrazi - Обраꙁи for your site – a gallery generator command

SYNOPSIS

  Usage: APPLICATION generate obrazi [OPTIONS]

    ./myapp.pl generate obrazi --from --to
    mojo generate obrazi --from ~/Pictures/summer-2021 \
        --to /opt/myapp/public/summer-2021

    mojo generate obrazi --from ~/Pictures/summer-2021 \
        --to /opt/myapp/public/albums/summer-2021 -x 800x600 -s 96x96

  Options:
    -h, --help       Show this summary of available options
    -f, --from       Root of directory structure from which the images
                     will be taken. Defaults to ./.
        --to         Root directory where the gallery will be put. Defaults to ./.
    -x, --max        Maximal image dimesnions in pixels in format 'widthxheight'.
                     Defaults to 1000x1000.
    -s, --thumbs     Thumbnails maximal dimensions. Defaults to 100x100 pixels.
    -i, --index      Name of the CSV index file to be generated or read in the
                     --from directory.
    -t, --template   Path to template file. Defaults to embedded template
                     obrazi.html.ep.

DESCRIPTION

Mojolicious::Command::Author::generate::obrazi generates a gallery from a directory structure, containing images. The produced gallery is a static html file which content can be easily taken, modified, and embedded into any page.

In addition the command generates a csv file describing the images. This file can be edited. Titles and descriptions can be added for each image and then the command can be run again to regenerate the gallery with the new titles and descriptions.

The word обраꙁъ(singular) means face, image, picture, symbol, example, template, etc. in OCS/Old BG language. The name of the plugin is the plural variant in nominative case (обраꙁи).

WORKFLOW

    1. Images' owner and producer gives the direcory (probably zipped) to the
        command runner.
    2. The runner runs the command as shown in the SYNOPSIS.
    3. The runner gives the produced csv file to the images producer. Fixes
        problems with ICC profiles etc. Notifies the producer for eventual
        naming convetions, possible problems. The producer fills in the
        description and titles in the comfort of LibreOffice Calc or MS Excel
        and gives back the file to the command-runner. This may take some time.
    4. The runner runs again the command with the new csv file, reviews the
        produced file. Takes the HTML and puts it in a page on the Web.
    5. The images' owner/producer enjois the gallery, prise him/herself with it
        or goes back to the runner to report problems.
    6. DONE or go to some of the previous steps.

FEATURES

Recursively traverses subdirectories and scales images (four at a time) to given width and height and produces thumbnails for those images. Thumbnail sizes can also be set.

Produces an index CSV file which can be edited to add titles and descriptions for the images.

Produces an HTML file with fully functional lightbox-like gallery, implemented only using jQuery and CSS – no plugins. Left/right keyboard buttons navigation to next and previous image.

ATTRIBUTES

Mojolicious::Command::Author::generate::obrazi inherits all attributes from Mojolicious::Command and implements the following new ones.

csv_filename

    my $filename = $self->csv_filename; # index.csv
    my $обраꙁи = $self->csv_filename('gallery.csv');

The name of the CSV file which will be created in "from_dir". This file, after being edited and after the images are processed, will be copied together with the images to "to_dir". Defaults to index.csv. Can be passed on the command-line via the --index argument.

defaults

    my $defaults_hashref = $обраꙁи->defaults;
    $обраꙁи->defaults->{category_title} = 'Def. Cat. title';
    $обраꙁи->defaults->{category_description} = 'Def. Cat. description.';
    $обраꙁи->defaults->{image_title} = 'Def. Image Title';
    $обраꙁи->defaults->{image_description} = 'Def. Image description.';
    $обраꙁи->defaults->{author} = 'John Smith';

These values go to the folowing columns in the produced CSV file. title, description, author. They are supposed to be replaced by editing the produced file. TODO: Allow these to be passed on the command line via an argument --defaults.

description

  my $description = $обраꙁи->description;
  $self       = $обраꙁи->description('Foo');

Short description of this command, used for the application's command list.

files_per_subproc

    my $files_num = $обраꙁи->files_per_subproc;
    $self         = $обраꙁи->files_per_subproc(10);

Number of files to be processed by one subprocess. Defaults to int($number_of_images/$self->subprocs_num) +1. The last chunk of files is the remainder — usually smaller than the previous chunks.

from_dir

    $self = $обраꙁи->from_dir('./');
    my $root_folder_abs_path = $обраꙁи->from_dir;

Holds a Mojo::File instance - absolute path to the directory from which the pictures will be taken. This is where the CSV file describing the directory structure will be generated too. The value is taken from the commandline argument --from_dir. Defaults to ./ — current directory — where the command is executed.

imager

    my $img = $обраꙁи->imager->read(file=>'path/to/image.jpg')
        || die $обраꙁи->imager->errstr;

    my $self = $обраꙁи->imager(Imager->new);

An Imager instance.

log

    my $log = $self->log;
    my $self = $self->log(Mojo::Log->new)

A Mojo::Log instance. It is not the same as $self->app->log. Used to output info, warnings and errors in the terminal or the application log.

matrix

    my $matrix = $self->matrix;

    # add an image
    push @$matrix,
      [
      $category,               $path,
      $defaults->{image_title}, $defaults->{image_description},
      $defaults->{author},      $self->calculate_max_and_thumbs($path, $raw_path)
      ];

    # add a category
    push @$matrix, [
        $category, $path, "$defaults->{category_title} – $category",
        $defaults->{category_description}, $defaults->{author}, '', ''
    ];

    $matrix->each(sub{...});


    csv(in => $matrix->to_array, enc => 'UTF-8', out => \my $data, binary => 1, sep_char => ",");
    path($csv_filepath)->spurt($data);

A Mojo::Collection instance. First row contains the headers. This matrix is filled in while recursively searching in the "from_dir" for images. Then it is dumped into the index CSV file.

max

    my $max_sizes = $self->max; #{width => 1000, height => 1000}
    $self = $self->max(width => 1000, height => 1000);
    $self = $self->max('1000x1000');

A hash reference with keys width and height. Defaults to {width = 1000, height => 1000}>. Can be changed via the command line argument --max.

subprocs_num

    $self->subprocs_num; #4
    $self = $self->subprocs_num(5);

Integer, used to split the number of files found into equal chunks, each of which will be processed in a separate subprocess in parallel. Defaults to 4. See also "files_per_subproc".

template_file

    my $self = $self->template_file('path/to/template.html.ep');
    my $tpl  = $self->template_file;

Path to template file to be used for generating the HTML for the gallery. Defaults to embedded template obrazi.html.ep. Can be passed as argument on the command-line via --template.

thumbs

    my $thumbs_sizes = $self->thumbs; #{width => 1000, height => 1000}
    $self = $self->thumbs(width => 1000, height => 1000);
    $self = $self->thumbs('1000x1000');

A hash reference with keys width and height. Defaults to {width = 1000, height => 1000}>. Can be changed via the command line argument --thumbs.

to_dir

    $self->to_dir # $app/public
    $self = $self->to_dir('/some/folder')

A Mojo::File instance. Directory where the folder with the processed images will be put. Defaults to the public forlder of the current application. Can be changed via the command line argument --to_dir.

usage

  my $usage = $обраꙁи->usage;
  $self = $обраꙁи->usage('Foo');

Usage information for this command, used for the help screen.

METHODS

Mojolicious::Command::Author::generate::obrazi inherits all methods from Mojolicious::Command and implements the following new ones.

calculate_max_and_thumbs

    #   img_1000x1000.jpg, img_100x100.jpg
    my ($img_filename, $thumb_filename) = $self->calculate_max_and_thumbs($decoded_path, $raw_path);

Calculates the resized image dimensions according to the $self->max and $self->thumbs gallery contraints. Accepts the utf8 decoded path and the raw path to the file to be worked on. Returns two empty strings if there is error reading the image and warns about the error. Returns filenames for the resized image and the thumbnail image. See also "scale_calculate()" in Imager::Transformations.

run

  $makefile->run(@ARGV);

Run this command.

TEMPLATES

Mojolicious::Command::Author::generate::obrazi contains an embedded template obrazi.html.ep. TODO: Make the template inflatable.

SEE ALSO

Imager, Text::CSV_XS Mojolicious, Mojolicious::Guides, https://mojolicious.org,

jQuery – used for implementing the example embedded template,

Chota (A micro (~3kb) CSS framework) – also used for the example implementation.