Item13362: docu, fixes and update of clockpicker

foswiki · Apr 9, 2015 · dccf3f2 · dccf3f2
1 parent 4ff303d
commit dccf3f2
Show file tree

Hide file tree

Showing 14 changed files with 366 additions and 87 deletions.
diff --git a/data/System/MoreFormfieldsAjaxHelper.txt b/data/System/MoreFormfieldsAjaxHelper.txt
@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" comment="" date="1418739013" format="1.1"  version="1"}%
+%META:TOPICINFO{author="ProjectContributor" comment="" date="1428580029" format="1.1"  version="1"}%
 %META:TOPICPARENT{name="MoreFormfieldsPlugin"}%
 ---+!! %TOPIC%
 

diff --git a/data/System/MoreFormfieldsPlugin.txt b/data/System/MoreFormfieldsPlugin.txt
@@ -1,42 +1,183 @@
-%META:TOPICINFO{author="ProjectContributor" comment="" date="1418739013" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" comment="" date="1428580029" format="1.1" version="1"}%
 ---+!! %TOPIC%
 %SHORTDESCRIPTION%
 
-<div class="foswikiHelp">
-Warning: This is a beta release.
-</div>
-
 %TOC%
 
-This plugin implements a set of additional special purpose formfields to be used in [[%SYSTEMWEB%.DataForms][DataForm]] definitions.
-
-These are:
+---++ Description
 
-   * =ipaddress=: a general purpose IP4 address, consisting of 4 octets, e.g. =10.0.0.1=
-   * =netmask=: a special IP address used for routing, consisting of 4 octets, e.g. =255.255.255.0=
-   * =macaddress=: a hardware address given in 6 hex values, e.g. =00:1a:10:6f:ba:12=
-   * =user=
-   * =topic=
-   * =autofill=
-   * =phonenumber=
-   * =time=
-   * =icon=
-   * =smartbox=: the first value of an attribute list (or the one marked with an '*') is used as "any value" place holder 
+This plugin implements a set of additional special purpose formfields to be used in [[%SYSTEMWEB%.DataForms][DataForm]] definitions.
 
----++ !ExampleForm definition
+To make use of these formfields use their type identifier in the =Type= column of a !DataForm definition, such as in
 
-| *Name*  | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
-| <nop>IpAddress | ipaddress |  15  | | network address | M |
+| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* |
+| <nop>IpAddress | ipaddress |  15  | | network address |  |
 | Netmask | netmask |  15  | | netmask |  |
 | <nop>MacAddress | macaddress |  17  | | hardware-addresse | |
 
+When defining a formfield additional parameters may be used in the =Values= column to further customize the behavior of the element.
+
+---++ Known Formfield types
+
+---+++ =autofill=
+
+A formfield that is filled automatically based on values from one or more other formfields of the same topic. During an edit-save loop, values of fields listed in the =source= parameter
+are extracted and concatenated using the specified =separator=. Values of an =autofill= formfield cannot be edited by the user.
+
+*Parameters*:
+
+   * =header=: add an optional string prefixed to the field value, but only when the source fields are not empty
+   * =source=: comma-separated list of one or more formfields to fetch values from
+   * =separator=: separator used when concatenating all values into a new value for the =autofill= field
+   * =footer=: append an optional string to the field value, but only when the source fields are not empty
+
+A typical use-case for an =autofill= field is the construction of a !TopicTitle based on other form properties:
+
+| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* |
+| <nop>TopicTitle | autofill |  1  | header="Project" source="Customer, ID, Year" |  |  |
+| Customer | text | 80 | | | |
+| ID | id | 4 | | | |
+| Year | text | 4 | | | |
+
+---+++ =icon=
+
+A select box to chose an icon supported by Foswiki (famfamfam and fontawesome).
+
+*Parameters*:
+
+   * =cat=: list of icon categories to be included in the selection
+   * =include=: regular expression of icons to include in the selection
+   * =exclude=: regular expression of icons to be excluded from the selection
+
+An icon category can be either a topic on the icon search path as defined in =$Foswiki::cfg{JQueryPlugin}{IconSearchPath}=:
+
+   * =famfamfam= ... to select famfamfam icons only
+   * =silkicons= ... to selec from a silk icon only,
+   * =flagicons= ... to select a flag
+   * ...
+
+Or an icon category as defined in the fontawesome definition:
+
+   * Brand Icons
+   * Chart Icons
+   * Currency Icons
+   * Directional Icons
+   * File Type Icons
+   * Form Control Icons
+   * Medical Icons
+   * Payment Icons
+   * Spinner Icons
+   * Text Editor Icons
+   * Video Player Icons
+   * Web Application Icons
+
+Examples:
+
+| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* | *Default* |
+| <nop>FamFamFamIcon | icon | 20 | cat="famfamfam" | | | |
+| <nop>SilkIcon | icon | 20 | cat="silkicon" | | | |
+| <nop>MintIcon | icon | 20 | cat="minticons" | | | |
+| <nop>FlagIcon | icon | 20 | cat="flagicons" | | | |
+| <nop>WebApp | icon | 20 | cat="Web App" | | | |
+
+---+++ =id=
+
+Extract the numeric identifier from the topic name. This is most usefull for topics created using the =AUTOINC= feature (see [[TemplateTopics]]).
+The =AUTOINC= feature adds a numeric unique identifier when the topic is created. This identifier can be extracted  using an =id= formfield type 
+and stored into a !DataForm and be available for formatted searches.
+
+The value in the =Size= column will be used to add leading zeros to the id. For example, given a topic !FooBar1 has a !DataForm
+
+| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* |
+| ID | id | 4 | | | |
+
+Then upon save the =id= formfield will have a value of =0001=.
+
+*Parameters*: none
+
+---+++ =ipaddress=
+
+A general purpose IP4 address, consisting of 4 octets, e.g. =10.0.0.1= 
+
+*Parameters*: none
+
+---+++ =macaddress=
+
+A hardware address given in 6 hex values, e.g. =00:1a:10:6f:ba:12=
+
+*Parameters*: none
+
+---+++ =netmask=
+
+A special IP address used for routing, consisting of 4 octets, e.g. =255.255.255.0=
+
+---+++ =phonenumber=
+
+A standard telephone number. This formfield uses [[JQueryValidate]] to make sure the formfield value is a valid phone number.
+
+*Parameters*: none
+
+---+++ =select2=
+
+A drop-in replacement for the standard =select= formfield. See [[JQSelect2Contrib]].
+
+*Parameters:* none
+
+---+++ =smartbox=
+
+A somewhat "smarter" checkbox formfield type. It allows to select one of the values as a placeholder representing "any" value in the selection.
+
+So given this !DataForm definition ...
+
+| *Name*  | *Type* | *Size* | *Values* | *Description* | *Attributes* | *Default* |
+| Business Area | smartbox | 5 | Energy, Maritime, Oil & Gas, Software, Across all Business Areas* | | | |
+
+... then selecting "Accross all Business Areas" will select all other areas with it. Likewise, selecting all 
+business areas indivudually will automatically select "Accross all Business Areas" as well.
+
+Note that the "any value" selection is the one indicated by the "*" asterisk, or if not present the first in the list.
+
+---+++ =time=
+
+A time formfield using the clockpicker widget from http://weareoutman.github.io/clockpicker/
+
+---+++ =topic=
+
+A topic reference using JQSelect2Contrib for autocompletion.
+
+*Parameters*:
+
+   * =web=: the web the user can choose topics from; defaults to current web
+   * =default=: the default value to use if no value exists yet
+   * =url=: url for autocompletion, default: =%<nop>SCRIPTURL{"view"}%/%SYSTEMWEB%/MoreFormfieldsAjaxHelper?section=select2::topic;skin=text;contenttype=application/json=
+   * =TopicType=: name of a !TopicType to be selected
+
+Custom parameters may be added. These will be appended to the autocompletion url.
+
+There are a couple of parameters that further customize the behavior of the select2 widget. Some of the most useful ones are:
+
+   * =minimumInputLength=: number of characters that have to be entered before the autocompletion url is called to fetch matching selections from the backend; default 0
+   * =quietMillis=: number of milliseconds to wait for input before the backend is called for autocompletion
+   * =limit=: maximum number of values fetched from the autocompletion backend, default 10
+
+These are also available for the =user= and =icon= formfield types.
+
+---+++ =user=
+
+A user reference using JQSelect2Contrib for autocompletion.
+
+*Parameters*:
+
+   * =url=: url for autocompletion, default: =%<nop>SCRIPTURL{"view"}%/%SYSTEMWEB%/MoreFormfieldsAjaxHelper?section=select2::user;skin=text;contenttype=application/json=
+   * =form=: !DataForm supposed to be attached to user profile pages; this form is used to search for users, default: !UserForm
+
 ---++ Installation Instructions
 
 %$INSTALL_INSTRUCTIONS%
 
 ---++ Info
 <!--
-   * Set SHORTDESCRIPTION = Additionall formfield types for !DataForms
+   * Set SHORTDESCRIPTION = Additional formfield types for !DataForms
 -->
 
 |  Author(s): | Michael Daum|
@@ -45,6 +186,7 @@ These are:
 |  Release: | %$RELEASE% |
 |  Version: | %$VERSION% |
 |  Change History: | <!-- versions below in reverse order -->&nbsp; |
+|  09 Apr 2015: | documentation; final bugfixing before release; updated to latest clockpicker |
 |  26 Mar 2015: | updated list of all fontawesom icons; fixed rendering of Topic formfields values |
 |  16 Dec 2014: | fixed thumbnails in user autocompletion; don't inherit from <nop>ListFieldDefinition for performance reasons |
 |  22 Aug 2014: | added smarbox formfield |

diff --git a/lib/Foswiki/Form/Autofill.pm b/lib/Foswiki/Form/Autofill.pm
@@ -67,22 +67,18 @@ sub param {
 sub beforeSaveHandler {
   my ($this, $topicObject) = @_;
 
-  #print STDERR "called Foswiki::Form::Autofill::beforeSaveHandler()\n";
-
+  my $header = $this->param("header") || '';
+  my $footer = $this->param("footer") || '';
   my $source = $this->param("source");
   my $sep = $this->param("separator") || '';
   return unless $source;
 
-  #print STDERR "source=$source\n";
-
   my @result = ();
   foreach my $name (split(/\s*,\s*/, $source)) {
     my $field = $topicObject->get('FIELD', $name);
     push @result, $field->{value} if defined $field && defined $field->{value} && $field->{value} ne '';
   }
 
-  return unless @result;
-
   my $thisField = $topicObject->get('FIELD', $this->{name});
   $thisField = {
     name => $this->{name},
@@ -93,11 +89,9 @@ sub beforeSaveHandler {
   my $request = Foswiki::Func::getRequestObject();
   $request->delete($this->{name});
 
-  $thisField->{value} = join($sep, @result);
+  $thisField->{value} = @result?$header.join($sep, @result).$footer:"";
 
   $topicObject->putKeyed('FIELD', $thisField);
-
-  #print STDERR "result=$thisField->{value}\n";
 }
 
 1;

diff --git a/lib/Foswiki/Form/Select2.pm b/lib/Foswiki/Form/Select2.pm
@@ -63,20 +63,23 @@ sub renderForEdit {
     $option =~ s/<nop/&lt\;nop/go;
     $choices .= CGI::option(\%params, $option);
   }
-  my $size = scalar(@{$this->getOptions()});
-  if ($size > $this->{maxSize}) {
-    $size = $this->{maxSize};
-  } elsif ($size < $this->{minSize}) {
-    $size = $this->{minSize};
+
+  my $size = $this->{size};
+  if (defined $size) {
+    $size .= "em";
+  } else {
+    $size = "element";
   }
+
   my $params = {
     class => $this->cssClasses('jqSelect2'),
     name => $this->{name},
-    size => $this->{size},
-    'data-placeholder' => $this->param("placeholder") || 'select ...', 
-    'data-width' => $this->param("width") || 'element',
-    'data-allow-clear' => $this->param("allowClear") || 'false',
+    size => 1,
+    'data-width' => $size,
+    'data-allow-clear' => 'true',
+    'data-placeholder' => 'None',
   };
+
   if ($this->isMultiValued()) {
     $params->{'multiple'} = 'multiple';
     $value = CGI::Select($params, $choices);

diff --git a/lib/Foswiki/Form/Topic.pm b/lib/Foswiki/Form/Topic.pm
@@ -48,7 +48,7 @@ sub new {
 sub isMultiValued { return shift->{type} =~ /\+multi/; }
 sub isValueMapped { return shift->{type} =~ /\+values/; }
 
-sub getDefaultValue { return ''; }
+#sub getDefaultValue { return ''; }
 
 sub finish {
   my $this = shift;

diff --git a/lib/Foswiki/Plugins/MoreFormfieldsPlugin.pm b/lib/Foswiki/Plugins/MoreFormfieldsPlugin.pm
@@ -25,9 +25,9 @@ use Foswiki::Plugins ();
 
 use Error qw(:try);
 
-our $VERSION = '0.30';
-our $RELEASE = '26 Mar 2015';
-our $SHORTDESCRIPTION = 'Additionall formfield types for %SYSTEMWEB%.DataForms';
+our $VERSION = '1.00';
+our $RELEASE = '09 Apr 2015';
+our $SHORTDESCRIPTION = 'Additional formfield types for %SYSTEMWEB%.DataForms';
 our $NO_PREFS_IN_TOPIC = 1;
 
 our $iconService;

diff --git a/lib/Foswiki/Plugins/MoreFormfieldsPlugin/Clockpicker.pm b/lib/Foswiki/Plugins/MoreFormfieldsPlugin/Clockpicker.pm
@@ -12,7 +12,7 @@ sub new {
   my $this = bless(
     $class->SUPER::new(
       name => 'Clockpicker',
-      version => '0.06',
+      version => '0.07',
       author => 'Wang Shenwei',
       homepage => 'http://weareoutman.github.io/clockpicker',
       javascript => ['clockpicker.js', 'clockpicker.init.js'],

diff --git a/lib/Foswiki/Plugins/MoreFormfieldsPlugin/DEPENDENCIES b/lib/Foswiki/Plugins/MoreFormfieldsPlugin/DEPENDENCIES
@@ -1,4 +1,4 @@
 Foswiki::Plugins::JQueryPlugin,>5.11,perl,Required
-Foswiki::Contrib::JQSelect2Contrib,>0,perl,Required
+Foswiki::Contrib::JQSelect2Contrib,>1.00,perl,Required
 JSON,>=2.59,cpan,Required
 YAML,>=0.90,cpan,Required
diff --git a/lib/Foswiki/Plugins/MoreFormfieldsPlugin/IconService.pm b/lib/Foswiki/Plugins/MoreFormfieldsPlugin/IconService.pm
@@ -20,6 +20,7 @@ use warnings;
 
 use YAML ();
 use JSON ();
+use constant TRACE => 0;
 
 sub new {
   my $class = shift;
@@ -123,9 +124,12 @@ sub init {
 
   my @icons = ();
 
+  my %cats = ();
+
   foreach my $entry (@{$yml->{icons}}) {
     $entry->{text} = $entry->{id};
     $entry->{id} = 'fa-'.$entry->{id};
+    $cats{$entry->{categories}} = 1 if TRACE;
     push @icons, $entry;
     if ($entry->{aliases}) {
       foreach my $alias (@{$entry->{aliases}}) {
@@ -137,6 +141,7 @@ sub init {
       }
     }
   }
+  print STDERR "cats=".join(", ", sort keys %cats)."\n" if TRACE;
 
   # read icons from icon path
   my $iconSearchPath = $Foswiki::cfg{JQueryPlugin}{IconSearchPath}
@@ -167,9 +172,6 @@ sub init {
         };
       }
       closedir $dh;
-
-      #print STDERR "no icons at $web.$topic\n" unless $icons{$topic};
-
   }
 
   @icons = sort {lc($a->{text}) cmp lc($b->{text})} @icons;