=head1 NAME

Jifty::Manual::Glossary - The Jifty dictionary

=head1 GLOSSARY

We use words.  This is what they mean.

=over 4

=item action

An B<action> is a specifically designed RPC call that can do something to the
system, with any number of declared L</parameter>s.  At runtime, an action
can take L</argument>s, which it L</canonicalize>s, L</validate>s, and then
uses to do something useful.  Each action has a L</result>.  See
L<Jifty::Action> and L<Jifty::Manual::Actions>.

=item active

For an L</action> to run, it needs to be B<active>.  Most of the time, all
actions submitted are active, but it is possible to specify only a specific
action as active; any non-active actions are ignored.  See L<Jifty::Request>.

=item AJAX

An acronym standing for B<Asynchronous Javascript And XML>.  Though technically
incorrect, it is the buzzword that describes doing asynchronous requests to the
server while the user waits.  This can lead to very "dynamic" pages, as the
browser does not need to refresh the entire page to update a small section of
the screen.  In Jifty, the sections of the screen are called L</region>s.  See
L<Jifty::Web::PageRegion>.

=item argument

An B<argument> is a user-supplied input to fill in a L</parameter> in an
L</action>.  See L<Jifty::Action>.

=item canonicalize

To turn an L</argument> into a more standard form.  For instance, a
canonicalizer could translate a user-typed date into a date object or a
SQL-formatted date string.  See L<Jifty::Action>.

=item collection

A B</collection> is a class representing all or a subset of the records stored in the database regarding a particular L</model>. See L<Jifty::Collection>.

=item constructor

A property of a L</parameter>; the action B<must> have an argument value for
this parameter in order to be constructed.  This is different from
L</mandatory>, in that the user can leave mandatory fields empty.  For
instance, the C<id> of a L<Jifty::Action::Record::Update> is a constructor.
See L<Jifty::Action>.

=item continuation

A concept stolen from Lisp, Scheme, Smalltalk, and Perl 6.  The continuation of
any particular piece of code is the deferred operations that care about the
return value at that point.  In the context of Jifty, a continuation is a
deferred L</request> that may pull L</argument>s and the like from the
L</result>s of the current request.  Continuations can be arbitrarily nested,
so they are often useful to keep track of tangents that the user went on.  See
L<Jifty::Continuation>.

=item database version

The B<database version> is the L</schema version> last installed or updated in the application's database. In general, the database version will always match the schema version. The exception is when Jifty is updated to a new schema version, your application updates to a new schema version, or a plugin updates to a new schema version. When this happens, you must L</update> your database so that the database versions and schema versions match before running your application.

=item form field

A widget which the browser renders.  These are generally useful to ask the user
for a value for an L</argument> to an L</action>.  See
L<Jifty::Web::Form::Field>.

=item fragment

A section of HTML (at present, a Mason component) contained in a L</region>.
Fragments are a kind of standalone Mason component which the browser can request
individually.  Because of this, they can only take strings and scalars as
arguments, not references or objects!

=item element

A Mason component used by one or more other pages, which is not a whole page of
itself. As opposed to L<fragments|/fragment> C<elements> are strictly internal,
and never visible to the outside world by themselves. Elements typically live
under a path beginning with or containing '/_elements'. This, and the whole idea
of an element is strictly convention, but Jifty contains elements for things
like page headers, menus, and showing keybindings out of the box to make your
life easier.

=item mandatory

A property of a L</parameter>; the user must enter a value for the action to
validate.  This is the simplest level of L<validation|/validate>.

=item model

Jifty uses L<Jifty::DBI> to store its data (though might use other storage tools at some later time). The B<model> defines the L</schema> and provides a package for creating, reading, updating, and deleting records stored in the database. The model is generally a subclass of L<Jifty::Record>. Access multiple items from a model is performed through a L</collection>.

=item moniker

Every instance of a L<Jifty::Action> has a B<moniker>.  Monikers
serve as identifiers for actions, to associate arguments with actions
and to access specific actions "by name".  Monikers need not be
globally unique, but they must be unique within a single request.
Monikers have no semantic meaning. See L<Jifty::Action/monikers>

A moniker is an arbitrary-length nonempty string containing no
semicolons. It may not begin with a digit.

=item parameter

A B<parameter> is a named parameter to an L</action>.  Jifty generally renders
these on the screen as L</form field>s.  See L<Jifty::Param> and
L<Jifty::Param::Schema>.

=item region

An area of the page which JavaScript can replace.  The content in the region is
a L</fragment>.  Think of the region as the box and the fragment as the content
in the box.  See L<Jifty::PageRegion>.

=item request

A single query which lists L</action>s to run, together with a page or list of
L</fragment>s to return.  This most often comes from the browser as query
parameters, but may come from other sources as a L<JSON> or L<YAML> POST
request.  The answer to a request is a L</response>.  See L<Jifty::Request>.

=item response

The answer to a L</request>, it contains a L</result> for every action that
ran.  See L<Jifty::Response>.

=item result

The answer to a L</action>, it contains information about if the action was a
success or failure, and further detail about why or how.  It can also contain
arbitrary "content".  See L<Jifty::Result>.

=item return

After performing a L</tangent> a user may perform a L</return> to invoke the L</continuation> created by the original tangent.

=item schema

The B<schema> for a L</model> represents the structure of the data stored in an individual item in that model's L</collection>. See L<Jifty::DBI::Schema>.

=item schema version

The B<schema version> is a number in L<version> object used to determine which L</database version> your application code is expecting to use. There are three places where the schema version is important: 

=over

=item 1.

I<Jifty application version>. The Jifty application stores some details in the database.

=item 2.

I<Your database version>. Your application keeps a database version recorded in the configuration. See L<Jifty::Config>.

=item 3.

I<Plugin versions>. Each plugin has a version associated with it affecting whatever C</model>s it uses.

=back 

If any of these versions differs from their respective L</database version>s, then you need to run the L<Jifty::Script::Schema|schema setup script> to L</upgrade> to the latest schema version. 

Contrast with L</database version>.

=item sticky

A property of L</form field>s.  If a field is "sticky," values that the user
entered appear there again when the page is rendered again, avoiding making the
user type them again.  Most L</action>s have form fields which are sticky on
failure, so the user can update the information and try again.

=item tangent

A tangent is a link or redirect that causes Jifty to save the current state into a L</continuation> for a later L</return>. This operation is handy for situations when you want to jump to another page or form, but return to this page when the user is done with the "tangent" page. Because of the use of continuations, this can be especially handy because a user could go on multiple tangents and eventually return to the start.

=item upgrade

Generally, your Jifty application will change over time. Most of these changes will be simple changes to behavior or appearance. When changes are made to the L</schema> structure of your database, you may need to perform an B<upgrade>. An B<upgrade> is the process by which you rename columns, initialize data, or otherwise update information that needs to be updated when a change to the database needs to be made. See L<Jifty::Upgrade>, L<Jifty::Manual::Upgrading>, and L<Jifty::Script::Schema>.

=item validate

To check that the provided value of an L</argument> is a possible value for it
to have.  See L<Jifty::Web::Form::Field>.

=back

=cut
