=head1 NAME
 
RapidApp::Manual::TableSpec - RapidApp/DBIC metadata config options
 
=head1 DESCRIPTION
 
TableSpecs are RapidApp-specific metadata associated with DBIx::Class 
Result Classes which affect the behavior of automatically generated 
interfaces, interacting with the given source, throughout the RapidApp 
application.

TableSpecs also provide additional Row methods to Result Classes when 
loaded.

TableSpecs can be loaded via C<load_components>, however loading is
handled atomatically by higher-level APIs, namely RapidDbic. See
L<RapidApp::Manual::RapidDbic> for where and how to supply TableSpec
params.

=head1 SOURCE CONFIG PARAMS
 
=head2 title
 
Friendly title associated with the source in single row context (i.e. singular). This is a label
common to all the rows in the source. This is very often the same as the source name (the default),
such as 'Album', but could be more verbose, such as 'Music Album'.

=head2 title_multi
 
Friendly title associated with the source in multiple row, or set context (i.e. plural). This might
be 'Albums' or 'Music Albums' for the source 'Album'. This is used when showing lists of rows from
the given source.

Defaults to 'SOURCE_NAME Rows' (i.e. 'Album Rows').

=head2 iconCls
 
Icon associated with the source in single row context (i.e. singular). This should be a CSS class 
name in the same format as 'iconCls' in ExtJS. This is typically something like C<icon-apple> where
the associated class defines a background image. Expects a 16x16 icon.

This icon is displayed in various single-row contexts, such as in tab titles (for row pages) or 
inline in various places.

See L<RapidApp::Manual::Assets> for information on setup of icon assets and icon CSS classes in
RapidApp.

Defaults to 'ra-icon-pg'

=head2 multiIconCls
 
Icon associated with the source in multiple row, or set context (i.e. plural). This should be a CSS
class name in the same format as 'iconCls' in ExtJS. This is typically something like C<icon-apples>
where the associated class defines a background image. Expects a 16x16 icon.

See L<RapidApp::Manual::Assets> for information on setup of icon assets and icon CSS classes in
RapidApp.

Defaults to 'ra-icon-pg-multi'

=head2 display_column

Column used when displaying an individual row. Used when this source is the target of a single
relationship (i.e. belongs_to)

Defaults to the first primary key column, or the first column if there are no primary keys.

=head2 auto_editor_type

Default editor interface to use when selecting a row from this source (i.e. setting/changing a
single relationship, or belongs_to). Current supported values are C<grid>, C<combo>, C<dropdown>
 and C<custom>.

In RapidDbic this is set to C<custom> with an automatic config that attaches to the default grid for
the source. This is effectively the same as C<grid> but without configuring a separate RapidApp
module.

C<combo> and C<dropdown> set up a dropdown box with the items listed showing the value of the 
C<display_column> for each row. C<combo> also enables type-in search/filtering of the list (which
triggers a LIKE query on the display_column) while C<dropdown> does not. C<combo> is a nice 
alternative to C<grid> when there is a limited number of rows to select from and/or if text
searching on the display_column alone is sufficient to distinguish them between them. C<dropdown> 
is only suitable when both are the case, but is more than sufficient and optimal when it is (i.e.
for things like a 'status' table with just a handful of static rows).

C<grid> is by far the most powerful choice, but the tradeoff is that it is much slower to interact
with since it loads an entire grid interface in a pop-up window, instead of quick little inline
combo/dropdown box. But, this mode has all the same capabilities as any other grid, including not 
only the query tools like quick search and filters, but also the ability to select a row that 
doesn't already exist by adding it on-the-spot, which is not available in the other types.

Since the system doesn't have a reliable way of determining that C<combo>/C<dropdown> would be 
sufficient for a given source, the default is C<grid> which is the safest choice to ensure all 
needed options are available -- it is better to have them and not need them than need them
and not have them.


=head2 columns

HashRef of column names to TableSpec column configs. See COLUMN CONFIG PARAMS below.

=head1 COLUMN CONFIG PARAMS

These config settings apply to individual columns within the source. Most of the config options from
B<Ext.grid.Column> are supported here with some additional custom behaviors. Many of these options 
are automatically configured based on the column type from the schema.

=head2 header

Friendly name associated with the given column. Used in labels such as grid column headers.

Defaults to the column name. 

