Dokumentation – heise „socialSharePrivacy“–Plug-In
Author: Hilko Holweg, Sebastian Hilbig, Nicolas Heiringhoff, Juergen Schmidt - Heise Zeitschriften Verlag GbmH & Co. KG
Description: Dokumentation und Einbindung des heise SocialSharePrivacy-Plug-Ins

# jQuery Plug-In socialshareprivacy – Dokumentation

### Download des jQuery-Plug-Ins:

jquery.socialshareprivacy.zip
jquery.socialshareprivacy.tar.gz

1. ## Change-Log

   1. ### Version 1.3

      - Erste Fassung, die auch mehrmals auf einer Seite verwendet werden kann. Damit in den verschiedenen Instanzen unterschiedliche URIs verwendet werden können, wird der per Option `uri` gesetzen Funktion ein Kontext-DOM-Knoten übergeben, über den man eine URI ermitteln kann. Beispiele für die Verwendung haben wir in der Dokumentation bei den Beispiel-Einbindungen ergänzt.
      - Korrektur für IE < 9: Das per `css_path` angegebene Stylesheet wurde mit jQuery-Versionen != 1.4.2 nicht eingebaut.

   2. ### Version 1.2

      - JS: Facebook App-ID entfernt, da diese nicht mehr nötig ist, um den Like/Recommend-Button zu nutzen.

   3. ### Version 1.1

      - CSS: Bei diversen Elementen haben wir mehr Angaben hinzugefügt, um die Nacharbeiten, bei der Integration in eigene Seiten, geringer zu halten. Vor allem haben wir `margin`-, `padding`-, `width`- und `height`-Angaben hinzugefügt.
      - Die Doku wurde um einen Beispiele- und diesen Change-Log-Bereich erweitert.
      - Das Plug-In wurde inhaltlich etwas umgestellt und einige Code-Abkürzungen vorgenommen.
      - JS-Bug Korrektur: Es gab einen Fehler, wenn es in der Seite ein `canonical`-Attribut gab, das aber einen leeren Wert hatte.
      - JS-Bug Korrektur: Bei den Optionen von Google+ gab es eine Angabe, die später im Script nie abgefragt wurde.
      - JS-Bug Korrektur: Die Perma-Option von Google+ wurde nur angezeigt, wenn auch die Perma-Option von Twitter aktiviert war.
      - Twitter: Wenn aktiviert war das iFrame zu groß und überlagerte darunter liegende Links. `<iframe ...style="width:130px; height:25px;"></iframe>` ergänzt.
      - Allgemein: Wenn die Option css_path leer ist, wird kein <link>-Tag mit leerem href in die Seite eingebaut.
      - Allgemein: Die von den Buttons verwendete URI kann jetzt über die Option `uri` gesteuert werden. Es ist sowohl ein fester Wert, wie auch eine Function möglich. Default ist die enthaltene Funktion `getURI`
      - Neue Features:
        - Facebook: Die Beschriftungsvarianten des Buttons "Empfehlen" und "Gefällt mir" kann über die neue Option "action" gesteuert werden. Werte sind "`recommend`" (default) und "`like`".
        - Twitter: Parameter "`language`" (default "`en`") jetzt auch für Twitter.

   4. ### Version 1.0

      - Erstes öffentliches Release

2. ## Dateien

   Zu unserem Plug-In gehören folgende Dateien:

   - index.html (die Doku, die Sie gerade lesen)
   - dimensions.gif (Infografik für diese Doku)
   - 2-klick-logo_min.jpg (Logo klein)
   - jquery.socialshareprivacy.js
   - jquery.socialshareprivacy.min.js
   - socialshareprivacy/socialshareprivacy.css
   - socialshareprivacy/images/dummy_facebook.png
   - socialshareprivacy/images/dummy_facebook_en.png
   - socialshareprivacy/images/dummy_gplus.png
   - socialshareprivacy/images/dummy_twitter.png
   - socialshareprivacy/images/settings.png
   - socialshareprivacy/images/socialshareprivacy_info.png
   - socialshareprivacy/images/socialshareprivacy_on_off.png
   - socialshareprivacy/images/2-klick-logo.jpg

