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:

  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

    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(); 
      }
    });
  </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über­tragung 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.

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