Name

    Data::CloudWeights - Calculate values for an HTML tag cloud

Version

    Describes version v0.15.$Rev: 1 $ of Data::CloudWeights

Synopsis

       use Data::CloudWeights;
    
       # Create a new cloud
       my $cloud = Data::CloudWeights->new( \%cfg );
    
       # Add one or more tags to the cloud
       $cloud->add( $tag, $count, $value );
    
       # Calculate the tag cloud values
       my $nimbus = $cloud->formation;

Description

    Each tag added to the cloud has a unique name to identify it, a count
    which represents the size of the tag and a value that is associated
    with the tag. The reference returned by $cloud->formation() is a list
    of hash refs, one hash ref per tag. In addition to the input parameters
    each hash ref contains the scaled size, the percentage of total and a
    colour value in the range hot to cold.

    The cloud typically displays the tag name and count in the calculated
    colour with a font size set equal to the scaled value in the result

Configuration and Environment

    Attributes defined by this class:

    cold_colour

      The six character hex colour for the smallest count in the cloud.
      Defaults to #0000FF (blue)

    colour_pallet

      An array ref of hex colour values. If the cold_colour attribute is
      set to null then the colour values from the pallet are used instead
      of calculating the colour value from the scaled count. Defaults to
      twelve values that give an even transition from blue to red

    decimal_places

      The number of decimal places returned in the size attribute. Defaults
      to 2. With the default values for high and low this lets you set the
      tags font size in ems. If set to 0 and the high/low values suitably
      changed tag font size can be set in pixies

    hot_colour

      The six character hex colour for the highest count in the cloud.
      Defaults to #FF0000 (red)

    limit

      Limits the size of the returned list. Defaults to zero, no limit

    max_count

      The largest count in the cloud

    max_size

      The upper boundary value to which the highest count in the cloud is
      scaled. Defaults to 3.0 (ems)

    min_count

      The smallest count in the cloud

    min_size

      The lower boundary value to which the smallest count in the cloud is
      scaled. Defaults to 1.0 (ems)

    sort_field

      Select the field to sort the output by. Values are; tag, count or
      value. If set to undef the output order will be the same as the order
      of the calls to add. If set to a code ref it will be called as a sort
      comparison subroutine and passed two tag references whose keys are
      values listed above

    sort_order

      Either asc for ascending or desc for descending sort order

    sort_type

      Either alpha to use the cmp operator or numeric to use the <=>
      operator in sorting comparisons

    total_count

      The total count of all tags in the cloud

Subroutines/Methods

 new

       $cloud = Data::CloudWeights->new( [{] attr => value, ... [}] )

    This is a class method, the constructor for Data::CloudWeights. Options
    are passed as either a list of keyword value pairs or a hash ref

 BUILD

    If the hot_colour or cold_colour attributes are undefined a discreet
    colour value will be selected from the 'pallet' instead of calculating
    it using Color::Spectrum

 add

       $cloud->add( $name, $count, $value );

    Adds the tag name, count, and value triple to the cloud. The formation
    method returns a ref to an array of hash refs. Each hash ref contains
    one of these triples and the calculated attributes. The value argument
    is optional. Passing a count of zero will do nothing but returns the
    current cumulative total count for this tag name

 formation

       $cloud->formation();

    Return a ref to an array of hash refs. The attributes of each hash ref
    are:

  colour

    Calculated or dereferenced via the pallet, this is the hex colour
    string for this tag

  count

    The supplied size for this tag. Multiple calls to the add method for
    the same tag cause these counts to accumulate

  percent

    The percentage of the total count that this tag represents

  size

    The count scaled to a value between max_size and min_size

  tag

    The supplied name for this tag

  value

    The supplied value for this tag. This is usually an URI but can be any
    scalar. If multiple calls to add the same tag were made this will be an
    array ref containing each of the passed values

Diagnostics

    None

Acknowledgements

    Originally WWW::CloudCreator

      This did not let me calculate font sizes in ems

    HTML::TagCloud::Sortable

      I lifted the sorting code from here

    Color::Spectrum

      I copied the colour value manipulation code from here after this
      distribution started failing tests on 5.18

Dependencies

    Moo

    Type::Tiny

Incompatibilities

    There are no known incompatibilities in this module

Bugs and Limitations

    There are no known bugs in this module. Please report problems to the
    address below. Patches are welcome

Author

    Peter Flanigan, <pjfl@cpan.org>

License and Copyright

    Copyright (c) 2015 Peter Flanigan. All rights reserved

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. See perlartistic

    This program is distributed in the hope that it will be useful, but
    WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE