Item14278: docu and final enhancements

foswiki · Jan 19, 2017 · f831b07 · f831b07
1 parent 86e6345
commit f831b07
Show file tree

Hide file tree

Showing 12 changed files with 153 additions and 28 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+igp_*
 *,v
 *.swp
 *.gz

diff --git a/data/System/SocialSharePlugin.txt b/data/System/SocialSharePlugin.txt
@@ -1,13 +1,114 @@
-%META:TOPICINFO{author="ProjectContributor" date="1420222138" format="1.1" version="1"}%
+%META:TOPICINFO{author="micha" comment="reprev" date="1484824411" format="1.1" reprev="3" version="3"}%
 ---+!! %TOPIC%
 %FORMFIELD{"Description"}%
 
 %TOC%
 
----++ Usage
+---++ Summary
+
+This plugin allows you to render so-called social share buttons. Clicking on such a button will allow you to share content
+on other social network in oder to promote the content the social share button is on. Supported ways to share content are:
+
+   * Buffer
+   * Delicious
+   * Digg
+   * Email
+   * Facebook
+   * Google
+   * <nop>LinkedIn
+   * Pinboard
+   * Pinterest
+   * Pocket
+   * Reddit
+   * <nop>StumbleUpon
+   * Tumblr
+   * Twitter
+   * <nop>WhatsApp
+   * <nop>WordPress
+   * Xing
+
+Buttons may be rendered for each of them or a subset using the =%SOCIALSHARE= macro. Additionally this plugin supports a
+way to present a modal dialog with all social buttons on it. 
 
 ---++ Examples
 
