SuperBlogger

The following documentation applies to SuperBlogger version 1.5 (released November 4th, 2009).

DOWNLOADING

Login to your Member Dashboard and grab the latest release from your "My Subscriptions" page. An active membership is required.

INSTALLATION

After you download the zip file, use the Joomla! 1.5 installer by navigating to Extensions >> Install/Uninstall and then choose to upload the zip file.

You also need to enable the plugin, so navigate to Extensions >> Plugin Manager, locate "SuperBlogger" and choose to enable it. To set the various parameters of the plugin, just click on its name to access it's parameters page.

If you are upgrading from an older version of SuperBlogger, you do not need to uninstall the old version first. Simply head over to Extensions >> Install/Uninstall and choose to upload the new file. All plugin files will now be updated maintaining your settings.

REQUIREMENTS

  • In order for SuperBlogger to function as intended, you need to have Joomla! 1.5 installed (preferably the latest version) and working properly. Mootools should not be cut off in any way as it's required by both Joomla! and the plugin.
  • You also have to make sure that Joomla's /cache folder is writable, in other words, check that the permissions for this folder are 755 or 777.
  • A Disqus.com account (and subdomain) which you can register for free at http://disqus.com, so comments are enabled on the plugin. SEF URLs in Joomla! should be enabled for the comments counter feature to properly work, as Disqus utilizes the URL of each post to identify the number of comments for a specified article.
  • A Twitter account (username) if you wish to enable the Twitter tools provided by the plugin. If you don't have one, you can sign up for free at http://twitter.com
  • Optionally you can grab a code snippet from ShareThis.com or AddThis.com (for the social media button option) or get an ID from Outbrain.com (for the rating system). These are not needed as SuperBlogger already provides similar functionality, including a built-in ajax based rating system, using Joomla!'s article database. For the author avatar images, SuperBlogger uses the popular Gravatar.com service. If you enable the related setting in SuperBlogger, the plugin will ping Gravatar.com for an avatar assigned to the author's email address, if it exists, otherwise display a default avatar image (fully configurable via MVC templating).

HOW DOES IT WORK?

SuperBlogger is a powerful plugin adding blogging functionality -the easy way- to Joomla! 1.5 articles. The plugin integrates popular services like Disqus.com (for comments) and Twitter, along with commonly used blogging tools like tagging, rating, bookmarking and social media sharing. Add to that MVC template overrides and the ability to process images server-side and you got a real Wordpress contender, if not better in some areas!

SuperBlogger grabs the text of the article before output and processes it, adding the aforementioned blogging functionalities (and more). These functionalities can easily be set in the plugin's parameters, so you can choose which elements you want to make use of in your Joomla! website and which not. Below we explained the plugin parameters one by one, while providing a screenshot on the right of the actual page in Joomla!.

superblogger_v1.2_plugin_params.png

PLUGIN PARAMETERS (SETTINGS)

IMPORTANT: The first time you go into the plugin parameters, hit "Apply" once so that the parameter area titles are refreshed and displayed properly (this is a known bug in Joomla!, not the plugin).

The parameters are divided into the following areas:
  • Select where to render the plugin: Choose where to "render" (enable) the plugin. This involves selecting specific or all categories (even the "Uncategorized" category) and/or selecting specific or all menu items, in which you want the plugin to render.
  • Common settings: this is where we set the settings available across the entire plugin functionality, like our Disqus.com subdomain, our Twitter username etc.
  • Listing Options: here we define the display of elements in listing pages like blogcategory for example. These options are limited compared to the Article Options because of the less space provided by default in listings.
  • Article Options: here we define the display of elements in article pages.

Let's see now in detail what each parameter does:
The first area "Select where to render the plugin" features 2 multiple-selection boxes for choosing where to have the plugin enabled. You can select individual categories and/or menu items by pressing the Control button (Command button for Mac) and clicking on specific entries.

