iBegin Share is an easy to use tool that allows you to make it easy to share and spread your content across the web. Features built-in support for email, the social web & bookmarks, Word Document, PDF, and printing.

Table of Contents

  1. Quick Start
  2. Usage Example
  3. Bookmarks Services
  4. Plugins
  5. Skinning
  6. Resources
  7. License

TopQuick Start

Installation instructions have changed from version 2.2 to 2.3!

iBegin Share can be setup in two different environments. It can work both with PHP (and some additional plugins) and without PHP. If you are using the Wordpress plugin you do not need to do any configuration, as it is automatic. The first thing you will need to do, however, with either configuration, is to include the files in your website's header with three lines:

<link rel="stylesheet" type="text/css" media="screen" href="media/share/share.css" />
<script src="media/share/share.js" type="text/javascript"></script>
<script type="text/javascript">iBeginShare.base_url = 'media/share/';</script>

These should be the correct paths to the CSS and JavaScript files. These can be either absolute or relative to the current directory. You also need to make sure you set base_url to be the base directory which contains share.js and share.php. Make sure this includes the trailing slash.

The plugins which require PHP are Email, My PC, and Print. If you do not wish to use these then you may disable them in share.js (at the end of the file).

Enabling Statistics

As of iBegin Share 2.3 we now include an optional statistics module. This will gather and display statistics on how your users interact with the iBegin Share module. Enabling the stats module consists of two steps, again, if you are using Wordpress, this is handled within the Wordpress plugin options.

You first need to setup your database, using either PostgreSQL or MySQL. You will find the appropriate SQL dump under sql/. Import this into your database server:

MySQL

mysql -u<username> -p -D<database_name> < path/to/database.mysql

PostgreSQL

psql -U <username> -W -f path/to/database.pgsql <database_name>

Next you need enable logging in the JavaScript file. This is done by adding another line in your header:

<script type="text/javascript">iBeginShare.enableStats();</script>

This tells the plugins (that are applicable) to redirect all requests to share.php first so that it can log clicks.

The next step requires you to edit includes/config.inc.php. Open it in your favorite text editor, and input the databae settings. Both MySQL and PostgreSQL configurations are available. Also make sure you adjust IBEGIN_SHARE_ENABLE_LOGS and set it to true.

define(IBEGIN_SHARE_ENABLE_LOGS, true);
$db = array(
    'username'  => 'root',
    'password'  => '',
    'host'      => 'localhost',
    'port'      => '',
    'database'  => 'my_database',
    'type'      => 'mysql', // or postgresql
);

Configuring the Email Plugin

The email plugin includes a few basic configuration options, which you can change by opening plugins/email/email.php in a text editor.

// The subject of the email to send. (Eg. "You've got new message about iBegin Share")
function generateEmailSubject($title, $link, $from_name, $from_email, $to_name, $to_email)
{
    return "{$from_name} wants you to see this link";
}
// The plain text body of the email to send
function generateEmailBody($title, $link, $from_name, $from_email, $to_name, $to_email, $message=null)
{
    $output = array();
    $output[] = $from_name . ' thought you might find this link interesting:';
    $output[] = '';
    $output[] = 'Title: ' . $title;
    $output[] = 'Link: ' . $link;
    if ($message) $output[] = 'Message: ' . messageFilter($message);
    $output[] = '';
    $output[] = '-----------------------------';
    $output[] = $from_name . ' is using iBegin Share (http://www.ibegin.com/labs/share/)';
    $output[] = '-----------------------------';
    return implode("\r\n", $output);
}

TopUsage Examples

There are three variables you will need to pass to attach a button. All variables are optional, but most likely you will want to at least specify link and title. If these are not present they default to the current page's title and url.

The third variable, content variable should be the full URL as described in PHP's fopen() documentation to the page which produces the trimmed content. If you pass the content parameter it will enable two additional plugins, My Computer and Print.

The attachLink method accepts several parameters via the standard params which you can pass to customize how your link shows on the page.

Below are several common examples.

Shiny Button

This example inserts the default button link, using the default skin.

<span id="share-tool"><script type="text/javascript">iBeginShare.attachLink('share-tool', {
    link: 'http://www.ibegin.com/labs/share/',
    title: 'Local Space Innovation',
    link_style: 'button'
});</script></span>

Plain Text Link

This example inserts a normal text link, using the red skin, and the green link skin.

<span id="share-tool"><script type="text/javascript">iBeginShare.attachLink('share-tool2', {
    link: 'http://www.ibegin.com/labs/share/',
    title: 'Local Space Innovation',
    skin: 'red',
    link_style: 'text',
    link_skin: 'green'
});</script></span>

TopBookmarks Services

The bookmarks system is flexible enough to allow you to add additional bookmarks to the list.

Add Bookmark Services

