Content Plugin ValAddThis for Joomla

Friday, 27 April 2012 12:00

plg_content_valaddthis
Joomla Plugin Multilingual Extension

Current Version: 2.5.1
(April 2012)

Compatibility:
Plugin compatible with Joomla! 1.5 in Native mode
Plugin compatible with Joomla! 1.6 in Native mode
Plugin compatible with Joomla! 1.7 in Native mode
Plugin compatible with Joomla! 2.5 Series

ValAddThis Logo



The content plugin ValAddThis is compatible with both Joomla! versions 1.5, 1.6, 1.7 as well as 2.5+, and it uses the Bookmarking services of AddThis.com. For a complete list of the AddThis features take a look at this page. ValAddThis allows the easy configuration as well the display of the AddThis Button or AddThis Toolbox, in any Joomla article, category, section or frontpage, with or without using plugin tags. ValAddThis will automatically read the article URL, its title and the description, and it will pass them to the AddThis script for you. It produces valid markup for XHTML as well as for CSS 2.1. ValAddThis is free software, which has been released under the GNU/GPL v2.0 license.


This version of the plugin supports the latest AddThis Menu Client API 2.0, in combination with the old API 1.0 (which is still used to display an RSS-Feed button). With ValAddThis you're also able to display the new AddThis Toolbox as well as several other special buttons (such as: LinkedIn and Stumbleupon counters), which aren't supported officially by AddThis yet; for more details on the various configuration options read on. New features in this latest version of ValAddThis plugin will be marked with this icon: New feature of ValAddThis

All the documentation screenshots were taken in Joomla! 1.5, but they won't look much different in newer versions of Joomla!


1. Installation

If you already have an older version of the plugin installed, you don't need to uninstall it as it will update itself. Here are the installation steps:

Now the content plugin ValAddThis is installed and you can begin using it.



2. Configuration

The configuration page of the plugin supports currently 3 languages; Greek, English and German. If you want to write a translation for your language, do the following:


2.1. Edit Plugin


2.2. General Parameters

The first parameters you may alter are the general ones:
plugin01new

  1. You can enter a CSS class to be applied to the plugin, for individual styling. (default: empty)
  2. In order to use the free Analytics service of AddThis.com you have to create an account there and put your account's ID in the plugin field "AddThis ID"; having an account at AddThis gives you access to their free Analytics service. You should also enter your account ID, in case you use an AddThis Button and want to include the "email" service in the AddThis menus; otherwise the email icon won't appear in the AddThis menu. It seems that this is not true if you use an AddThis toolbox instead. (default: empty)
  3. If you are installing the plugin on a secure Web-Server (https), choose "Yes". (default: "No")
  4. Now here you may choose the type of AddThis that will be displayed inside Joomla's articles. Some of the plugin's parameters below are valid only for the Button or for the Toolbox. (default: "Button")
  5. Here you may choose the type of AddThis that will be displayed inside Joomla's categories. (default: "Button")
  6. Here you may choose the type of AddThis that will be displayed inside Joomla's sections (valid only for Joomla! 1.5). (default: "Button")
  7. Here you may choose the type of AddThis that will be displayed on the frontpage (J1.5) or featured articles layout view (after J1.6). (default: "Button")
  8. Choose the position of the plugin relative to the article content; it can be placed on the top, at the bottom or both on the top and at the bottom of articles. (default: "Top")
  9. Choose "Yes" in order to enable the plugin inside Joomla categories. (default: "Yes")
  10. Choose "Yes" in order to enable the plugin inside Joomla sections (valid only for Joomla! 1.5). (default: "Yes")
  11. Choose "Yes" in order to enable the plugin on the frontpage (J1.5) or featured articles layout view (after J1.6) of your Joomla website. (default: "Yes")
  12. This is a comma-separated list of excluded articles (by using their ID); the plugin won't be displayed in the articles listed here. (default: empty)
  13. This is a comma-separated list of excluded categories (by using their ID); the plugin won't be displayed in the categories listed here. (default: empty)
  14. This is a comma-separated list of excluded sections (by using their ID); the plugin won't be displayed in the sections listed here (valid only for Joomla! 1.5). (default: empty)
  15. Optionally you may enter some HTML code, which is going to be displayed before the AddThis Button/Toolbox. (default: empty)
  16. Optionally you may enter some HTML code, which is going to be displayed after the AddThis Button/Toolbox. (default: empty)


