Mojolicious::Plugin::Moai - Mojolicious UI components using modern UI libraries
version 0.006
use Mojolicious::Lite;
plugin Moai => 'Bootstrap4'; # or 'Bulma'
app->start;
__DATA__
@@ list.html.ep
%= include 'moai/lib'
%= include 'moai/table', items => \@items, columns => [qw( id name )]
%= include 'moai/pager', current_page => 1, total_pages => 5
This plugin provides some common UI components using a couple different popular UI libraries.
These components are designed to integrate seamlessly with Yancy, Mojolicious::Plugin::DBIC, and Mojolicious::Plugin::SQL.
The Test::Mojo::Role::Moai library is provided to help test the Moai components. It also works without Moai, allowing you to test any website.
These libraries are not included and the desired version should be added to your layout templates. To add your library using a CDN, see "moai/lib", below.
Widgets are snippets that you can include in your templates using the include helper.
<%= include 'moai/pager',
current_page => param( 'page' ),
total_pages => $total_pages,
%>
A pagination control. Will display previous and next buttons along with individual page buttons.
Also comes in a mini
variant in moai/pager/mini
that has just
previous/next buttons.
-
current_page
The current page number. Defaults to the value of the
page
parameter. -
total_pages
The total number of pages. Required.
-
page_param
The name of the parameter to use for the current page. Defaults to
page
. -
id
An ID to add to the pager
<%= include 'moai/table',
items => [
{ id => 1, name => 'Doug' },
],
columns => [
{ key => 'id', title => 'ID' },
{ key => 'name', title => 'Name' },
],
%>
A table of items.
-
items
The items to display in the table. An arrayref of hashrefs.
-
columns
The columns to display, in order. An arrayref of hashrefs with the following keys:
-
key
The hash key in the item to use.
-
title
The text to display in the column heading
-
link_to
Add a link to the given named route. The route will be filled in by the current item, like
url_for $link_to => $item
. -
id
An ID to add to the table.
-
class
A hashref of additional classes to add to certain elements:
col
- Add these classes to every cell in the column
-
-
class
A hashref of additional classes to add to certain elements:
table
thead
wrapper
- Add a wrapper element with these classes
A horizontal navigation bar.
-
menu
An arrayref of menu items. Menu items are arrayrefs with two elements: label, and route name.
$app->routes->get( '/' )->name( 'index' ); $app->routes->get( '/blog' )->name( 'blog' ); $app->routes->get( '/about' )->name( 'about' ); <%= include 'moai/menu/navbar', menu => [ [ Home => 'index' ], [ Blog => 'blog' ], [ 'About Us' => 'about' ], ], %>
-
brand
A menu item for the "brand" section. An arrayref with two elements: a label, and a route name.
<%= include 'moai/menu/navbar', brand => [ 'Zooniverse' => 'main' ], %>
-
position
Position the navbar. Can be either
fixed-top
to affix the navbar to the top of the viewport orfixed-bottom
for the bottom of the viewport. If not set, the navbar will be a static element at the current location. -
id
An ID to add to the table.
-
class
A hashref of additional classes to add to certain elements:
navbar
- Add these classes to the<nav>
element
%= include 'moai/lib', version => '4.1.0';
Add the required stylesheet and JavaScript links for the current library
using a CDN. The stylesheets and JavaScript can be added separately
using moai/lib/stylesheet
and moai/lib/javascript
respectively.
-
version
The specific version of the library to use. Required.
-
Security
The CDN links should have full security hashes.
-
Accessibility Testing
Accessibility testing should be automated and applied to all supported libraries.
-
Internationalization
This library should use Mojolicious's
variant
feature to provide translations for every widget in every library. -
Add more widgets
There should be widgets for...
- other menus (vertical lists, dropdown buttons)
- dropdown menus
- forms and other items in the navbar (move the Form plugin from Yancy?)
- switched panels (tabs, accordion, slider)
- alerts (error, warning, info)
- menus (dropdown button, menu bar)
- popups (modal dialogs, tooltips, notifications)
- grid (maybe...)
-
Add more libraries
There should be support for...
- Bootstrap 3
- Material
Moai should support the same features for each library, allowing easy switching between them.
-
Add progressive enhancement
Some examples of progressive enhancement:
- The table widget could have sortable columns
- The table widget could use AJAX to to filter and paginate
- The pager widget could use AJAX to update a linked element
- The switched panel widgets could load their content lazily
-
Themes
Built-in selection of CDN-based themes for each library
-
Layouts
A customizable layout with good defaults.
-
Extra Classes
A standard way of adding extra classes to individual tags inside components. In addition to a string, we should also support a subref so that loops can apply classes to certain elements based on input criteria.
-
Documentation Sheet
Each supported library should come with a single page that demonstrates the various widgets and provides copy/paste code snippets to achieve that widget.
It would be amazing if there was a way to make one template apply to all supported libraries.
-
Content section overrides
We cannot, should not, must not make every little thing customizable or else our templates will be so complex as to be unmaintainable and unusable. We should instead make content sections that can be extended, like the
moai/table
template could have athead
section, atbody
section, and atbody.tr
section.A rule of thumb for adding a feature should be if it can be configured simply by a single string. The more complex the configuration needs to be, the more likely it should be customized using Mojolicious's template
extends
Test::Mojo::Role::Moai, Mojolicious::Guides::Rendering
Doug Bell preaction@cpan.org
This software is copyright (c) 2019 by Doug Bell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.