In "Common settings" we have the most options to set, but these are options we set only once.
  • Enable Tags: if you use the Meta Keywords box inside the Joomla! article form and enable this option, you can actually use these keywords as tags. When the user clicks on a tag in the frontend of your site, they are redirected to the "search" component display directly search results for this specific work or phrase.
  • Enable Disqus comments: enable this option to turn commenting on. Requires a valid Disqus.com account and subdomain. Sign up for free at: http://disqus.com - If you want to use an existing comments system installed on your Joomla! site like JomComment, simply disable this option.
  • Your Disqus subdomain: After you signup with Disqus, you can link Disqus with your website. Disqus will ask you to "add a website", this is where you provide your site details. At the end it will produce a subdomain like mycoolblog.disqus.com. In this page you can see all your comments gathered and do all sorts of things, like adjust styling settings, moderate comments and more. The "mycoolblog" part is what you copy and paste in this option. Learn why Disqus is the best comment system worldwide at http://disqus.com
  • Enable rating: Choose if you want to enable the rating widget or not. If you do, you can choose between SuperBlogger's built in ajax based rating (using Joomla!'s article database natively) or the free online Outbrain.com rating widget service (currently the most popular service of its kind). You can easily obtain your free code there without registering. Visit http://www.outbrain.com/get/ratings/Other and generate your outbrain.com snippet. Then just copy this code snippet in the textarea next to "Your Outbrain.com code". PLEASE NOTE that users of older version who used an ID for Outbrain.com can continue using their ID or grab a new code snippet to their preferred language. The ratings will not be lost.
  • Social button code: Grab your social button code snippet from services like ShareThis.com or AddThis.com and paste it here.
  • Twitter username: Enter here your Twitter username if you want to enable the Twitter tools provided by SuperBlogger (see technical requirements above). Enter nothing to disable Twitter tools. Avoid using a fake or non-existent Twitter username, otherwise the plugin will return an error (Twitter cannot provide a related warning when looking up a non-existent username, thus we cannot know the response).
  • Enable TinyURL integration?: Enable this option to have URLs used in Twitter tools shortened, using the TinyURL.com service. Recommended.
  • Twitter cache: This option defines the cache expiration time in minutes for your Twitter Status (feed) used in the "Latest Tweets" feature (set below). Prefer not to use less than 2 mins for performance reasons.
  • Enable article image processing: This option enables image processing for the first image found in the article introtext. You can choose to enable image processing on listing pages, article pages or both. If you enable this option, you can set additional parameters in the options following.
  • Image width on listing pages (px): The width in pixels for the processed first image in listing pages.
  • Image width on article pages (px): The width in pixels for the processed first image in article pages.
  • Image processing quality (%): The JPEG quality for the processed first image in listing and article pages. The less this value is, the lower the quality of the processed image gets. A value between 70 to 90 is ideal in most cases, mainting low image file size.
  • Cache time for processed images (in mins): Set here the cache expiration time for processed images. When this time is reached, processed images are re-created. SuperBlogger uses caching for the generated images to minimize server load and improve site performance overall.
Depending on the options we've set in the "Common Settings" area, we can now define if we want to show or hide specific elements in listing and article pages.

In "Listing Options" we have the following parameters:
  • Rating widget: show or hide the chosen rating widget if enabled.
  • Tweetmeme button: show or hide the TweetMeme badge for displaying re-tweets and an easy "tweet" this button
  • Article tags: show or hide meta keywords presented as tags.
  • Comments counter/anchor link: show or hide the comments counter (acting as anchor link to the comments form as well) if Disqus comments are enabled.