2.3. Global Parameters

The next group of parameters you may alter consists of the global ones; global parameters are valid for all AddThis buttons and/or toolboxes that are displayed on a single web-page.

 

For all currently available AddThis services, as well as their Service Codes, check this updated services list.

 



2.4. Language Parameters

The next group of parameters consists of the language-specific ones; language parameters are also valid for all AddThis buttons and/or toolboxes that are displayed on a single web-page.

 

For all currently supported languages by AddThis, including their corresponding Two Letter Codes check this updated languages list.

 

The language parameters are the following:
Screenshot - Parameters: Language

  1. Here you can optionally enter the Two Letter Code of the language you want to explicitly use for the AddThis User Interface (UI). If you leave empty, the AddThis script will change the language automatically based on the visitor's browser language setting. (default: empty)
  2. The next 5 text fields can be optionally defined, in order to change some of the texts used by the AddThis buttons and/or toolboxes, apart from setting the default UI language; this can be extremely helpful if you're not satisfied with the AddThis translations for your language for instance. In the first field you can enter a text for "Bookmark & Share". (default: empty)
  3. In this field you can enter a text that will be used in place of "Email a Friend". (default: empty)
  4. Here you can enter a text for "Email". (default: empty)
  5. Here you can enter a text for "Favorites". (default: empty)
  6. And last but not least you can enter a text for "More". (default: empty)

Any of above texts can be used or just left empty in combination with the default UI Language.



2.5. AddThis Button Parameters

The next group of parameters consists of the AddThis Button specific ones; Button parameters are only valid for the AddThis buttons and they don't affect in any way the toolboxes.

 

The Button parameters are the following:
Screenshot - Parameters: Button

  1. Choose the type of the AddThis button. It can be a standard button for the Bookmarking services, a special button for the RSS feed services or a simple Email-only button. (default: Standard)
  2. Here you can choose the event that will trigger the display of the AddThis compact menu; it can be either when the visitor clicks on the button (Mouse click) or when the visitor hovers with the mouse over the button (Mouse over). Note that this applies only to a "Standard" type of button, since RSS-Feed and Email-only buttons work only when the visitor clicks on them. Important note: if you are about to use both button(s) and toolbox(es) on the same web-page don't set this parameter to "Mouse click", because it will hinder the function of some toolbox services! (default: "Mouse over")
  3. Choose if you want to use your own image for the AddThis button, or your own image with some text next to it, or just some text without any image at all. (default: "No")
  4. Choose one of the standard "AddThis" graphic buttons, which are already included in the plugin installation (in case you chose "No" on the above list). Important note: the images aren't displayed correctly after J1.6 due to changes in the CSS of the administration backend. Take this screenshot as a guide if you have difficulties. (default: "AddThis long")
  5. Optionally you can enter here the URL of your own image for the AddThis button. The URL can be either absolute or document-relative. For example if you had your custom button in your Joomla images folder "images/custom.jpg" you should enter here: images/custom.jpg, which is a document-relative URL. You may use one of the sample images inside the plugin folder: plugins/content/valaddthis/images/add_to_fav_20.png (20px) or plugins/content/valaddthis/images/add_to_fav_32.png (32px) (after J1.6 those are located inside folder plugins/content/valaddthis/valaddthis/images/). (default: empty)
  6. Optionally enter the text that will be displayed next to your own image (or only the text itself). (default: empty)
  7. Optionally enter a CSS style for your custom text (only the attributes with their values like: text-decoration:none;). (default: empty)
  8. Optionally enter an "Alt" text for the AddThis image/text button. (default: empty)
  9. Type in the URL for your site's RSS feed, in case you chose for an RSS feed button; example: http://www.mysite.com/en/sitefeed.feed?type=rss. (default: empty)


2.6. AddThis Toolbox Parameters

