From 02b168ff9cb90f75f8b9143ea3c89ff2626bae10 Mon Sep 17 00:00:00 2001 From: Oliver Gorwits Date: Sat, 27 May 2017 10:04:05 +0100 Subject: [PATCH] update plugin-writing docs for site_local_files setting --- lib/App/Netdisco/Manual/Configuration.pod | 18 +++--- lib/App/Netdisco/Manual/Troubleshooting.pod | 7 +++ lib/App/Netdisco/Manual/WritingPlugins.pod | 70 +++++++++++++-------- 3 files changed, 60 insertions(+), 35 deletions(-) diff --git a/lib/App/Netdisco/Manual/Configuration.pod b/lib/App/Netdisco/Manual/Configuration.pod index 4aa37443..764cb21e 100644 --- a/lib/App/Netdisco/Manual/Configuration.pod +++ b/lib/App/Netdisco/Manual/Configuration.pod @@ -159,23 +159,21 @@ Value: List. Default: Empty List. Additional paths for L templates. Files in these paths will be loaded before (and hence override) any templates built in to Netdisco. -If you do want to copy and override a built in web template, then create the -directories necessary (such as "ajax" or "sidebar") in this path. - -Note that templates may need to have a further "C" subdirectory -created. +If you want to copy and override a built in web template, then create the +directories necessary (such as "ajax" or "sidebar") in this path. Note that +templates may need to have a further "C" subdirectory created. =head3 C Value: Boolean. Default: false. A shortcut for using C and C. Setting this to -true will push C<< $home/nd-site-local/{lib,share} >> into those settings, -respectively. You can then put Perl code in C and templates in C -within the C directory (you have to create this yourself). +true will push C<< $ENV{NETDISCO_HOME}/nd-site-local/{lib,share} >> into those +settings, respectively. You can then put Perl code in C and templates in +C within the C directory. -Note that templates may need to have a further "C" subdirectory -created. +Note that you still need to create the directories yourself, and templates may +need to have a further "C" subdirectory created within "C". =head3 C diff --git a/lib/App/Netdisco/Manual/Troubleshooting.pod b/lib/App/Netdisco/Manual/Troubleshooting.pod index d8dcd429..2faa3c2c 100644 --- a/lib/App/Netdisco/Manual/Troubleshooting.pod +++ b/lib/App/Netdisco/Manual/Troubleshooting.pod @@ -79,6 +79,13 @@ See the tips at L, or else contact the L. +=head1 Devices are not being discovered + +Besides reading the whole of this manual page for general tips, take a look at +the "SNMP Connect Failures" report under the Admin menu. Any devices listed +have had multiple SNMP connect failures, indicating a possible configuration +error on the device or in Netdisco's configuration. + =head1 After OS update or upgrade, Netdisco fails If you upgrade the operating system then your system libraries will change and diff --git a/lib/App/Netdisco/Manual/WritingPlugins.pod b/lib/App/Netdisco/Manual/WritingPlugins.pod index bde07ada..c6321633 100644 --- a/lib/App/Netdisco/Manual/WritingPlugins.pod +++ b/lib/App/Netdisco/Manual/WritingPlugins.pod @@ -118,8 +118,8 @@ the name of the registration helper sub: =head1 Reports Report components contain pre-canned searches which the user community have -found to be useful. Before you go further, it might be the case that you can -generate the report without any Perl or HTML: see the L for details. Otherwise, the typical implementation is very similar to one of the Search @@ -267,9 +267,11 @@ To register the column call the following helper routine: default => 'on', # or undef }); -App::Netdisco searches for one Template::Toolkit file in the regular template -include paths (see also C, below). The template must -be called "C" on disk and live in the directory: +App::Netdisco searches for Template::Toolkit files in the regular template +include paths: either its internal locations, or those configured with the +C setting or the C helper (see +below). The template must be called "C" on disk and +live in the directory: plugin/myportcolumnplugin/device_port_column.tt @@ -293,9 +295,11 @@ To register the column call the following helper routine: label => 'My Device Details Heading', }); -App::Netdisco searches for one Template::Toolkit file in the regular template -include paths (see also C, below). The template must -be called "C" on disk and live in the directory: +App::Netdisco searches for Template::Toolkit files in the regular template +include paths: either its internal locations, or those configured with the +C setting or the C helper (see +below). The template must be called "C" on disk and +live in the directory: plugin/mydevicedetailsplugin/device_details.tt @@ -363,7 +367,15 @@ probably installed in your system's or user's Perl directory. It's not recommended that you mess about with those 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: +template file of your own in your plugin, you need a new path. + +If you don't plan on redistributing the plugin via CPAN, then configuring the +"C" setting to be true will enable "C" +for Perl code and "C" for tmplates in your Netdisco home +location. You will need to create these directories. + +Alternatively, shipping templates within a CPAN distribution, the following +code would be appropriate: package App::Netdisco::Web::Plugin::Search::MyNewFeature @@ -429,11 +441,14 @@ current page with some additional parameters, for example: A simple mechanism exists for loading additional Javascript and CSS documents. This is done in the C<< >> section of the web page. -Within a Template include path (see C, above) create a -directory called "C" and within that another directory named after -your plugin (e.g. "C"). The Javascript and/or CSS files must -then be named "C" and "C" respectively. -For example: +Netdisco searches all template include paths, both those built into the +application and those configured in your plugin(s) with "C" +or C. + +Within the template location, create a directory called "C" and within +that another directory named after your plugin (e.g. "C"). The +Javascript and/or CSS files must then be named "C" and +"C" respectively. For example: plugin/mynewfeature/mynewfeature.js plugin/mynewfeature/mynewfeature.css @@ -444,10 +459,6 @@ helper routines: register_javascript('mynewfeature'); register_css('mynewfeature'); -Note that this searches all template include paths, both those built into the -application and those configured in your plugin(s) with -C. - =head1 Naming and File Location There are several options for how you name, distribute and install your @@ -467,16 +478,25 @@ abbreviated form "X::MyPluginName" which is then expanded to the full package. =head2 File Location -If writing your own plugins, Netdisco supports a local include path which is -usually C<~/site_plugins> (or C<${NETDISCO_HOME}/site_plugins>). +If writing your own plugins that are not for redistribution or packaging on +CPAN, Netdisco can enable local include paths for Perl, templates, and static +content such as javascript and images. -This means if your plugin is called +Configuring the "C" to be "true" enables: + + # perl code + $ENV{NETDISCO_HOME}/nd-site-local/lib + + # templates and static content + $ENV{NETDISCO_HOME}/nd-site-local/share + +Note that you still need to create the directories yourself, and templates may +need to have a further "C" subdirectory created within "C". + +As an example, if your plugin is called "App::NetdiscoX::Web::Plugin::MyPluginName" then it could live at: - ~/site_plugins/App/NetdiscoX/Web/Plugin/MyPluginName.pm - -This feature should make development of new plugins or maintenance of local -plugins much more straighforward. + ~netdisco/nd-site-local/lib/App/NetdiscoX/Web/Plugin/MyPluginName.pm =head1 Plugin Configuration