3. ## Voraussetzungen und Einschränkungen

   Technische Voraussetzungen sind jQuery und aktiviertes JavaScript im Browser. Bei uns getestet mit jQuery 1.4.
   Das Plug-In kann derzeit innerhalb einer HTML-Seite nur einmal verwendet werden.

   Wenn Sie Vorschläge zur Verbesserung haben, wenden Sie sich gerne per Mail an 2klick@heise.de.

   Das dauerhafte Aktivieren der Services funktioniert im Internet Explorer erst ab Version 8, da die Vorgängerversionen kein JSON unterstützen. Daher fehlt im IE <= 7 diese Funktion. Der Rest des Plug-Ins ist davon nicht betroffen.

   Für Facebook ist zwingend eine eigene App-ID notwendig, siehe dazu Hinweis zur Facebook App-ID.

4. ## Ausmaße

   Das Plug-In benötigt insgesamt etwa 600 Pixel in der Breite (wenn alle Services aktiviert sind) und ca. 290 Pixel in der Höhe, wobei dies natürlich auch von der Länge der angegebenen MouseOver-Texte abhängt.

5. 1. ## Einbindung

          <head>
            …
            <script type="text/javascript" src="jquery.js"></script>
            <script type="text/javascript" src="jquery.socialshareprivacy.js"></script>
            <script type="text/javascript">
              jQuery(document).ready(function($){
                if($('#socialshareprivacy').length > 0){
                  $('#socialshareprivacy').socialSharePrivacy();
                }
              });
            </script>
            …
          </head>
          <body>
            …
            <div id="socialshareprivacy"></div>
            …
          </body>

   2. ### Erklärung des Codes

          <script type="text/javascript" src="jquery.js"></script>
          <script type="text/javascript" src="jquery.socialshareprivacy.js"></script>

      Die erste Zeile bindet das JavaScript-Framework „JQuery“ (http://jquery.com/) ein, die zweite Zeile unser Plug-In. jQuery liegt unserem Paket nicht bei, Sie müssen es erst noch selbst von der eben genannten Website herunterladen.

          <script type="text/javascript">
            jQuery(document).ready(function($){
              if($('#socialshareprivacy').length > 0){
                $('#socialshareprivacy').socialSharePrivacy();
              }
            });
          </script>

      In diesem `<script>`-Block wird die Plug-In Funktion an ein frei wählbares, leeres HTML-Element in der Seite gehängt, in diesem Fall das Element mit der `id` socialshareprivacy.
      Damit das Anhängen des Plug-Ins nur dann geschieht, wenn das Element auch wirklich vorhanden ist, haben wir noch die Kontrollfunktion `if`, die das Anhängen umschließt und die nötige Bedingung prüft.

          <body>
            …
            <div id="socialshareprivacy"></div>
            …
          </body>

      Irgendwo im `<body>`-Bereich der Website platziert man das leere HTML-Element mit der gewünschten `id`, die identisch zur verwendeten `id` im vorhergehenden `<script>`-Block sein muss.

6. ## Optionen

   Zur Einbindung stehen diverse Optionen zur Verfügung. Im Folgenden sind erstmal die allgemeinen Optionen aufgeführt und anschließend die Optionen nach den einzelnen Services (Facebook, Twitter, Google+) aufgelistet.
   Beispiel für einen Aufruf mit Optionen:

       $('#socialshareprivacy').socialSharePrivacy({
         services : {
           facebook : {
             'perma_option': 'off'
           },
           twitter : {
               'status' : 'off'
           },
           gplus : {
             'display_name' : 'Google Plus'
           }
         },
         'cookie_domain' : 'heise.de'
       });

   1. allgemeine Optionen
      Option | Standardwert | Beschreibung
      --- | --- | ---
      info_link | http://www.heise.de/ct/artikel/2-Klicks-fuer-mehr-Datenschutz-1333879.html | Link zu detaillierter Datenschutz-Info, in unserem Fall ein heise-Artikel.
      txt_help | Text | MouseOver-Text des i-Icons
      settings_perma | Dauerhaft aktivieren und Datenübertragung zustimmen: | Überschrift des Einstellungsmenüs
      cookie_path | / | Pfad der Gültigkeit des Cookies
      cookie_domain | `document.location.host` | Domain für die das Cookie gültig ist
      cookie_expires | 365 | Dauer die das Cookie gültig ist in Tagen
      css_path | socialshareprivacy/socialshareprivacy.css | Pfad zur CSS-Datei, wenn leer wird kein Stylesheet eingebaut
      uri | getURI | Die URI, die von den Buttons weitergegeben werden soll. Möglich ist ein fester Wert (z.B. `"http://www.heise.de"`) oder eine Funktion (siehe `function getURI()` im Plug-In-Quellcode)

   2. Optionen: Facebook
      Option | Standardwert | Beschreibung
      --- | --- | ---
      status | on | Der User hat Facebook zur Auswahl
      app_id | entfallen (seit Version 1.2) | Facebook App-ID; Sie ist nötig um den Empfehlen-Button von Facebook nutzen zu können. Ist sie nicht angegeben, wird dem User Facebook trotz `'status' : 'on'` nicht angeboten. In der JavaScript-Konsole wird dem Entwickler ein entsprechender Hinweis ausgegeben.
      dummy_img | socialshareprivacy/images/dummy_facebook.png | Pfad zur statischen Grafik
      txt_info | Text | MouseOver-Text des Empfehlen-Buttons
      txt_fb_off | nicht mit Facebook verbunden | Text-Entsprechung der Schalter-Grafik im ausgeschalteten Zustand, in der Regel nicht sichtbar für den User
      txt_fb_on | mit Facebook verbunden | Text-Entsprechung der Schalter-Grafik im eingeschalteten Zustand, in der Regel nicht sichtbar für den User
      perma_option | on | Der User hat die Option sich Facebook dauerhaft einblenden zu lassen (mittels Cookie)
      display_name | Facebook | Schreibweise des Service in den Optionen
      referrer_track |  | Wird ans Ende der URL gehängt, kann zum Tracken des Referrers genutzt werden
      language | de_DE | Spracheinstellung
      action | recommend | Beschriftung des Buttons: Empfehlen (`recommend`) oder Gefällt mir (`like`)

   3. Optionen: Twitter
      Option | Standardwert | Beschreibung
      --- | --- | ---
      status | on | Der User hat Twitter zur Auswahl
      dummy_img | socialshareprivacy/images/dummy_twitter.png | Pfad zur statischen Grafik
      txt_info | Text | MouseOver-Text des Tweet-Buttons
      txt_twitter_off | nicht mit Twitter verbunden | Text-Entsprechung der Schalter-Grafik im ausgeschalteten Zustand, in der Regel nicht sichtbar für den User
      txt_twitter_on | mit Twitter verbunden | Text-Entsprechung der Schalter-Grafik im eingeschalteten Zustand, in der Regel nicht sichtbar für den User
      perma_option | on | Der User hat die Option sich Twitter dauerhaft einblenden zu lassen (mittels Cookie)
      display_name | Twitter | Schreibweise des Service in den Optionen
      referrer_track |  | Wird ans Ende der URL gehängt, kann zum Tracken des Referrers genutzt werden
      tweet_text | `getTweetText` | Die Funktion prüft ob es die Meta-Angabe `DC.title` gibt und verwendet diese. Gibt es außerdem noch `DC.creator` wird diese etwas abgesetzt (" - ") hinten angehängt. Ist `DC.title` nicht vorhanden wird das <title>-Tag der Seite verwendet. Diese Option kann mit einem eigenen Text (`typeof == string`) überschrieben werden oder mit einer eigenen Funktion (`typeof == function`), die den Text generiert. Der übergebene Texte wird immer auf 120 Zeichen gekürzt und beim letzten Leerzeichen mit … ersetzt.
      language | en | Spracheinstellung (Default: "`en`" ja, uns gefällt Tweet besser als Twittern)

   4. Optionen: Google+
      Option | Standardwert | Beschreibung
      --- | --- | ---
      status | on | Der User hat Google+ zur Auswahl
      dummy_img | socialshareprivacy/images/dummy_gplus.png | Pfad zur statischen Grafik
      txt_info | Text | MouseOver-Text des „+1“-Buttons
      txt_gplus_off | nicht mit Google+ verbunden | Text-Entsprechung der Schalter-Grafik im ausgeschalteten Zustand, in der Regel nicht sichtbar für den User
      txt_gplus_on | mit Google+ verbunden | Text-Entsprechung der Schalter-Grafik im eingeschalteten Zustand, in der Regel nicht sichtbar für den User
      perma_option | on | Der User hat die Option sich Google+ dauerhaft einblenden zu lassen (mittels Cookie)
      display_name | Google+ | Schreibweise des Service in den Optionen
      referrer_track |  | Wird ans Ende der URL gehängt, kann zum Tracken des Referrers genutzt werden
      language | de | Spracheinstellung

7. ## Beispiel-Einbindungen

   Im Folgenden sehen Sie ein paar beispielhafte Einbindungen von gängigen Konfigurationen.

   - ### Nur Facebook einbinden

         $('#socialshareprivacy').socialSharePrivacy({
             services : {
                 twitter : {
                     'status' : 'off'
                 },
                 gplus : {
                     'status' : 'off'
                 }
             }
         });

   - ### Keine Option zum dauerhaften Aktivieren anbieten

         $('#socialshareprivacy').socialSharePrivacy({
             services : {
                 facebook : {
                     'perma_option'  : 'off'
                 },
                 twitter : {
                     'perma_option' : 'off'
                 },
                 gplus : {
                     'perma_option' : 'off'
                 }
             }
         });

   - ### Nur Google+ anbieten und eigenen Pfad für die CSS-Datei angeben.

         $('#socialshareprivacy').socialSharePrivacy({
             services : {
                 facebook : {
                     'status' : 'off'
                 },
                 twitter : {
                     'status' : 'off'
                 }
             },
             'css_path' : '/style/plugins/socialshareprivacy.css'
         });

   - ### Mehrere 2-Klick-Buttonleisten auf einer Seite

     #### Variante 1: Ein Aufruf des Plug-Ins mit einem entsprechenden Selektor

         <div class="anriss">
             <h3><a href="http://www.heise.de">heise</a></h3>
             <p>lorem ipsum</p>
             <div class="social"></div>
         </div>

         <div class="anriss">
             <h3><a href="http://www.heise.de/security/">heise security</a></h3>
             <p>dolor sit amet</p>
             <div class="social"></div>
         </div>

         <script>
         $(".social").socialSharePrivacy({
             uri : function(context) {
                 return $(context).parents(".anriss").find("h3 a").attr("href");
             }
         });
         </script>

     #### Variante 2: Mehrfacher Aufruf des Plug-Ins

         <div>
             <h3><a href="http://www.heise.de">heise</a></h3>
             <p>lorem ipsum</p>
             <div id="one"></div>
         </div>
         <script>
         $("#one").socialSharePrivacy({
             uri : "http://www.heise.de"
         });
         </script>

         <div>
             <h3><a href="http://www.heise.de/security/">heise security</a></h3>
             <p>dolor sit amet</p>
             <div id="two"></div>
         </div>
         <script>
         $("#two").socialSharePrivacy({
             uri : "http://www.heise.de/security/"
         });
         </script>

8. ## URL

   Die URL, die den Services übergeben wird, kann über eine Option gesteuert werden.
   Standardmäßig wird eine Funktion innerhalb des Plug-Ins verwendet, die die URL der aktuellen Seite aus `document.location.href` ermittelt, ist jedoch eine kanonische URL hinterlegt (`<link rel="canonical">`), wird diese genommen.

9. ## Einstellungen merken

   Bevor das Cookie abgefragt wird, wie die Einstellungen des Users sind, wird erstmal geprüft, wie das Plug-In konfiguriert ist. Ist das Plug-In eventuell nachträglich umgestellt worden hat der User dadurch keine Nachteile.
   Wurde für alle Services die Merken-Funktion ausgeschaltet (`'perma_option' : 'off'`) wird auch das Einstellungsmenü nicht mehr angezeigt.

10. ## Lizenz

    Dieses Plug-In ist unter der MIT License (http://www.opensource.org/licenses/mit-license.php) veröffentlicht und darf gerne für private, wie auch kommerzielle Zwecke genutzt werden.

11. ## Logo

    Unserem Plug-In liegt auch das von uns verwendete Logo bei, das Sie gerne zur Bewerbung dieser Aktion verwenden dürfen.