Idea Melt

Focus Mode

Apps

Suggested Follow

Description

The Suggested Follow app provides a really easy way to increase engagement on your site by suggesting the right people for your users to follow. We use various algorithms based on a user's social graph to determine which people to suggest.

Features

Suggested Follow makes your life easy.

  • Takes care of making API requests from the client
  • Checks to see if the user is being followed on initialization
  • Adds and removes classes as appropriate to make your life easier
  • Provides default styles that can be turned on and off by a simple boolean
  • Offers an extremely easy way to customize class names, and the whole template for maximum flexiblity
  • Optimizes network requests for maximum efficiency and least amount of data sent over the wire
  • Takes care of click events and API requests for the follow button
  • Automatically refreshes when a user is followed for an endless stream of suggested users to follow
Scripts

Include the following script in your HTML

<script src="http://www.ideamelt.com/static/apps/3.0/im.suggested.js"></script>

NOTE: jQuery is dependency

Initialize

To initialize Suggested Follow, all you need to do is execute the init function with your IdeaMelt API KEY. You also need to provide it a target. This is where the suggested users to follow will be injected.

IdeaMelt.Apps.Suggested.init({
    api_key: 'API_KEY',
    target: 'ANY VALID jQUERY SELECTOR'
})

Please make sure you do this as soon as possible. Don't worry, the library takes care of document.ready

Config

There are four config settings you can set when initializing the app

api_key
required
string
your IdeaMelt API_KEY
target
required
selector
any valid jQuery selector that can be used to find the element within which the suggestions will be appended.
NOTE: If an array of targets are returned with the selector you specify, only the first target will be injected in.
EXAMPLE: target: '#my-favourite-div'
style
optional
boolean
if true, basic styling will be automatically injected. otherwise, elements will remain completely unstyled.
DEFAULT: false
quantity
optional
integer
the number of suggested users to display
DEFAULT: 3
Default Template & Classes

The app's template along with its classes are designed to fit most use cases. The easiest way to make the app fit your styling is by adding your own CSS. Have a look at the HTML for a single item and how elements in the item are structured by default.

<div class="im-suggested-item">
    <a class="im-suggested-itemLink" href="USER_URL">
        <img class="im-suggested-itemAvatar" src="AVATAR"></img>
        <div class="im-suggested-itemTitle">TITLE</div>
    </a>
    <a class="im-suggested-itemFollow" href="JavaScript:void(0);">
        Follow
    </a>
</div>

Visually, this is the structure of the HTML:

Custom Classes

If you've already set up your CSS and you don't want to add/manage additional classes, don't worry! You can easily change class names too!

All class names are stored in one object:

IdeaMelt.Apps.Suggested.Class = {
    item: 'im-suggested-item',
    itemAvatar: 'im-suggested-itemAvatar',
    itemTitle: 'im-suggested-itemTitle',
    itemLink: 'im-suggested-itemLink',
    itemFollow: 'im-suggested-itemFollow',
    itemDisabled: 'im-suggested-itemDisabled',
}

Change any value before initializing the app and the classes injected will change accordingly.

IdeaMelt.Apps.Suggested.Class.itemTitle = "my-custom-title-class";

You can also attach multiple classes to elements by separating class names with spaces.

IdeaMelt.Apps.Suggested.Class.item = "class1 class2 class3";

NOTE: The click event for following a user is always attached to the value of the itemFollow key!

IdeaMelt.Apps.Suggested.Class.itemFollow = "click-event-always-attached-to-me";

NOTE: itemDisabled is used when the script is busy making HTTP requests, so be sure to use it!

Custom Template

If you don't like the default template, don't worry, you can easily change it completely!

The template used when compiling the HTML for each item is stored here:

IdeaMelt.Apps.Suggested.userTemplate =
    '<div class="{{item}}">' +
        '<a class="{{itemLink}}" href="{{this.url}}">' +
            '<img class="{{itemAvatar}}" src="{{this.avatar}}"></img>' +
            '<div class="{{itemTitle}}">{{this.title}}</div>' +
        '</a>' +
        '<a class="{{itemFollow}}" href="JavaScript:void(0);">' +
            'Follow' +
        '</a>' +
    '</div>';

To change the template, simply override this value with stringified HTML of your choosing. But before you do, there's a few things you should know:

NOTE:The template must be a string.

NOTE:Do NOT hard-code classes into your template. Since we use class names to find, retrieve, and manipulate elements, you must have the actual class name stored in the Suggested.Class object. In the template, demarcate them using two curly braces and their corresponding key from the Suggested.Class object. Refer to the previous section for more information.

NOTE:You do not have to use all the key:value pairs in the Suggested.Class object and you are more than welcome to add as many more as you need.

NOTE:Your template must contain {{itemFollow}} as a class for some element. This is the class on which follow click events are attached and executed. This will also be the same element on which the {{itemDisabled}} class is added.

NOTE:To inject variable data into the template, use the same double curly braces format. Each user comes standard with three data points. They are {{this.url}}, {{this.title}}, and {{this.avatar}}. Use them to put user data wherever you want in the template.