/ 
Web-Components-0.12.6
River stage zero No dependents
/ Web::Components::Navigation

Name

Web::Components::Navigation - Context sensitive menu builder

Synopsis

use Web::Components::Navigation;

Description

Context sensitive menu builder

JavaScript

Files wcom-*.js are included in the share/js directory of the source tree. These will be installed to the File::ShareDir distribution level shared data files. Nothing further is done with these files. They should be concatenated in sort order by filename and the result placed under the webservers document root. Link to this from the web applications pages. Doing this is outside the scope of this distribution

Configuration and Environment

Defines the following attributes;

confirm_message

Immutable string. The default "Are you sure ?" message

container_class

Lazy string combining container_name and container_layout. This can be applied as a class name to the HTML container element by the application's page layout template

container_layout

A mutable string which defaults to centred. Used as a class name in the HTML it is also shared with the JS code

container_name

An immutable string which defaults to standard. Used as a class name in the HTML it is also shared with the JS code

container_tag

An immutable string which default to div. The HTML element to render

content_name

An immutable string which defaults to panel. Used as an id and a class name in the HTML it is also shared with the JS code

context

An immutable required weak reference to the context object

control_icon

An immutable string which defaults to user-settings. The name of the symbol in the SVG icons file for the user settings menu

global

An immutable array reference with an empty default. Contains a list of action paths used to create the top level of the navigation menus. It is expected that this will be populated at object construction time

icons

A lazy string representation of a partial URI. This should point to an SVG file containing named symbols. Defaults to img/icons.svg

json_view

An immutable string which defaults to json. Stashed by finalise as the view which will serialise the response as JSON

A lazy string which defaults to either the value is the session if it exists or the string both. An enumerated type with values; both, icon, or text. Controls how the global menu display links

A optional lazy string representation of a partial URI with a null default. This should point to an image file containing the logo if one is required

media_break

An immutable positive integer with a default of 680 pixels. When the display window's <innerWidth> drop below this (due to a resize event) link_display is set to icon which reduces the display width requirement

A lazy string which defaults to header. Can be set to sidebar. Effects where the navigation menus are rendered

message_action

An immutable string which defaults to api/navigation_messages. This is the action path for the API call that the message object in the JS will make to collect messages

messages

An immutable hash reference with an empty default. The attributes are used to configure the JS message collection and display code. Attributes are;

buffer-limit

Maximum number of messages to buffer. Defaults to 3

display-time

How long in seconds to display each message for. Defaults to 20 seconds

model

An immutable required object reference to the model component that is handling the current request

title

An immutable string which defaults to null. If set will be displayed as the application title along with the logo in the page header

title_abbrev

An immutable string which defaults to Nav. Used to set the pages title attribute in the HTML head. This is used in turn is used by the browser to create history links (the back button). Would set this from configuration to the abbreviation for the application

title_entry

A lazy string. The default constructor sets it to the current pages navigation label. This is appended to title_abbrev to form the labels in the browser history

Subroutines/Methods

Defines the following methods;

BUILDARGS

Wraps around the constructor call. If the context object has a reference to the config object which has a reference to a navigation attribute, then that hash reference is merged into the attributes passed to the constructor

crud
$self = $self->crud($moniker, $existing_id, $create_id);

A convenience method which calls item up to four times. If create_id is passed item is called with an action path of moniker/create. The existing_id is required and item is called three times with the action paths; moniker/delete, moniker/edit and moniker/view

finalise

Populates the stash with the data that represents the menu which will be serialised to JSON

finalise_script_request

If is_script_request is true then stash an OK HTTP return code. When using JS navigation all HTTP responses must be OK or the browser (which sniffs the fetch responses) will automatically navigate

is_script_request

Returns true if the request has come from the JS in the browser

item
$self = $self->item('action path', $args, $params);
$self = $self->item(formpost, 'action path', $args, $params);

The first example will add a single link to the current list. The display text is set by the Nav subroutine attribute of the endpoint, the href is supplied by context uri_for_action

In the second example formpost is imported from Web::Components::Util and causes the rendered menu item to be a form with a button on it (it is expected that this will be styled like a link). This is used for delete operations since we don't do deletes with a GET

list
$self = $self->list('list name', 'optional title');

Sets the current list to the name provided. If this list does not exist it is created. Once a list has been created item is called to add entries to it

$self = $self->menu('list name');

If the named list exists add it to the current list. This is how you created nested lists

render

Returns the HTML for inclusion on the web page

Diagnostics

None

Dependencies

Moo

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=Web-Components. Patches are welcome

Acknowledgements

Larry Wall - For the Perl programming language

Author

Peter Flanigan, <pjfl@cpan.org>

License and Copyright

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