+You type:
+
+<verbatim class="tml">
+%SOCIALSHARE{width="42em"}%
+</verbatim>
+
+You get:
+
+%IF{"context SocialSharePluginEnabled"
+   then="$percntSOCIALSHARE{width=\"42em\"}$percnt"
+   else="<img src='%ATTACHURLPATH%/SocialShareSnapshot1.png' width='588' />"
+}%
+
+You type:
+
+<verbatim class="tml">
+%SOCIALSHARE{type="icons" tooltips="on"}%
+</verbatim>
+
+You get:
+
+%IF{"context SocialSharePluginEnabled"
+   then="$percntSOCIALSHARE{type=\"icons\" tooltips=\"on\"}$percnt"
+   else="<img src='%ATTACHURLPATH%/SocialShareSnapshot2.png' width='641' />"
+}%
+
+You type:
+
+<verbatim class="tml">
+%BUTTON{"%MAKETEXT{"Share"}%" icon="fa-share-alt" class="socialShareButton"}%
+</verbatim>
+
+You get:
+
+%BUTTON{"%MAKETEXT{"Share"}%" icon="fa-share-alt" class="socialShareButton"}%
+
+... and - when %TOPIC% is installed - on click it will open a dialog (using [[%SYSTEMWEB%.JQueryBlockUI]]) displaying a list of social share buttons.
+See the below screenshot.
+
+---++ Syntax
+
+=%<nop>SOCIALSHARE{"&lt;services>" ...}%=
+
+In most cases it is sufficient to just list the services you want a social button for. The actual implementation is then predefined in the =socialshare.tmpl= template.
+However, you may still want to take over control and create the button by yourself. This will require detailed knowledge about the way social networks construct share links.
+
+| *Parameter* | *Description* | *Default* |
+| ="..."=, =services= | a list comma separated of services to render buttons for (see the list of IDs above) | all of them, or a subset as configured in =$Foswiki::cfg{SocialSharePlugin}{Services}= | 
+| =type= | | |
+| =tooltips= | boolean flag to switch on/off jQuery-ui tooltips on the buttons; if left =off= then the browser's native tooltip will still be used | off |
+| =url= | | |
+| =tags= | | |
+| =title=, =topictitle= | | |
+| =text= | | |
+| =media= | | |
+| =topic= | | |
+| =web= | | |
+| =include= | | |
+| =exclude= | | |
+| =format= | | |
+| =header= | | |
+| =footer= | | |
+| =separator= | | |
+
+---++ Skin integration
+
+For PatternSkin there is a skin overlay that will all add a "Share" button to the topic toolbox at the top right.
+Change your %LOCALSITEPREFS% by adding the =social= ID to the =SKIN= setting, for example like this:
+
+<verbatim class="tml">   * Set SKIN = social, pattern</verbatim>
+
+You might have other extra skin overlays in place already (such as =natedit=, =metacomment=, =topicinteraction=, and/or =solr=. In that case just prepend =social= to the =SKIN= setting to mix in the functionality.
+
+<img src="%ATTACHURLPATH%/SocialShareSnapshot3.png" width="800" />
+
+For [[Foswiki:Extensions/NatSkin][NatSkin]] no extra provisions are required. The "Share" feature is already integrated into the "More" menu.
+
 ---++ Installation Instructions
 
 %$INSTALL_INSTRUCTIONS%
@@ -16,15 +117,19 @@
 %$DEPENDENCIES%
 
 ---++ Change History
-| | |
+%TABLE{columnwidths="7em" tablewidth="100%"}%
+| 19 Jan 2017 | initial public release |
 
 %META:FORM{name="PackageForm"}%
 %META:FIELD{name="Author" title="Author" value="Michael Daum"}%
-%META:FIELD{name="Copyright" title="Copyright" value="&copy; 2015 Michael Daum http://michaeldaumconsulting.com"}%
+%META:FIELD{name="Version" title="Version" value="%25$VERSION%25"}%
+%META:FIELD{name="Release" title="Release" value="%25$RELEASE%25"}%
 %META:FIELD{name="Description" title="Description" value="%25$SHORTDESCRIPTION%25"}%
-%META:FIELD{name="Home" title="Home" value="Foswiki:Extensions/%TOPIC%"}%
+%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/%25TOPIC%25"}%
+%META:FIELD{name="Copyright" title="Copyright" value="&copy; 2015-2017 Michael Daum http://michaeldaumconsulting.com"}%
 %META:FIELD{name="License" title="License" value="[[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]]"}%
-%META:FIELD{name="Release" title="Release" value="%$RELEASE%"}%
-%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/%TOPIC%"}%
-%META:FIELD{name="Support" title="Support" value="Foswiki:Support/%TOPIC%"}%
-%META:FIELD{name="Version" title="Version" value="%$VERSION%"}%
+%META:FIELD{name="Home" title="Home" value="Foswiki:Extensions/%25TOPIC%25"}%
+%META:FIELD{name="Support" title="Support" value="Foswiki:Support/%25TOPIC%25"}%
+%META:FILEATTACHMENT{name="SocialShareSnapshot3.png" attachment="SocialShareSnapshot3.png" attr="" comment="" date="1484824072" size="124208" user="micha" version="5"}%
+%META:FILEATTACHMENT{name="SocialShareSnapshot2.png" attachment="SocialShareSnapshot1.png" attr="t" comment="" date="1484823748" moveby="micha" movedto="System.SocialSharePlugin.SocialShareSnapshot2.png" movedwhen="1484823797" movefrom="System.SocialSharePlugin.SocialShareSnapshot1.png" size="8299" user="micha" version="2"}%
+%META:FILEATTACHMENT{name="SocialShareSnapshot1.png" attachment="SocialShareSnapshot.png" attr="" comment="" date="1484823803" moveby="micha" movedto="System.SocialSharePlugin.SocialShareSnapshot1.png" movedwhen="1484823809" movefrom="System.SocialSharePlugin.SocialShareSnapshot.png" size="23484" user="micha" version="1"}%
diff --git a/lib/Foswiki/Plugins/SocialSharePlugin.pm b/lib/Foswiki/Plugins/SocialSharePlugin.pm
@@ -1,6 +1,6 @@
 # Plugin for Foswiki - The Free and Open Source Wiki, http://foswiki.org/
 #
-# SocialSharePlugin is Copyright (C) 2015-2016 Michael Daum http://michaeldaumconsulting.com
+# SocialSharePlugin is Copyright (C) 2015-2017 Michael Daum http://michaeldaumconsulting.com
 #
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU General Public License
@@ -21,8 +21,8 @@ use warnings;
 use Foswiki::Func ();
 use Foswiki::Plugins ();
 
-our $VERSION = '0.01';
-our $RELEASE = '15 Sep 2016';
+our $VERSION = '1.00';
+our $RELEASE = '16 Jan 2017';
 our $SHORTDESCRIPTION = 'Social Share Buttons';
 our $NO_PREFS_IN_TOPIC = 1;
 our $core;

diff --git a/lib/Foswiki/Plugins/SocialSharePlugin/Core.pm b/lib/Foswiki/Plugins/SocialSharePlugin/Core.pm
@@ -1,6 +1,6 @@
 # Plugin for Foswiki - The Free and Open Source Wiki, http://foswiki.org/
 #
-# SocialSharePlugin is Copyright (C) 2015-2016 Michael Daum http://michaeldaumconsulting.com
+# SocialSharePlugin is Copyright (C) 2015-2017 Michael Daum http://michaeldaumconsulting.com
 #
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU General Public License
@@ -69,6 +69,8 @@ sub SOCIALSHARE {
   my $text = $params->{text} || $title;
   my $media = $params->{media} || '';
   my $type = $params->{type} || 'default';
+  my $width = $params->{width} || 'auto';
+  my $doTooltips = Foswiki::Func::isTrue($params->{tooltips}, 0);
 
   $topic = $params->{topic} if defined $params->{topic};
   $web = $params->{web} if defined $params->{web};
@@ -130,11 +132,21 @@ sub SOCIALSHARE {
 
   my $result= $header.join($sep, @result).$footer;
 
-  my $class = "";
-  $class = "socialShare_".$type unless $type eq 'default';
+  my @class = ();
+  my $data = "";
+  push @class, "socialShare_".$type unless $type eq 'default';
+  if ($doTooltips) {
+    push @class, "jqUITooltip";
+    $data = 'data-theme="info" data-position="top" data-arrow="true" data-delay="0" data-track="false"'
+  } else {
+    $result =~ s/ title="%MAKETEXT\{.*?\}%"/ /g;
+  }
+  my $class = join(" ", @class);
   $result =~ s/\$class/$class/g;
   $result =~ s/\$web/$web/g;
   $result =~ s/\$topic/$topic/g;
+  $result =~ s/\$width/$width/g;
+  $result =~ s/\$data/$data/g;
 
   return $result;
 }

diff --git a/lib/Foswiki/Plugins/SocialSharePlugin/DEPENDENCIES b/lib/Foswiki/Plugins/SocialSharePlugin/DEPENDENCIES
@@ -1,5 +1 @@
-# Dependencies for SocialSharePlugin
-# Example:
-# Time::ParseDate,>=2003.0211,cpan,Required.
-# Foswiki::Plugins,>=1.2,perl,Requires version 1.2 of handler API.
-
+Foswiki::Plugins::RenderPlugin,>=4.00,perl,Required
diff --git a/lib/Foswiki/Plugins/SocialSharePlugin/MANIFEST b/lib/Foswiki/Plugins/SocialSharePlugin/MANIFEST
@@ -10,6 +10,9 @@ pub/System/SocialSharePlugin/socialshare.css 0644
 pub/System/SocialSharePlugin/socialshare.css.gz 0644
 pub/System/SocialSharePlugin/socialshare.js 0644
 pub/System/SocialSharePlugin/socialshare.js.gz 0644
+pub/System/SocialSharePlugin/SocialShareSnapshot1.png 0644
+pub/System/SocialSharePlugin/SocialShareSnapshot2.png 0644
+pub/System/SocialSharePlugin/SocialShareSnapshot3.png 0644
 pub/System/SocialSharePlugin/socialshare.uncompressed.css 0644
 pub/System/SocialSharePlugin/socialshare.uncompressed.js 0644
 templates/socialshare.tmpl 0644
diff --git a/pub/System/SocialSharePlugin/SocialShareSnapshot1.png b/pub/System/SocialSharePlugin/SocialShareSnapshot1.png
diff --git a/pub/System/SocialSharePlugin/SocialShareSnapshot2.png b/pub/System/SocialSharePlugin/SocialShareSnapshot2.png
diff --git a/pub/System/SocialSharePlugin/SocialShareSnapshot3.png b/pub/System/SocialSharePlugin/SocialShareSnapshot3.png
diff --git a/pub/System/SocialSharePlugin/socialshare.uncompressed.css b/pub/System/SocialSharePlugin/socialshare.uncompressed.css
@@ -3,12 +3,15 @@
   box-sizing:border-box;
 }
 .socialShare a {
-  display:inline-block;
-  min-width:140px;
-  padding:5px 10px;
+  display:block;
+  float:left;
+  min-width:10.5em;
+  padding:0.25px 0.5em;
   white-space:nowrap;
+  line-height:2.5em;
 }
 .socialShare a,
+.socialShare a:visited,
 .socialShare a:hover {
   color:#fff;
   text-decoration:none;
@@ -21,9 +24,11 @@
 .socialShare a img,
 .socialShare a .fa {
   font-size:20px;
-  padding:5px;
-  margin-right:5px;
+  padding:0.25em;
+  margin-right:0.5em;
   vertical-align:middle;
+  width:1.3em;
+  text-align:center;
 }
 
 .socialShare_icons a {
@@ -32,6 +37,7 @@
 .socialShare_icons a img,
 .socialShare_icons a .fa {
   margin:0;
+  width:1.3em;
 }
 
 /* see http://brandcolors.net/ */

diff --git a/pub/System/SocialSharePlugin/socialshare.uncompressed.js b/pub/System/SocialSharePlugin/socialshare.uncompressed.js
@@ -32,5 +32,7 @@ jQuery(function($) {
         throw("ERROR: can't load dialog xhr=",xhr);
       }
     }); 
+
+    return false;
   });
 });
