Name

HTML::StateTable - Displays tables from DBIC resultsets

Synopsis

use HTML::StateTable;

Description

A rich description of the required table is serialised to the browser via the data attributes of an empty div element. The JS running in the browser renders the table a fetches row data from the server which it also renders. User interactions with the table result in mutated query parameters on the request for row data to the server. New row data is rendered without any page reload

Configuration and Environment

Defines the following attributes;

• caption

  An immutable string with a null default. If set will display as the tables caption

• cell_class

  A lazy loadable class that defaults to HTML::StateTable::Cell

• columns

  A lazy privately mutable array reference of Column objects in sorted order

  Handles all_columns via array trait

• context

  An optional Context object passed to the constructor. If supplied it is expected to contain a request object. Some table roles require this to function

• has_context

  Predicate for the context attribute

• displayable_columns

  A lazy hash reference of booleans keyed by column name. Indicates that the column is displayable

  Handles is_displayable_column via the hash trait

• empty_text

  A string to display when there is no data

• is_filtered

  A mutable boolean that defaults to false. Is set to true by the Filterable and Searchable table roles

• max_page_size

  A non zero positive integer that defaults to 100. The hard limit on the page_size attribute

• name

  A non empty simple string that defaults to one supplied by the meta class

• no_count

  A boolean which defaults to false. If set to true will prevent the counting of database table rows which in turn leads to the non displaying of the page count and the last link

• page

  A mutable non zero positive integer that defaults to 1. The number of the current page of data being displayed

• page_control_location

  An immutable non empty simple string which defaults to 'BottomRight'. The location of the page control

• page_manager

  An immutable simple string with a null default. Name of the JS page management object

• page_size

  A mutable non zero positive integer which defaults to 20. The number of rows to be displayed per page. This is settable from preferences

• page_size_control_location

  An immutable non empty simple string which defaults to 'BottomLeft'. The location of the page size control

• pager

  The pager object on the prepared resultset

• paging

  A mutable boolean which default to true. If false paging is disabled and no limit is placed on the number of rows retrieved from the database

• prepared_resultset

  A required lazy ResultSet built from the resultset attribute. The builder method is build_prepared_resultset. The prepared resultset restricts the row retrieved from the database to those requested by the Searchable and Filterable table roles

• has_prepared_resultset

  Predicate for prepared_resultset

• render_style

  A mutable simple string which defaults to 'replace'. Used by the experimental animation feature to select which type of row replacement animation to use

• renderer

  The object used to render the table

• renderer_args

  A hash reference of arguments passed the renderer's constructor

• renderer_class

  A lazy loadable class. The class name of the renderer object

• request

  A lazy Request object supplied by the context

• resultset

  A DBIx::Class::ResultSet object

• row_class

  A lazy loadable class which defaults to HTML::StateTable::Row. The class name for the row object

• row_count

  The total row count as return by either the resultset pager object or the prepared resultset count depending on whether paging is enabled

• serialisable_columns

  A lazy hash reference of booleans keyed by column name. Indicates that the column is serialisable

  Handles is_serialisable_column via the hash trait

• sort_column_name

  A mutable simple string which defaults to the first sortable column name

• sort_desc

  A mutable boolean which defaults to false. If true the sort will be in descending order

• sortable

  A lazy boolean which is true if the number of sortable columns is greater than zero

• sortable_columns

  A lazy array reference of Column objects

• title_location

  Immutable string which defaults to inner. If set to outer causes the title and credit control divs to be rendered outside of the top and bottom control divs

• visisble_columns

  A lazy array reference of Column objects that are not hidden.

  Handles all_visible_columns via the array trait

Subroutines/Methods

Defines the following methods;

• BUILDARGS

  Modifies the method in the base class. Allow the renderer to be specified without a fully qualified package name

• BUILD

  Called after object instantiation it applies parameters from the query string in the request object if context has been provided

• add_role( $role_name, $class_name )

  Called by the applied table roles this method registers the role and it's class with the serialiser. Each table role is expected to implement a method called "serialise_<role_name>"

• apply_params

  If context is provided extracts query parameter values from the request and applies them to the table attributes

• build_prepared_resultset

  Applies column SQL, paging, and sorting to the supplied resultset

• get_displayable_columns

  Returns an array reference of displayable column objects

• get_serialisable_columns

  Returns an array reference of serialisable column objects

• next_result

  Call next on the resultset and returns the result

• next_row

  Call next_result to obtain the next result object which it uses to instantiate a row object which it returns

• param_value( $name )

  If context has been provided returns the named query parameter. Will look for "<table name>_<param name>" in the query parameters and return it if it exists. If not will return "<param name>" from the query parameters if that exists. If that does not exist then returns a null string

• reset_resultset

  Resets the resultset so that next can be called again

• serialiser( $moniker, \&writer, \%args )

  Returns the requested serialiser object. The moniker is the serialiser class without the prefix. The writer is a code reference that is called to write the serialised output. The args are passed to the constructor call for the serialiser object

• sort_column( $column_name )

  Accessor mutator for sort_column_name attribute. Returns the current sort column object

• sorted_columns( @columns )

  Returns the list of column objects sorted by their position attribute value

Diagnostics

None

Dependencies

See dist.ini for full list

• Moo
• Unexpected

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-StateTable. Patches are welcome

Acknowledgements

Larry Wall - For the Perl programming language

Author

Peter Flanigan, <pjfl@cpan.org>

License and Copyright

Copyright (c) 2023 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