add Plugin POD and knock back version to beta release
This commit is contained in:
Oliver Gorwits
@@ -1,4 +1,4 @@
|
||||
2.006000 -
|
||||
2.005000_001 - 2013-02-09
|
||||
|
||||
[NEW FEATURES]
|
||||
|
||||
|
||||
@@ -6,7 +6,6 @@ bin/netdisco-deploy
|
||||
bin/netdisco-web
|
||||
bin/netdisco-web-fg
|
||||
Changes
|
||||
DEVELOPING.pod
|
||||
inc/Module/Install.pm
|
||||
inc/Module/Install/Base.pm
|
||||
inc/Module/Install/Can.pm
|
||||
@@ -71,6 +70,7 @@ lib/App/Netdisco/DB/schema_versions/App-Netdisco-DB-2-PostgreSQL.sql
|
||||
lib/App/Netdisco/DB/schema_versions/App-Netdisco-DB-3-4-PostgreSQL.sql
|
||||
lib/App/Netdisco/DB/schema_versions/App-Netdisco-DB-3-PostgreSQL.sql
|
||||
lib/App/Netdisco/DB/schema_versions/App-Netdisco-DB-4-PostgreSQL.sql
|
||||
lib/App/Netdisco/Developing.pod
|
||||
lib/App/Netdisco/Util/Connect.pm
|
||||
lib/App/Netdisco/Util/DeviceProperties.pm
|
||||
lib/App/Netdisco/Util/Permissions.pm
|
||||
|
||||
@@ -51,4 +51,4 @@ resources:
|
||||
homepage: http://netdisco.org/
|
||||
license: http://opensource.org/licenses/bsd-license.php
|
||||
repository: git://netdisco.git.sourceforge.net/gitroot/netdisco/netdisco-ng
|
||||
version: 2.006000
|
||||
version: 2.005000_001
|
||||
|
||||
@@ -7,7 +7,7 @@ use 5.010_000;
|
||||
use File::ShareDir 'dist_dir';
|
||||
use Path::Class;
|
||||
|
||||
our $VERSION = '2.006000';
|
||||
our $VERSION = '2.005000_001';
|
||||
|
||||
BEGIN {
|
||||
if (not length ($ENV{DANCER_APPDIR} || '')
|
||||
@@ -145,12 +145,23 @@ Run the following command to start the job control daemon (port control, etc):
|
||||
You should (of course) avoid running this Netdisco daemon and the legacy
|
||||
daemon at the same time.
|
||||
|
||||
=head1 Upgrading
|
||||
|
||||
Simply install this module again, then upgrade the database schema:
|
||||
|
||||
~/bin/localenv cpanm --quiet --notest App::Netdisco
|
||||
DANCER_ENVDIR=~/environments ~/bin/localenv netdisco-deploy
|
||||
|
||||
=head1 Tips and Tricks
|
||||
|
||||
=head2 Searching
|
||||
|
||||
The main black navigation bar has a search box which is smart enough to work
|
||||
out what you're looking for in most cases. For example device names, node IP
|
||||
or MAC addreses, VLAN numbers, and so on.
|
||||
|
||||
=head2 SQL and HTTP Trace
|
||||
|
||||
For SQL debugging try the following commands:
|
||||
|
||||
DBIC_TRACE_PROFILE=console DBIC_TRACE=1 \
|
||||
@@ -159,9 +170,13 @@ For SQL debugging try the following commands:
|
||||
DBIC_TRACE_PROFILE=console DBIC_TRACE=1 \
|
||||
DANCER_ENVDIR=~/environments ~/bin/localenv netdisco-daemon-fg
|
||||
|
||||
=head2 Deployment
|
||||
|
||||
Other ways to run and host the web application can be found in the
|
||||
L<Dancer::Deployment> page. See also the L<plackup> documentation.
|
||||
|
||||
=head2 User Rights
|
||||
|
||||
With the default configuration user authentication is disabled and the default
|
||||
"guest" user has no special privilege. To grant port and device control rights
|
||||
to this user, create a row in the C<users> table of the Netdisco database with
|
||||
@@ -169,32 +184,33 @@ a username of C<guest> and the C<port_control> flag set to true:
|
||||
|
||||
netdisco=> insert into users (username, port_control) values ('guest', true);
|
||||
|
||||
=head1 Upgrading
|
||||
=head2 Database API
|
||||
|
||||
Simply install this module again, then upgrade the database schema:
|
||||
Bundled with this distribution is a L<DBIx::Class> layer for the Netdisco
|
||||
database. This abstracts away all the SQL into an elegant, re-usable OO
|
||||
interface. See the L<App::Netdisco::Developing> documentation for further
|
||||
information.
|
||||
|
||||
~/bin/localenv cpanm --quiet --notest App::Netdisco
|
||||
DANCER_ENVDIR=~/environments ~/bin/localenv netdisco-deploy
|
||||
=head2 Plugins
|
||||
|
||||
=head1 Future Work
|
||||
App::Netdisco includes a Plugin subsystem for building the web user interface.
|
||||
Items in the navigation bar and the tabs on pages are loaded as Plugins, and
|
||||
you have control over their appearance and ordering. See
|
||||
L<App::Netdisco::Web::Plugin> for further information.
|
||||
|
||||
Bundled with this app is a L<DBIx::Class> layer for the Netdisco database.
|
||||
This could be a starting point for an "official" DBIC layer. Helper functions
|
||||
and canned searches have been added to support the web interface.
|
||||
=head2 Developing
|
||||
|
||||
The intention is to support "plugins" for additonal features, most notably
|
||||
columns in the Device Port listing, but also new menu items and tabs. The
|
||||
design of this is sketched out but not implemented. The goal is to avoid
|
||||
patching core code to add localizations or less widely used features.
|
||||
Lots of information about the architecture of this application is contained
|
||||
within the L<App::Netdisco::Developing> documentation.
|
||||
|
||||
=head1 Caveats
|
||||
|
||||
Some sections are not yet implemented, e.g. the I<Device Module> tab.
|
||||
|
||||
Menu items on the main black navigation bar go nowhere, except Home.
|
||||
Some menu items on the main black navigation bar go nowhere.
|
||||
|
||||
None of the Reports yet exist (e.g. searching for wireless devices, or duplex
|
||||
mismatches). These might be implemented as a plugin bundle.
|
||||
mismatches). These will be implemented as a plugin bundle.
|
||||
|
||||
The Wireless, IP Phone and NetBIOS Node properies are not yet shown.
|
||||
|
||||
|
||||
@@ -248,10 +248,10 @@ This is a typical Template::Toolkit "wrapper" configuration, as noted by the
|
||||
C<[% content %]> call within C<main.tt> that loads the template you actually
|
||||
specified in your Dancer handler.
|
||||
|
||||
All templates (and Javascript and Stylesheets) are shipped in the Dancer
|
||||
distribution and located automatically by the application (using the
|
||||
environment variables which L<App::Netdisco> set up). The user doesn't have to
|
||||
copy or install any files.
|
||||
All templates (and Javascript and Stylesheets) are shipped in the
|
||||
L<App::Netdisco> distribution and located automatically by the application
|
||||
(using the environment variables which App::Netdisco set up). The user doesn't
|
||||
have to copy or install any files.
|
||||
|
||||
There's a template for the homepage called C<index.tt>, then separate
|
||||
templates for searching, displaying device details, and showing inventory.
|
||||
@@ -275,11 +275,11 @@ organised below C<share/views/ajax/...> in the distribution.
|
||||
|
||||
=head2 Stylesheets
|
||||
|
||||
The main style for Netdisco uses Twitter Bootstrap, which is a stylish modern
|
||||
library of styles and javascript used on many websites. It does a lot of heavy
|
||||
lifting, providing simple CSS classes for all of the standard web page
|
||||
furniture (forms, tables, etc). Check out the documetation at the Twitter
|
||||
Bootstrap web site for more information.
|
||||
The main style for Netdisco uses Twitter Bootstrap, which is a modern library
|
||||
of CSS and javascript used on many websites. It does a lot of heavy lifting,
|
||||
providing simple CSS classes for all of the standard web page furniture
|
||||
(forms, tables, etc). Check out the documetation at the Twitter Bootstrap web
|
||||
site for more information.
|
||||
|
||||
These stylesheets are of course customised with our own C<netdisco.css>. We
|
||||
try to name all CSS classes with a prefix "C<nd_>" so as to be distinct from
|
||||
@@ -57,3 +57,237 @@ register 'register_device_tab' => sub {
|
||||
|
||||
register_plugin;
|
||||
true;
|
||||
|
||||
=head1 NAME
|
||||
|
||||
App::Netdisco::Web::Plugin - Plugin subsystem for App::Netdisco Web UI components
|
||||
|
||||
=head1 Introduction
|
||||
|
||||
L<App::Netdisco>'s plugin subsystem allows developers to write and test web
|
||||
user interface (UI) components without needing to patch the main Netdisco
|
||||
application. It also allows the end-user more control over the UI components
|
||||
displayed in their browser.
|
||||
|
||||
So far, the following UI compoents are implemented as plugins:
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
Navigation Bar items (e.g. Inventory link)
|
||||
|
||||
=item *
|
||||
|
||||
Tabs for Search and Device pages
|
||||
|
||||
=back
|
||||
|
||||
In the future there will be other components supported, such as Reports.
|
||||
|
||||
This document explains first how to configure which plugins are loaded (useful
|
||||
for the end-user) and then also how to write and install your own plugins.
|
||||
|
||||
=head1 Application Configuration
|
||||
|
||||
In the main C<config.yml> file for App::Netdisco (located in C<share/...>)
|
||||
you'll find the C<web_plugins> configuration directive. This lists, in YAML
|
||||
format, a set of Perl module names (or partial names) which are the plugins to
|
||||
be loaded. For example:
|
||||
|
||||
web_plugins:
|
||||
- Inventory
|
||||
- Search::Device
|
||||
- Search::Node
|
||||
- Search::Port
|
||||
- Device::Details
|
||||
- Device::Ports
|
||||
|
||||
When the name is specified as above, App::Netdisco automatically prepends
|
||||
"C<App::Netdisco::Web::Plugin::>" to the name. This makes, for example,
|
||||
L<App::Netdisco::Web::Plugin::Inventory>. This is the module which is loaded
|
||||
to add a user interface component.
|
||||
|
||||
Such plugin modules can either ship with the App::Netdisco distribution
|
||||
itself, or be installed separately. Perl uses the standard C<@INC> path
|
||||
searching mechanism to load the plugin modules.
|
||||
|
||||
If an entry in the C<web_plugins> list starts with a "C<+>" (plus) sign then
|
||||
App::Netdisco attemps to load the module as-is, without prepending anything to
|
||||
the name. This allows you to have App::Netdiso web UI plugins in other
|
||||
namespaces:
|
||||
|
||||
web_plugins:
|
||||
- Inventory
|
||||
- Search::Device
|
||||
- Search::Node
|
||||
- Device::Details
|
||||
- Device::Ports
|
||||
- +My::Other::Netdisco::Web::Component
|
||||
|
||||
The order of the entries in C<web_plugins> is significant. Surprisingly
|
||||
enough, the modules are loaded in order. Therefore Navigation Bar items appear
|
||||
in the order listed, and Tabs appear on the Search and Device pages in the
|
||||
order listed.
|
||||
|
||||
The consequence of this is that if you want to change the order (or add or
|
||||
remove entries) then simply edit the C<web_plugins> setting. In fact, we
|
||||
recommend adding this setting to your C<< <environment>.yml >> file and
|
||||
leaving the C<config.yml> file alone. Your Environment's version will take
|
||||
prescedence.
|
||||
|
||||
Finally, if you want to add components without completely overriding the
|
||||
C<web_plugins> setting, use the C<extra_web_plugins> setting instead in your
|
||||
Environment configuration. Any Navigation Bar items or Page Tabs are added
|
||||
after those in C<web_plugins>.
|
||||
|
||||
=head1 Developing Plugins
|
||||
|
||||
A plugin is simply a Perl module which is loaded. Therefore it can do anything
|
||||
you like, but most usefully for the App::Netdisco web application, the module
|
||||
will install a L<Dancer> route handler subroutine, and link this to a web user
|
||||
interface (UI) component.
|
||||
|
||||
Explaining how to write Dancer route handlers is beyond the scope of this
|
||||
document, but by examining the source to the plugins in App::Netdisco you'll
|
||||
probably get enough of an idea to begin on your own.
|
||||
|
||||
App::Netdisco plugins should load the L<App::Netdisco::Web::Plugin> module.
|
||||
This exports a set of helper subroutines to register the new UI components.
|
||||
Here's the boilerplate code for our example plugin module:
|
||||
|
||||
package App::Netdisco::Web::Plugin::MyNewFeature
|
||||
|
||||
use Dancer ':syntax';
|
||||
use Dancer::Plugin::Ajax;
|
||||
use Dancer::Plugin::DBIC;
|
||||
|
||||
use App::Netdisco::Web::Plugin;
|
||||
|
||||
# plugin registration code goes here, ** see below **
|
||||
|
||||
# your Dancer route handler, for example:
|
||||
get '/mynewfeature' => sub {
|
||||
# ...lorem ipsum...
|
||||
};
|
||||
|
||||
true;
|
||||
|
||||
=head2 Navigation Bar items
|
||||
|
||||
These components appear in the black navigation bar at the top of each page,
|
||||
as individual items (i.e. not in a menu). The canonical example of this is the
|
||||
Inventory link.
|
||||
|
||||
To register an item for display in the navigation bar, use the following code:
|
||||
|
||||
register_navbar_item({
|
||||
id => 'newfeature',
|
||||
path => '/mynewfeature',
|
||||
label => 'My New Feature',
|
||||
});
|
||||
|
||||
This causes an item to appear in the Navigation Bar with a visible text of "My
|
||||
New Feature" which when clicked sends the user to the C</mynewfeature> page.
|
||||
Note that this won't work for any target link - the path must be an
|
||||
App::Netdisco Dancer route handler. Please bug the App::Netdisco devs if you
|
||||
want arbitrary links supported.
|
||||
|
||||
=head2 Search and Device page Tabs
|
||||
|
||||
These components appear as tabs in the interface when the user reaches the
|
||||
Search page or Device details page. If you add a new tab, remember that the
|
||||
C<package> name in the file should be C<...Plugin::Device::MyNewFeature> (i.e.
|
||||
within the Device namespace).
|
||||
|
||||
To register an item for display as a Search page Tab, use the following code:
|
||||
|
||||
register_search_tab({id => 'newfeature', label => 'My New Feature'});
|
||||
|
||||
This causes a tab to appear with the label "My New Feature". So how does
|
||||
App::Netdisco know what the link should be? Well, as the
|
||||
L<App::Netdisco::Developing> documentation says, tab content is retrieved by
|
||||
an AJAX call back to the web server. This uses a predictable URL path format:
|
||||
|
||||
/ajax/content/<search or device>/<feature ID>
|
||||
|
||||
For example:
|
||||
|
||||
/ajax/content/search/newfeature
|
||||
|
||||
Therefore your plugin module should look like the following:
|
||||
|
||||
ajax '/ajax/content/search/newfeature' => sub {
|
||||
# ...lorem ipsum...
|
||||
|
||||
content_type('text/html');
|
||||
# return some HTML content here, probably using a template
|
||||
};
|
||||
|
||||
If this all sounds a bit daunting, take a look at the
|
||||
L<App::Netdisco::Web::Plugin::Search::Port> module which is fairly
|
||||
straightforward.
|
||||
|
||||
To register an item for display as a Device page Tab, the only difference is
|
||||
the name of the registration helper sub:
|
||||
|
||||
register_device_tab({id => 'newfeature', label => 'My New Feature'});
|
||||
|
||||
=head1 Templates
|
||||
|
||||
All of Netdisco's web page templates are stashed away in its distribution,
|
||||
probably installed in your system's or user's Perl directory. It's not
|
||||
recommended that you mess about with these files.
|
||||
|
||||
So in order to replace a template with your own version, or to reference a
|
||||
template file of your own in your plugin, you need a new path.
|
||||
|
||||
TODO: this bit!
|
||||
|
||||
=head2 Template Variables
|
||||
|
||||
Some useful variables are made available in your templates automatically by
|
||||
App::Netdisco:
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<search_node>
|
||||
|
||||
A base url which links to the Node tab of the Search page, together with the
|
||||
correct default search options set.
|
||||
|
||||
=item C<search_device>
|
||||
|
||||
A base url which links to the Device tab of the Search page, together with the
|
||||
correct default search options set.
|
||||
|
||||
=item C<device_ports>
|
||||
|
||||
A base url which links to the Ports tab of the Device page, together with
|
||||
the correct default column view options set.
|
||||
|
||||
=item C<uri_base>
|
||||
|
||||
Used for linking to static content within App::Netdisco safely if the base of
|
||||
the app is relocated, for example:
|
||||
|
||||
<link rel="stylesheet" href="[% uri_base %]/css/toastr.css"/>
|
||||
|
||||
=item C<uri_for>
|
||||
|
||||
Simply the Dancer C<uri_for> method. Allows you to do things like this in the
|
||||
template safely if the base of the app is relocated:
|
||||
|
||||
<a href="[% uri_for('/search') %]" ...>
|
||||
|
||||
=item C<self_options>
|
||||
|
||||
Available in the Device tabs, use this if you need to refer back to the
|
||||
current page with some additional parameters, for example:
|
||||
|
||||
<a href="[% uri_for('/device', self_options) %]&foo=bar" ...>
|
||||
|
||||
=back
|
||||
|
||||
=cut
|
||||
|
||||
|
||||
Reference in New Issue
Block a user