diff --git a/templates/socialshare.tmpl b/templates/socialshare.tmpl
@@ -1,10 +1,10 @@
-%TMPL:DEF{"socialshare::header"}%<div class='socialShare $class clearfix'>%TMPL:END%
+%TMPL:DEF{"socialshare::header"}%<div class="socialShare $class clearfix" style="width:$width" $data>%TMPL:END%
 %TMPL:DEF{"socialshare::footer"}%</div>%TMPL:END%
 %TMPL:DEF{"socialshare::topictitle"}%%WIKITOOLNAME%: %GETTOPICTITLE{topic="$web.$topic"}%%TMPL:END%
 
 %TMPL:DEF{"socialshare::facebook"}%<a class="$service" $style href="http://www.facebook.com/sharer.php?u=%ENCODE{"$url"}%&t=%ENCODE{"$title"}%" target="_blank" rel="noopener noreferrer" title="%MAKETEXT{"share on [_1]" args="$service"}%">%JQICON{"fa-facebook"}%$label</a>%TMPL:END%
 
-%TMPL:DEF{"socialshare::twitter"}%<a class="$service" $style href="http://twitter.com/share?url=%ENCODE{"$url"}%&text=%ENCODE{"$text"}%&hashtags=%ENCODE{"$tags"}%" target="_blank" rel="noopener noreferrer" title="%MAKTEXT{"tweet this"}%">%JQICON{"fa-twitter"}%$label</a>%TMPL:END%
+%TMPL:DEF{"socialshare::twitter"}%<a class="$service" $style href="http://twitter.com/share?url=%ENCODE{"$url"}%&text=%ENCODE{"$text"}%&hashtags=%ENCODE{"$tags"}%" target="_blank" rel="noopener noreferrer" title="%MAKETEXT{"tweet this"}%">%JQICON{"fa-twitter"}%$label</a>%TMPL:END%
 
 %TMPL:DEF{"socialshare::google"}%<a class="$service" $style href="https://plus.google.com/share?url=%ENCODE{"$url"}%" target="_blank" rel="noopener noreferrer" title="%MAKETEXT{"share on [_1]" args="$service"}%">%JQICON{"fa-google-plus"}%$label</a>%TMPL:END%
 