The last group of parameters consists of the AddThis Toolbox specific ones; Toolbox parameters are only valid for the AddThis toolboxes and they don't affect in any way the standard buttons.

 

For all currently available AddThis services, as well as their Service Codes, check this updated services list.

 

The Toolbox parameters are the following:
Screenshot - Parameters: Toolbox #1 - Quick Toolbox

  1. Here you may choose one of the 12 predefined quick toolboxes or a Custom Toolbox if you want to define the services yourself by using the AddThis Toolbox Services field below. Important note: the images aren't displayed correctly after J1.6 due to changes in the CSS of the administration backend. Take this screenshot as a guide if you have difficulties. (default: "Custom Toolbox") New feature of ValAddThis

Screenshot - Parameters: Toolbox #2

  1. In this field you may type in the Service Codes of the AddThis services (comma-separated), which you want to be displayed in the AddThis Toolbox. There are some special AddThis services and other 3rd party buttons which have been added exclusively by ValAddThis. Notice that these buttons (Exception: counter_pill, counter_bubble, counter_vertical) can only be used with the following Toolbox CSS styles: Default, Default 32px, Vertical, Vertical 32px, CSS User-Defined. Below are the service names of those special buttons:
    • counter_pill displays the AddThis pill counter button
    • counter_bubble displays the AddThis bubble counter
    • counter_vertical displays the AddThis vertical counter
    • stumbleupon_counter displays a StumbleUpon counter badge
    • stumbleupon_vertical displays a StumbleUpon vertical counter badge
    • digg_counter displays the compact Digg button-counter
      Documentation of the plugin ValAddThis. This plugin is compatible with Joomla! versions 1.5, 1.6, 1.7 and 2.5+ and works with the Bookmarking service script of AddThis.com. Detailed documentation about the installation, configuration, support and download.
    • digg_vertical displays the vertical Digg button-counter
      Documentation of the plugin ValAddThis. This plugin is compatible with Joomla! versions 1.5, 1.6, 1.7 and 2.5+ and works with the Bookmarking service script of AddThis.com. Detailed documentation about the installation, configuration, support and download.
    • linkedin_counter displays the horizontal LinkedIn button-counter (not valid XHTML)
    • linkedin_vertical displays the vertical LinkedIn button-counter (not valid XHTML)
    • facebook_like displays a Facebook like button with counter
    • facebook_rec displays a Facebook recommend button with counter
    • facebook_like_vertical displays a Facebook like button with vertical counter
    • facebook_rec_vertical displays a Facebook recommend button with vertical counter
    • google_plusone displays the small Google Plus +1 button (15px) with counter (not valid XHTML)
      New feature of ValAddThis
    • google_plusone_medium displays the medium Google Plus +1 button (20px) with counter (not valid XHTML)
    • google_plusone_standard displays the standard Google Plus +1 button (24px) with counter (not valid XHTML)
    • google_plusone_tall displays the tall Google Plus +1 button (60px) with vertical counter (not valid XHTML)
    • gplus_ProfileID:W:H displays the Google Plus light badge. All Google Plus parameters are separated by a colon :. ProfileID is the user's (or page's) 21-digit Profile ID, W is the width and H the height of the badge. Notice that only some values are allowed for the width and height, take a look here for possible combinations and values.
      Example: gplus_110925991158276623398:200:69. (not valid XHTML)
      New feature of ValAddThis
    • gplusdark_ProfileID:W:H displays the Google Plus dark badge. All Google Plus parameters are separated by a colon :. ProfileID is the user's (or page's) 21-digit Profile ID, W is the width and H the height of the badge. Notice that only some values are allowed for the width and height, take a look here for possible combinations and values.
      Example: gplusdark_110925991158276623398:200:69. (not valid XHTML)
      New feature of ValAddThis
    • tweet displays the Tweet button with horizontal counter (not valid XHTML)
    • tweet_vertical displays the Tweet button with vertical counter (not valid XHTML)
    • tweet_follow_TwitterUser displays Twitter's official Follow button with horizontal counter, where TwitterUser is the Twitter user to follow. Example: tweet_follow_ValWebDesign. (not valid XHTML)
      New feature of ValAddThis
    • tweet_followlarge_TwitterUser displays Twitter's official large Follow button with horizontal counter, where TwitterUser is the Twitter user to follow. Example: tweet_followlarge_ValWebDesign. (not valid XHTML)
      New feature of ValAddThis
    • tweetmeme displays the Tweetmeme button with horizontal counter
    • tweetmeme_vertical displays the Tweetmeme button with vertical counter
    • pinterest displays the Pinterest Pin It button with a horizontal counter (not valid XHTML)
      New feature of ValAddThis
    • pinterest_vertical displays the Pinterest Pin It button with a vertical counter (not valid XHTML)
      New feature of ValAddThis
    • pinterest_none displays the Pinterest Pin It button without a counter (not valid XHTML)
      New feature of ValAddThis
    • hyves_respect displays the Hyves Respect button with a horizontal counter
      New feature of ValAddThis
    • hyves_respect_vertical displays the Hyves Respect button with a vertical counter
      New feature of ValAddThis
    • hyves_respect_none displays the Hyves Respect button without a counter
      New feature of ValAddThis
    • foursquare displays the Foursquare button. Notice that in order for the Save to foursquare button to work on your site, your site should include hCard or OpenGraph location metadata so that foursquare knows which place your web page is referring to. More info on that here.
      New feature of ValAddThis
    • foursquare_wide displays the wide Foursquare button. Notice that in order for the Save to foursquare button to work on your site, your site should include hCard or OpenGraph location metadata so that foursquare knows which place your web page is referring to. More info on that here. (not valid XHTML)
      New feature of ValAddThis
    • flattr_button:uid:category:popout:hidden displays the Flattr button. All Flattr parameters are separated by a colon :. If button is set to "compact" it displays a horizontal button, leave blank for a vertical one. uid is the Flattr username, category is one of these categories for the article (or thing as it's called by Flattr), if popout is 0 disables the popout that appears when hovering the mouse cursor over the button, set hidden to 1 if you don't want your content to be listed on Flattr. Example with button, popout and hidden params omitted:
      flattr_:valandis:text

      And another example using a horizontal button and hiding content from Flattr:
      flattr_compact:valandis:text::1
      New feature of ValAddThis
  2. Choose "Yes" if you want the names of the services to be also displayed next to their icons (it's doesn't apply for the "CSS Vertical #2" Toolbox style). (default: "No")
  3. Choose "Yes" if you want to use a "rel=nofollow" attribute in the services links of the Toolbox. (default: "No")
  4. Choose the style for the AddThis Toolbox; the CSS styles use styles from the plugin's CSS files and you may have multiple toolboxes on a single web-page that use different styles. (default: "Default")
    • Default: It uses the CSS file default.css and the service icons are placed horizontally.
      Example:
    • Default 32px: It uses the CSS file default32.css, the service icons are 32 pixels wide and placed horizontally.
    • Vertical: It uses the CSS file vertical.css and the service icons are placed vertically.
      Example:
    • Vertical 32px: It uses the CSS file vertical32.css, the service icons are 32 pixels wide and placed vertically.
    • CSS Horizontal: It uses the CSS file horizontal.css and the icons are placed horizontally with a hover effect.
      Example: ValAddThis: Example of CSS Horizontal styling
    • CSS Vertical #1: It uses the CSS file vertical1.css and the icons are placed vertically with a hover effect.
      Example: ValAddThis: Example of CSS Vertical #1 styling
    • CSS Vertical #2: It uses the CSS file vertical2.css and the icons are placed vertically with a hover effect.
      Example: ValAddThis: Example of CSS Vertical #2 styling
    • CSS User-Defined: It uses the CSS file user.css, which can be modified by you; this file is an exact copy of default.css. After you install the plugin, you can find this file here: plugins/content/valaddthis/css/user.css (after J1.6 this is located inside folder plugins/content/valaddthis/valaddthis/css/).
  5. Optionally you may enter the width of the AddThis Toolbox using a CSS value. Example: 100px, 95%, auto etc.; this style will be attached as an inline CSS style and you are recommended to use it. (default: empty)
  6. Optionally you may enter a text that will be displayed next to the Toolbox and it will be treated either as a sharing title or as an alt text for the optional sharing image below. A CSS class with the name "share" is applied to it. (default: empty)
  7. Here you may enter the URL of a share image, which is going to be displayed next to the Toolbox; use the Share (alt) Text above if you want to define an alt text for the sharing image. The URL can be either absolute or document-relative. A CSS class with the name "share" is applied to it and you may use one of the following sample images plugins/content/valaddthis/images/add_to_fav_20.png (20px) or plugins/content/valaddthis/images/add_to_fav_32.png (32px) (after J1.6 those are located inside folder plugins/content/valaddthis/valaddthis/images/). (default: empty)
  8. Optionally you may define a text here that will be displayed in place of "Send to", which is used for the tooltips of the service icons. (default: empty)
  9. Choose if you want to use the icon "More" inside the Toolbox, so that your visitors will be able to select from all available services. This will display a "More" icon right after the other service icons; if you want to display a "More" icon on another position just use a service name of more in the services list. (default: "No")
  10. Optionally enter a text that will be displayed next to the "More"-icon; leave empty if you want only the "More"-icon to be displayed. (default: empty)
  11. Optionally you may enter a text/character that will work as a separator between the "More"-icon and the rest icons; it works only in combination with the "Default" Toolbox style. (default: empty)

Important note: The following services were rewritten because their AddThis alternatives have produced invalid XHTML code: facebook_like and tweetmeme. For this reason these services won't be included in your personal AddThis Analytics.



2.7. Plugin Tags

The content plugin ValAddThis can also be displayed in any Joomla article, by using plugin tags. In order to do that you have to use the opening tag { valaddthis }, followed by any desired parameters with their values and at the end comes the closing tag { /valaddthis } (Note: don't use any spaces between the {} !). Parameters and their values are separated by using the pipe character |. Example: { valaddthis }type=button|button_type=default{ /valaddthis }.

 

Important note: when you trigger the plugin display by using tags, you automatically override any of the plugin parameters, which are already defined in the configuration backend! (even if for example an article is in the "Excluded articles" list)

 

Plugin Parameters
Parameter NamePossible ValuesDescription
 
type button Renders an AddThis Button
toolbox Renders an AddThis Toolbox
button_type default Renders a default AddThis Button
rss Renders an RSS Feed Button
email Renders an Email Button
button_img addthis-long Button #1: AddThis long
addthis Button #2: AddThis short
bm-long Button #3: Bookmark long
bm Button #4: Bookmark short
share-long Button #5: Share long
share Button #6: Share short
plus Button #7: Plus small
rss-feed-big Button #8: RSS feed big
rss-feed-long Button #9: RSS feed long
rss-feed Button #10: RSS feed short
subscribe-big Button #11: Subscribe big
subscribe-long Button #12: Subscribe long
subscribe Button #13: Subscribe short
email Button #14: Email short
counter Button #15: Counter button
lang A Two-Character Language Code A Two Letter Code of the language you want to explicitly use for the AddThis User Interface (UI)
share_caption Any Text Text for "Bookmark & Share"
email_caption Any Text Text for "Email a Friend"
email Any Text Text for "Email"
favorites Any Text Text for "Favorites"
more Any Text Text for "More"
compact List of Services A comma-separated List of Services for the Compact Menu
expanded List of Services A comma-separated List of Services for the Expanded menu
exclude List of Services A comma-separated List of Services to be excluded from all Menus
tool_services List of Services A comma-separated List of Services for the AddThis Toolbox
tool_style default Toolbox Service Icons will be displayed horizontally
default32 Toolbox Service Icons will be displayed horizontally with 32px width
vertical Toolbox Service Icons will be displayed vertically
vertical32 Toolbox Service Icons will be displayed vertically with 32px width
css-hor Toolbox Service Icons will be displayed horizontally with a Hover Effect
css-vert1 Toolbox Service Icons will be displayed vertically with a Hover Effect #1
css-vert2 Toolbox Service Icons will be displayed vertically with a Hover Effect #2
css-user Toolbox Service Icons will be styled according to user-defined CSS file
tool_width Any CSS width value Width of the AddThis Toolbox using a CSS value. Example: 100px, 95%, auto etc.
tool_share Any Text Text that will be used either as a title for the Toolbox and it will be displayed next to it or as the alt text of the optional share image (see: tool_shareurl)
tool_show_names yes Display Service Names next to the Toolbox Service Icons
no Do not display any Service Names next to the Toolbox Service Icons
tool_show_more yes Display "More" Icon in Toolbox
no Do not display a "More" Icon in Toolbox
tool_more Any Text Toolbox Text for "More"
tool_separator Any Text Toolbox Text for Separator (use "pipe" for |)
swfurl URL URL of a Flash Object to share, along with the Link
swf_width Width value Ideal Width of any provided Flash Object
swf_height Height value Ideal Height of any provided Flash Object
screenshot URL URL of an Image that shows a Preview of the Content being shared
tooltip Any Text Text that will be used in place of "Send to" for the tooltips of the service icons
html_before HTML code HTML code, which is going to be displayed before the AddThis Button/Toolbox. Use ">>" inside your HTML instead of the equal sign "="; Example: <p class>>test>
html_after HTML code HTML code, which is going to be displayed after the AddThis Button/Toolbox. Use ">>" inside your HTML instead of the equal sign "="; Example: <p class>>test>
tool_quick Value between 1-12 Choose one of the 12 predefined toolboxes
tool_shareurl URL URL of a share image that will be displayed next to the Toolbox (see also: tool_share; is used to define the alt text of the image)

2.8. Save Configuration

In order to activate the plugin ValAddThis, on the top left click on the radio button "Yes" next to "Enabled":
Screenshot - Configuration: Activation

 

When you are ready click on "Save" (or "Save & Close" in J1.7) to save the plugin's configuration.
Screenshot - Configuration: Activation



3. Known Limitations

One known limitation is that you cannot have at the same web-page AddThis button(s) with the parameter "Display on" set to "Mouse click" ("Mouse over" works just fine) and AddThis toolbox(es); this is because this parameter somehow hinders the proper function of some services icons of the toolbox, as for example the "email", "favorites" and "print". This isn't an issue of the plugin itself and thus it can't be fixed from me.


In addition, if you use the module ValAddThis together with the plugin (in case of a Toolbox), you should be aware there could be some issues with conflicting CSS styles. In a future update of the module there will be some option to disable the loading of the module's CSS files.


Last but not least, if you have questions about the capabilities and/or limitations of the AddThis button you can visit the website or the forum of AddThis.


4. Support

Support for the content plugin ValAddThis is only free for my customers or donators of the plugin. If you need a one-time email support please make a donation by using the PayPal "Donate" button on the right hand side. Donators will be listed at the end of the documentation.


If you have any suggestions or found any bugs in the plugin, feel free to:


Please vote for the plugin at the web-page of Joomla Extensions. Thank you!


5. Download

You can download the latest version of the plugin ValAddThis from here or from the project's page at Google Code. There is also a version of the same plugin, with CSS rounded corners for the AddThis Toolbox styles, but it doesn't produce valid markup for CSS 2.1.



6. ChangeLog

Version 2.5.1 (27 April 2012)

Version 2.5.0 (24 April 2012)

Version 1.5.5 (31 March 2012)

Version 1.5.4 (07 October 2011)

Version 1.5.3 (01 October 2011)

Version 1.5.2 (29 September 2011)

Version 1.5.1 (01 September 2011)

Version 1.5.0 (18 August 2011)

Version 1.4.2 (01 August 2011)

Version 1.4.1 (29 July 2011)

Version 1.4.0 (27 July 2011)

Version 1.3.0 (14 October 2010)

Version 1.2.0 (21 June 2010)

Version 1.1.0 (14 June 2010)

Version 1.0.1 (28 May 2010)

Version 1.0.0 (16 May 2010)


7. Donators

ValAddThis Donators
Donator's NameWebsite URL
 
Edze de Boer www.totalwebshops.nl
Marisa Herzog www.lehrmittelperlen.net
Arvin Avil├ęs www.circo212.org.mx
Dave Bishop ecowebdesign.net
Dave Rodman www.rodmandesign.com