Due to the way iBegin Share plugins work adding a bookmark service is extremely easy. You will need to do three things to add a plugin:

  1. Add an icon for this service, which will be a cleaned version of the service name in share/images/icons/. It should be formated as bm_<servicename>.gif and 40x40px dimentions.


    Example: MSN Live would be bm_msnlive.gif.
  2. Call the addService method anywhere after share/script/share.js has been loaded.
    Example: iBeginShare.plugins.builtin.bookmarks.addService('Digg', 'http://digg.com/submit/?url=__URL__');
    Two variables are present in the second argument, the url, __TITLE__ and __URL__.

Configure Visible Bookmarks

You are also able to choose which bookmark services appear via editing share/script/share.js. Open up the file, and scroll to the bottom. Near the bottom you will see the list of services already added. Simply comment out any of these to disable them.

Note: To comment out a service place // at the beginning of the line.

TopPlugins

iBegin Share supports adding additional plugins beyond those that are built-in. Below is some brief documentation on creating your own plugin.

We will be using the MyPC built-in plugin for our example. The code below is slightly modified from the source to make it standalone (built-in require different method calls).

We declare our function using the standar namespacing syntax.

var iBeginSharePlugin_myPC = function()
{

Inside we can add any private methods used directly by the function.

// This is a private function used by myPC to follow DRY standards.
  function createDocumentRow(type, label, params)
  {
    var link = encodeURIComponent(params.link);
    var title = encodeURIComponent(params.title);
    var content = encodeURIComponent(params.content);

    var tr = document.createElement('tr');
    var td = document.createElement('td');
    td.width = '10%';
    td.paddingLeft = '50px';
    var a = document.createElement('a');
    a.href = iBeginShare.base_url + 'share.php?mod=send&act=mypc&f=pdf&url='+link+'&content='+content+'&title='+title;
    a.title = label;
    var img = document.createElement('img');
    img.src = iBeginShare.base_url + 'share/images/icons/pc_'+type+'.gif';
    img.style.border = 0;
    img.style.width = '40px';
    img.style.height = '40px';
    a.appendChild(img);
    td.appendChild(a);
    tr.appendChild(td);
    var td = document.createElement('td');
    var a = document.createElement('a');
    a.href = iBeginShare.base_url + 'share.php?mod=send&act=mypc&f='+type+'&url='+link+'&content='+content+'&title='+title;
    a.innerHTML = label;
    td.appendChild(a);
    tr.appendChild(td);

    return tr;
  }

Now we need to add the controls to interact with the framework. label and render are the only required publicly accessible methods.

  return {
    // The label for your plugin. Used both in the tab name and the heading.
    label: 'My PC',
    // Any parameters it requires. Link and title are always available, content may not be.
    requires: ['link', 'title', 'content'],
    // The render method passes in a callback function, which is the
    // iBegin Share control, and a list of parameters.
    render: function(callback, params)
    {
      // Create our HTML
      var container = document.createElement('div');
      var table = document.createElement('table');
      table.cellPadding = 0;
      table.cellSpacing = 0;
      table.style.border = 0;

      table.appendChild(createDocumentRow('pdf', 'PDF - Portable Document Format', params));
      table.appendChild(createDocumentRow('word', 'Microsoft Word, Wordpad, Works', params));
      container.appendChild(table);

      var iframe = document.createElement('iframe');
      iframe.style.display = 'none';
      iframe.name = 'shre_sbmt';
      container.appendChild(iframe);

      // Pass the HTML as well as the params (they can be changed)
      // to the iBegin Share framework via a callback function.
      callback(container, params);
    }
  }
}();

And finally we need to register our plugin with the framework.

iBeginShare.plugins.register(iBeginSharePlugin_myPC);

Available public methods to plugins:

Enabling Statistics in Your Custom Plugin

Work in progress. Ask on the forums.

TopSkinning

New in iBegin Share 2.4

You can create skins, for both the link, and the actual share box by simply modifying some CSS. We also include several defaults.

Link Styles

To use a link style, you must specify it during the attachLink call as the 3rd argument. Below are the built-in styles. You may add your own by defining a share-link-[style] class in your CSS, which is applied to the share-link container.

Share Box Skins

To use a share box skin, you must specify it in the params passed to attachLink or show as the skin parameter. Below are the built-in skins. You may add your own by defining a share-skin-[skin] class in your CSS, which is applied to #share-box container.

You may also set the default skin values. The corresponding options are default_skin, default_link, and default_link_skin. These can be set by using iBeginShare.option = 'value'. For example, if you wanted to change the default link type to be text links, you could put iBeginShare.default_link = 'text'; in your JavaScript.

To create your skin, we suggest downloading the uncompressed version of iBegin Share, and taking a look towards the end of the share.css file. You will find the included example skins there.

TopResources

TopLicense

Copyright (c) 2008 iBegin

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.