=head2 width

Default size in pixels. Default value based on the column type and length.

=head2 sortable

Boolean. Defines whether or not the column will be sortable in contexts such as
grids. Defaults to true.

=head2 no_column

Boolean. Hides the column from being shown/selected as a column in grid views. Does not affect other
contexts, such as Quick Search and MultiFilters (see C<no_quick_search>/C<no_multifilter> options).
Defaults to false.

=head2 no_quick_search

Boolean. Excludes the column from the Quick Search in grids. Defaults to false.

=head2 no_multifilter

Boolean. Excludes the column from the MultiFilter Search in grids (Filter button). Defaults to false.

=head2 no_summary

Boolean. Excludes the column from column summaries in grids. Defaults to false.

=head2 quick_search_exact_only

Boolean. Forces queries from the Quick Search to only use exact mode (C<'='> instead of C<LIKE %string%>
sub-string match) for the given column, regardless of the client-side Quick Search mode. This is 
already implied for numeric columns since it would never make sense to attempt to match them against
a sub-string.

=head2 allow_add

Boolean. Determines if an individual column is allowed to be used when adding new rows. This setting
is not relevant when the column is not already included by the C<creatable_colspec>. Defaults to true.

=head2 allow_edit

Boolean. Determines if an individual column is allowed to be changed when editing a row. This setting
is not relevant when the column is not already included by the C<updatable_colspec>, or when there is no
C<editor> defined. Defaults to true. 

=head2 allow_view

Boolean. Same as C<no_column> setting (but inversed), but for page context (i.e. single row) instead
of grid/multi context. Defaults to false when C<no_column> is set, but true when C<allow_edit> is
set. Different combinations of the 3 can be used to accomplish various scenarios. For example, these
settings will hide a column from grids but show it on the row page read-only:

  no_column  => 1,
  allow_edit => 0,
  allow_view => 1

=head2 editor

HashRef config of an ExtJS Field/Component. This is automatically setup based on column type, 
nullability, auto_editor_type for relationship columns, etc, but can be overridden here. If this 
is set to a false or empty value it will disable editing for the column across the board.

=head2 renderer

String or ArrayRef of Strings containing a valid JavaScript function name(s). The function should 
accept the value as the only argument and return the formatted value. (For example, 
C<'Ext.util.Format.usMoney'>). If multiple functions are supplied, the functions are chained, with 
the return value of the previous becoming the input to the next.

Again, this is automatically configured based on the column type info.

=head2 validator

JavaScript function name used to validate a value (form/input) for the column. See C<validator> 
in B<Ext.form.Field>.

=head2 auto_editor_params

Optional HashRef of config options to be merged into the config of the auto-generated editor for 
relationship columns. The kind of auto-generated editor depends on the value of C<auto_editor_type>
in the TableSpec config of the I<remote> source.

Only applies to single relationship columns - for expert/advanced usage only.

=head2 search_operator_strf

Optional sprintf format to apply to the operator used to query the column in quick search and
MultiFilters. This feature has been added specifically to support Type Casting in PostgreSQL.

For instance, special column types need to be "cast" in order for text/string queries to work:

  search_operator_strf => '::varchar %s'

The above setting will prefix the raw SQL operator used when querying the column with 
C<::varchar>. For example, this would change a WHEREclause that would normally be generated
like this:

  WHERE column LIKE 'foo%'

to be generated like this:

  WHERE column ::varchar LIKE 'foo%'

=head2 profiles

ArrayRef list of column profile names. Column profiles are macros/sets of column configs to apply 
multiple options at once. Many of these are automatically set according to the column type.

Column profiles are defined in L<RapidApp::TableSpec::Column::Profile>.

Currently available column profiles:

=over 4

=item * relcol

=item * nullable

=item * notnull

=item * number

=item * int

=item * bool

=item * text

=item * bigtext

=item * monotext

=item * blob

=item * html

=item * email

=item * datetime

=item * date

=item * money

=item * percent

=item * noadd

=item * noedit

=item * zipcode

=item * filesize

=item * autoinc

=item * img_blob

=item * virtual_source

=item * unsearchable

=item * cas_link

=item * soft_rel

=back

=head1 SEE ALSO

=over

=item *

L<RapidApp::Manual>

=item *

L<RapidApp::Manual::RapidDbic>

=back

=cut



