jQuery Plug-In socialshareprivacy – Dokumentation

Download des jQuery-Plug-Ins:

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

  1. Change-Log

    1. Version 1.6

      • Die Option perma_orientation ist hinzugekommen, sie dient der Steuerung wohin sich das Perma-Menü ausklappt.
    2. Version 1.5

      • Neue Voraussetzung: Ab dieser Plug-In Version ist min. jQuery 1.7 erforderlich, da von der .live()-Funktion auf .on() umgestellt wurde.
      • Twitter wird immer der "Do not Track"-Parameter (dnt=true) angehängt.
      • Man kann das dunkle Farbschema des Facebook-Buttons einstellen und es liegen dunkle Dummy-Grafiken für alle Services bei.
      • Eine vertikale Anordnung der Buttons ist jetzt möglich.
      • Bei Facebook kann statt des Like-/Recommend-Buttons auch ein einfacher Teilen-/Share-Link angezeigt werden.
      • Die Like-/Tweet-/+1-Anzahl kann nun auch oberhalb des Buttons angezeigt werden (vertikale Darstellung). Bei der vertikalen Darstellung ist es möglich, die Schalter-Grafik rechts von den Buttons anzuzeigen, wenn alle drei Buttons die vertikale Darstellung nutzen.
      • Mehrsprachigkeit: Alle Texte sind nun ausgelagert und das Plug-In liefert Sprachdateien (JSON-Format) für Deutsch (de.lang) und Englisch (en.lang) mit. So ist es auch möglich das Plug-In beliebig mit anderen Sprachen zu nutzen, indem einfach eine neue Sprachdatei (z.B. es.lang) hinterlegt und beim Aufruf des Plug-Ins angegeben wird. Konnte die Datei nicht geladen werden bricht das Plug-In ab – kein Fallback auf eine andere Sprache.
        Diverse Optionen sind weggefallen (s.u.), dabei handelt es sich vor allem um Texte, die von nun an in den Sprachdateien (mitgeliefert de.lang und en.lang) zu finden sind. Sie können entweder diese Dateien editieren für eigene Texte oder eine eigene *.lang-Datei hinzufügen (z.B. firma_de.lang).
      • Das Plug-In ist nun auch per Tastatur (Tab+Enter) bedienbar.
      • Google+: Umstellung der Einbindung von .../plusone.js auf .../platform.js (Aktualisiert entsprechend der Google+-Doku)
      • Bugfixes
    3. Version 1.4

      • Grafik: Da Google+ eine neue aktive Grafik einsetzt, wurde nun auch die inaktive Google+ Grafik angepasst
        alt: alte Google+ Grafik
        neu: neue Google+ Grafik
    4. 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.
    5. Version 1.2

      • JS: Facebook App-ID entfernt, da diese nicht mehr nötig ist, um den Like/Recommend-Button zu nutzen.
    6. 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.
    7. Version 1.0

      • Erstes öffentliches Release
  2. Dateien

    Zu unserem Plug-In gehören folgende Dateien:

  3. Voraussetzungen und Einschränkungen

    Technische Voraussetzungen sind jQuery und aktiviertes JavaScript im Browser. Seit Plugin-In Version 1.5 ist mindestens jQuery 1.7 erforderlich.
    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

    Ausmaße des Plug-Ins

    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.

    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({
                "css_path"  : "/js/plugins/socialshareprivacy/socialshareprivacy.css",
                "lang_path" : "/js/plugins/socialshareprivacy/lang/",
                "language"  : "de"
              });
            }
          });
        </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({
              "css_path"  : "/js/plugins/socialshareprivacy/socialshareprivacy.css",
              "lang_path" : "/js/plugins/socialshareprivacy/lang/",
              "language"  : "de"
            });
          }
        });
      </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.

      Der Wert zum Schlüssel css_path gibt an, wo auf ihrem Server die CSS-Datei unseres Plug-Ins abgelegt wurde.
      Der Wert zum Schlüssel lang_path gibt das Verzeichnis an, wo auf ihrem Server die Sprach-Dateien (*.lang) unseres Plug-Ins abgelegt wurden.
      Der Wert zum Schlüssel language wählt die Sprach-Datei im Verzeichnis (angegeben unter lang_path) aus. Als Dateinamenserweiterung wird .lang angenommen. Ist die Datei nicht vorhanden bricht das Plug-In ab und schreibt eine Ausgabe in die Entwickler-Konsole des Browsers.

      <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.

  5. 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 : {
          'dummy_img' : '/images/socialshareprivacy/images/dummy_gplus_variante.png'
        }
      },
      'css_path'      : '/js/plugins/socialshareprivacy/socialshareprivacy.css',
      'lang_path'     : '/js/plugins/socialshareprivacy/lang/',
      'language'      : 'de',
      '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.
      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)
      language de Name der Sprachdatei (Schema de.lang) Beispiel
      lang_path lang/ Pfad zum Verzeichnis, wo die Sprachdateien zu finden sind Beispiel
      skin light Möglich sind dark und light
      alignment horizontal Möglich sind horizontal und vertical. Diese Angabe bezieht sich darauf, ob die Buttons neben- oder untereinander stehen.
      switch_alignment left Möglich sind left und right. Die Schalter-Grafik wird auf der entsprechende Seite der Buttons angezeigt. Diese Option hat nur Auswirkungen, wenn alle 3 Dienste die Darstellung des Zählers über dem Button nutzen.
      (Facebook: 'layout' : 'box_count'
      Twitter: 'count' : 'vertical'
      Google Plus: 'size' : 'tall')
      perma_orientation down Die Werte "down" und "top" sind möglich. Bei "top" klappt sich das Kontextmenü für die Perma-Optionen der Services nach oben auf. "down" ist das bisherige Standardverhalten und klappt das Menü nach unten auf.
      txt_help entfallen (seit Version 1.5) MouseOver-Text des i-Icons
      settings_perma entfallen (seit Version 1.5) Überschrift des Einstellungsmenüs
    2. Optionen: Facebook
      Option Standardwert Beschreibung
      status on Der User hat Facebook zur Auswahl
      dummy_img socialshareprivacy/images/dummy_facebook.png Pfad zur statischen Grafik
      perma_option on Der User hat die Option sich Facebook dauerhaft einblenden zu lassen (mittels Cookie)
      referrer_track   Wird ans Ende der URL gehängt, kann zum Tracken des Referrers genutzt werden
      action recommend Beschriftung des Buttons: „Empfehlen“ (recommend) oder „Gefällt mir“ (like)
      layout button_count Möglich sind button_count (der Zähler wird neben dem Button dargestellt) und box_count (der Zähler wird über dem Button dargestellt)
      sharer
      Optionen: sharer Beispiel
      Option Standardwert Beschreibung
      status off Um das Share-/Teilen-Feature einzuschalten setzt man hier on. Damit wird beim Aktivieren von Facebook kein Code von Facebook-Servern geladen, sondern lediglich ein Link auf eine Grafik zu Facebooks Teilen-Seite gesetzt.
      Die Dummy-Grafik wird entsprechend ersetzt und für die aktive Darstellung wird ebenfalls eine normale Grafik genommen und nichts von Facebook bezogen.
      dummy_img socialshareprivacy/images/dummy_facebook_share_de.png Pfad zur statischen Grafik (Dummy).
      img socialshareprivacy/images/dummy_facebook_share_active_de.png Pfad zur statischen Grafik (aktive Darstellung).
      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.
      display_name entfallen (seit Version 1.5) Schreibweise des Service in den Optionen
      language entfallen (seit Version 1.5) Spracheinstellung
      txt_info entfallen (seit Version 1.5) MouseOver-Text des Empfehlen-Buttons
      txt_fb_off entfallen (seit Version 1.5) Text-Entsprechung der Schalter-Grafik im ausgeschalteten Zustand, in der Regel nicht sichtbar für den User
      txt_fb_on entfallen (seit Version 1.5) Text-Entsprechung der Schalter-Grafik im eingeschalteten Zustand, in der Regel nicht sichtbar für den User
    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
      perma_option on Der User hat die Option sich Twitter dauerhaft einblenden zu lassen (mittels Cookie)
      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.
      count horizontal Möglich sind horizontal (der Zähler wird neben dem Button dargestellt) und vertical (der Zähler wird über dem Button dargestellt)
      display_name entfallen (seit Version 1.5) Schreibweise des Service in den Optionen
      txt_info entfallen (seit Version 1.5) MouseOver-Text des Tweet-Buttons
      txt_twitter_off entfallen (seit Version 1.5) Text-Entsprechung der Schalter-Grafik im ausgeschalteten Zustand, in der Regel nicht sichtbar für den User
      txt_twitter_on entfallen (seit Version 1.5) Text-Entsprechung der Schalter-Grafik im eingeschalteten Zustand, in der Regel nicht sichtbar für den User
      language entfallen (seit Version 1.5) 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
      perma_option on Der User hat die Option sich Google+ dauerhaft einblenden zu lassen (mittels Cookie)
      referrer_track   Wird ans Ende der URL gehängt, kann zum Tracken des Referrers genutzt werden
      size medium Es gibt noch small, standard und tall; Um den +1-Zähler über dem Button anzuzeigen wählen Sie bitte tall
      display_name entfallen (seit Version 1.5) Schreibweise des Service in den Optionen
      txt_info entfallen (seit Version 1.5) MouseOver-Text des „+1“-Buttons
      txt_gplus_off entfallen (seit Version 1.5) Text-Entsprechung der Schalter-Grafik im ausgeschalteten Zustand, in der Regel nicht sichtbar für den User
      txt_gplus_on entfallen (seit Version 1.5) Text-Entsprechung der Schalter-Grafik im eingeschalteten Zustand, in der Regel nicht sichtbar für den User
      language entfallen (seit Version 1.5) Spracheinstellung
  6. Beispiel-Einbindungen

    Im Folgenden sehen Sie ein paar beispielhafte Einbindungen von gängigen Konfigurationen. Da die meisten Benutzer den Pfad zu CSS- und Sprach-Dateien vermutlich anpassen müssen, werden diese Optionen hier immer mit angegeben.

  7. 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.

  8. 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.

  9. 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.

  10. Unserem Plug-In liegt auch das von uns verwendete Logo bei, das Sie gerne zur Bewerbung dieser Aktion verwenden dürfen. Logo 2 Klicks für mehr Datenschutz

  11. Forks

    Unser Projekt war von Anfang darauf ausgelegt offen zu sein, sodass andere es weiterentwickeln und an ihre Bedürfnisse anpassen können. Das haben zu unserer Freude auch viele getan.
    Im Folgenden finden Sie eine kleine Auflistung einiger Forks. Diese Liste erhebt keinerlei Anspruch auf Vollständigkeit.