v1.1 2012-12-24
- New: Facebook Login Widget
- New: Function wpss_display_fb_buttons will display the Facebook login button anywhere in your theme


v1.0 2012-11-17
- Initial release

Documentation

WPSocialStreamer Developer Documentation

In this chapter we will describe how to create your own WPSocialStreamer extensions. It has never been so easy to extend a plugin!

WPSocialStreamer has a global extension array that must be extended by every extension. To do that the plugin offers a filter: ‘wpsocialstreamer_extensions’. Here is an example how to hook into the filter:

// Add extension options filter
add_filter( 'wpsocialstreamer_extensions', 'wpss_extension_wordpress_settings' );

Your function that extends the array must have one parameter ‘extension_array’ and it must return the extended array again. Here is the example of such a function which also shows how to build the array:

/**
* Extend the extension array
*
* @param array $extensions_array
* @return array
*/

function wpss_extension_wordpress_settings( $extensions_array ) {

  $extensions_array['wordpress'] = array (
    /* Set the title that will be displayed on the settings page */
    'title'     => __('WordPress', 'wpsocialstreamer'),
    /* Set a function that should be used to checked if the plugin is 
    installed or set to false if it is a wordpress core extension. */
    'function'        => false,
    /* Set the link to the plugin */
    'link'                  => 'http://wordpress.org',
    /* Extension status: true or false */
    'active' => true,
    /* Define an array with available events / actions */
    /* ATTENTION: events should be named exactly like actions (hooks) ! */
    'events' => array (
      /* Action fired when a post gets published */
      'publish_post'  => array (
        /* Set the default message template */
        'template'  => __("Hey, I just added %POST_NAME%!", 'wpsocialstreamer'),
        /* Set the event description for user settings page. */
        /* Share this event when: */
        'title'     => __("I publish a new post.", 'wpsocialstreamer'),
        /* Define placeholders that admin can use to generate message text */
        /* Set to false if no placeholders are available: 'placeholders' => false */
        'placeholders' => array (
          /* Set placeholder name and a short description */
          'POST_NAME' => __("Name of the post", 'wpsocialstreamer')
        ) /* END placeholders */
      ), /* END event */
      
      /* Fired when a new comment is submitted */
      'comment_post'  => array (
        /* Set the default message template */
        'template'  => __("Wohoo, I just commented on %POST_NAME%!", 'wpsocialstreamer'),
        /* Set the event description for user settings page. */
        /* Share this event when: */
        'title'     => __("I post a new comment.", 'wpsocialstreamer'),
        /* Define placeholders that admin can use to generate message text */
        /* Set to false if no placeholders are available: 'placeholders' => false */
        'placeholders' => array (
          /* Set placeholder name and a short description */
          'POST_NAME' => __("Name of the post", 'wpsocialstreamer'),
          'CONTENT'   => __("Post content", 'wpsocialstreamer')
        ) /* END placeholders */
      ) /* END event */
    )
  );

  return $extensions_array;
}

As you can see in the example above we have defined two events: Publish post and comment post. Thereby we have to add two action hooks to our extension:

add_action( 'publish_post', 'wpss_wordpress_publish_post');
add_action( 'comment_post', 'wpss_wordpress_comment_post', 10, 2);

Take a look to the action functions:

/**
* Called when user publishes a post
*/
function wpss_wordpress_publish_post( $postID ) {
  global $wpss;
  
  if ( empty($postID) ) return;

  // Check if extension event is active.
  // Function parameter:
  // 1. Extension name
  // 2. Event name
  if ( $wpss->is_active('wordpress', 'publish_post') ) {

    // Load message for the given event ( extension name, event name)
    $wpss->set_raw_message( 'wordpress', 'publish_post' );

    // Forward placeholders and data to WPSocialStreamer core
    $wpss->set_data( array(
        'POST_NAME' => get_the_title( $postID ),
        /* Every extension must contain the LINK field. Values: link or false */
        'LINK'   => get_permalink( $postID )
      )
    );

    // Generate and share the message
    $wpss->generate_and_share();
  }
}

/**
* Called when user posts a comment
*
* @param int $commentID
* @param string $approval_status: "spam" , 0 = disapproved, 1 = approved
*/
function wpss_wordpress_comment_post($commentID, $approval_status) {
  global $wpss;

  // Check if extension event is active
  // Function parameter:
  // 1. Extension name
  // 2. Event name
  if ( $wpss->is_active('wordpress', 'comment_post') ) {

    // Check if the comment is approved
    if ( $approval_status == 1 ) {
    
      // Load message for the given event ( extension name, event name)
      $wpss->set_raw_message( 'wordpress', 'comment_post' );

      // Get the comment
      $comment = get_comment( $commentID );

      // Set needed data
      $wpss->set_data( array(
          'POST_NAME' => get_the_title( $comment->comment_post_ID ),
          'CONTENT' => $comment->comment_content,
          /* Every extension must contain the LINK field. Values: link or false */
          'LINK'   => get_permalink( $comment->comment_post_ID )
        )
      );

      // Generate and share the message
      $wpss->generate_and_share();
    }
  }
}

How to extend the WPSocialStreamer Plugin without editing any files of the plugin?

The answer is pretty simple. The easiest way is to write your own small extension plugin. The plugin won't be really complicated. Create a new directory for your plugin in you wordpress plugin folder. Create the two files "MyWPSocialStreamer.php" and "MyWPSocialStreamerExtension.php". For the "MyWPSocialStreamer.php" file you could use this small template file.

/**
 * Plugin Name:   My Custom WPSocialStreamer Extension
 * Plugin URI:    http://exells.com
 * Description:   Adds new events to WPSocialStreamer
 * Version:       1.0.0
 * Author:        Exells Team
 * Author URI:    http://exells.com
*/

// No direct access!
if ( !defined('ABSPATH') ) exit;

// Include extensions
include ( 'MyWPSocialStreamerExtension.php' );

In the "MyWPSocialStreamerExtension.php" file you have to enter the filter and options for your own extension as described on the top. That’s all! As you can see it’s very easy to create own extensions.

Here is a summary of all steps you need to do in your extension:

• Create a small Wordpress Plugin
  • Create a directory for your WP Plugin
  • Create the two files: "MyWPSocialStreamer.php" and "MyWPSocialStreamerExtension.php"
  • Use the example for the "MyWPSocialStreamer.php"
  • Add the Events to the "MyWPSocialStreamerExtension.php" file.
• Add a filter to extend the extension array
• Create your extension array
• Add hooks and functions for events
• Implement event functions
  • Check if extension is active
  • Call set_raw_message function
  • Collect needed data that are needed to replace the placeholders
  • Forward data with placeholders to WPSocialStreamer core
  • Call the function ‘generate_and_share’. As the name of the function said it will generate a message and share it on Facebook immediately.
• Publish your extension to the community