In "Article Options" we have the following parameters:
  • Social button: show or hide a social button from online services like ShareThis.com or AddThis.com if set in "Common Settings".
  • Font resizer: show or hide the font resizer widget for the main article text.
  • 'Bookmark this' button: show or hide the link used for bookmarking a page in all browsers.
  • Rating widget (with anchor link at the top): show or hide the rating widget along with an anchor link at the top of the article for easier user navigation.
  • Comments counter/anchor link: show or hide the comments counter (acting as anchor link to the comments form as well) if Disqus comments are enabled.
  • Related web content (provided by Sphere.com): if you enable this option, SuperBlogger will use Sphere.com for fetching related (to your article) content from across the web.
  • Introtext drop cap: show or hide a drop cap derived from the first letter in the introtext. IMPORTANT: This option will only work if "image processing" is enabled. It will also perform some necessary HTML cleanup (code formatting) in the article's introtext.
  • Custom HTML: in this textarea you can write some custom HTML code which will get displayed on all pages where SuperBlogger is enabled. Useful for copyright or other notices. Uses 2 variables [url] and [title] which are translated to the current article's url and title respectively.
  • Author avatar (via Gravatar.com): If you enable this parameter, the plugin will look for the current author's email and request an avatar to Gravatar.com based on that email address. If it exists, it will fetch the appropriate image, otherwise it displays a default image.
  • Article details: Show or hide article details like author name, date written, hits.
  • Article section and category with links and associated RSS feed links: Show or hide the related article section and category (linked) with associated RSS feeds.
  • Article tags: show or hide meta keywords presented as tags.
  • Social links: show or hide buttons from services like Delicious, Digg, Technorati and more so users can share/bookmark your articles into these popular services.
  • Latest author articles: fetch the latest articles from current author.
  • Latest author articles limit: enter how many latest author articles to retrieve.
  • Introtext for latest author articles: Show the introtext of the latest author articles
  • Introtext word limit for latest author articles: Number of words to limit the introtext of the latest author articles.
  • Latest tweets: fetch the latest tweets from the Twitter account set in "Common Settings" above.
  • Latest tweets limit: enter how many tweets to fetch for the above parameter.
  • Load a module position after the article text/before or after the comments: choose some module position to display in these places as stated by the options. Useful for displaying e.g. banners or the "related articles" module.
One more parameter area follows, the "Advanced" one, where we set if we will be testing SuperBlogger onto a local server before going live. We also have the option to enable debugging, if requested by the JoomlaWorks support team.

IMPORTANT Please note that if you have other "content" plugins installed in your Joomla! website (e.g. AllVideos, Simple Image Gallery Free/Pro etc.), you can define the order in which they execute and process/modify Joomla! article content by simply re-ordering them in the Plugin Manager. Plugins are executed in Joomla! from top to bottom, exactly as you see them listed in the Plugin Manager. In order for SuperBlogger and other "content" plugins to work properly, make sure that SuperBlogger is re-ordered at the top of the "content" plugins stack (order number 0 or negative, e,g, -1). There is just ONE exception: if you are using the "page break" functionality in Joomla! then you must re-order the "Content - Pagebreak" plugin first and have SuperBlogger as second.

MVC TEMPLATING: THE POWER TO CUSTOMIZE YOUR BLOG LAYOUT

The feature trully setting apart SuperBlogger from any other Joomla! plugin is its MVC architecture, currently available in Joomla! for components and modules only. That means you can use HTML and CSS template overrides inside your Joomla! template and completely change the way the plugin elements display on your website!

So you can either choose to use the versatile base styling of the plugin or simply override it (both the HTML and CSS code) by copying the plugin's /plugins/content/jw_superblogger/tmpl folder within your Joomla! template's /templates/YOURJOOMLATEMPLATE/html folder, as you would with components and modules. Then simply rename the folder /templates/YOURJOOMLATEMPLATE/html/tmpl to /templates/YOURJOOMLATEMPLATE/html/jw_superblogger. Whatever changes you do from now on within this folder, will completely override the plugin's output, exactly as you would with any other MVC component or module.

SuperBlogger uses 2 templates for listing and article pages, with 4 associated CSS files (one common, one for Disqus comments, one for IE6 and one for IE7 - just in case). You are able to override all files or selected files, as you would with any other MVC component or module, with the better exception that SuperBlogger overrides CSS files as well! That means if you copy just the main template file into your /templates/YOURJOOMLATEMPLATE/html/jw_superblogger, then the plugin will override that file, but not the other CSS files!

Below you can see the file structure of the /tmpl folder inside the plugin:
article.php
/css
  |-- disqus.css
  |-- template_ie6.css
  |-- template_ie7.css
  |-- template.css
/images
  |-- (contains image files currently used in the CSS files or inline)
listing.php

If you maintain this structure within /templates/YOURJOOMLATEMPLATE/html/jw_superblogger you can override the entire plugin output!

SEE THE DEMOS

See a live demo of the plugin in action here: http://demo.joomlaworks.net/superblogger
See the plugin running across the "latest news" category in the above website at: http://demo.joomlaworks.net/superblogger/superblogger-running-in-a-category

If you navigate in the above demo website you'll be able to see Joomla! articles with SuperBlogger enabled or disabled, so you can see first hand what features the plugin adds to the Joomla! website.