@@ -22,7 +22,7 @@
 
 %TMPL:DEF{"socialshare::email"}%<a class="$service" $style href="mailto:?Subject=%ENCODE{"$title"}%&Body=%ENCODE{"$url"}%" title="%MAKETEXT{"send email"}%">%JQICON{"fa-inbox"}%$label</a>%TMPL:END%
 
-%TMPL:DEF{"socialshare::buffer"}%<a class="$service" $style href="https://bufferapp.com/add?count=horizontal&via=&text=%ENCODE{"$text"}%&picture=%ENCODE{"$media"}%&url=%ENCODE{"$url"}%&source=button" target="_blank" rel="noopener noreferrer" title="%MAKETEXT{"submit to [_1]" args="$service"}%"><img src='%PUBURLPATH%/%SYSTEMWEB%/SocialSharePlugin/buffer-20.png' />$label</a>%TMPL:END%
+%TMPL:DEF{"socialshare::buffer"}%<a class="$service" $style href="https://bufferapp.com/add?count=horizontal&via=&text=%ENCODE{"$text"}%&picture=%ENCODE{"$media"}%&url=%ENCODE{"$url"}%&source=button" target="_blank" rel="noopener noreferrer" title="%MAKETEXT{"submit to [_1]" args="$service"}%"><img src="%PUBURLPATH%/%SYSTEMWEB%/SocialSharePlugin/buffer-20.png" />$label</a>%TMPL:END%
 
 %TMPL:DEF{"socialshare::delicious"}%<a class="$service" $style href="http://del.icio.us/post?url=%ENCODE{"$url"}%&title=%ENCODE{"$title"}%" target="_blank" rel="noopener noreferrer" title="%MAKETEXT{"submit to [_1]" args="$service"}%">%JQICON{"fa-delicious"}%$label</a>%TMPL:END%