Welcome to django-social-widgets’s documentation!

django-social-widgets is a Django app for easy embedding social network widgets and plugins into your site. Supports Facebook, Twitter, Google+, YouTube, Instagram and Pinterest.

Demo: https://creafz.github.io/django-social-widgets/index.html.

Requirements

  • Python 2.6 or 2.7
  • Django 1.5 or higher

Contents

Quickstart

  1. Install from PyPI:

    pip install django-social-widgets

  2. Add “social_widgets” to INSTALLED_APPS:

    INSTALLED_APPS = (
    ...
    "social_widgets",
    ...
)

  3. Load the social_widgets template library in every template you want to use it:

    {% load social_widgets %}

  4. Place {% social_widget_render %} code where you want to show the widget. For example if you want to show Facebook Likebox for Facebook Developers page put this code in your template:

    {% social_widget_render 'facebook/likebox.html' href='https://www.facebook.com/FacebookDevelopers' %}

Usage

Passing parameters

Parameter names for widgets are similar to the original parameters with only one change: they use underscore instead of hyphen. So for example if you need to set show-screen-name parameter for Twitter Follow Button, you should use code like this:

{% social_widget_render "twitter/follow_button.html" username="BillGates" show_screen_name=True %}

As a value for all parameters you can use a Python value like string, integer or Boolean, for example:

{% social_widget_render "facebook/likebox.html" app_id=12345678 href="https://www.facebook.com/FacebookDevelopers" show_border=True %}

JavaScript initialization code

All widgets (except Instagram badge) require JavaScript code to be loaded and executed before widget is rendered. django-social-widgets tracks and loads this code only once for each social network, so for example if you have 3 facebook widgets on one page, the Facebook JavaScript code will be loaded only once (when first widget is being rendered). If you already have this JavaScript code on the page (for example you have already loaded Facebook JavaScript SDK to use it with your own scripts) you can tell the django-social-widgets not to load it again. To do this, add noscript=True parameter to the {% social_widget_render %} tag, for example:

{% social_widget_render 'facebook/likebox.html' noscript=True href='https://www.facebook.com/FacebookDevelopers' %}

If you have multiple widgets on one page and you want to disable JavaScript loading for all of them you should add the noscript=True parameter to each call of {% social_widget_render %}.

Facebook Widgets

Likebox

  • Minimal code:

    {% social_widget_render "facebook/likebox.html" href="https://www.facebook.com/FacebookDevelopers" %}

  • Full code:

    {% social_widget_render "facebook/likebox.html" locale="en_US" app_id=12345678 href="https://www.facebook.com/FacebookDevelopers" height=300 colorscheme="light" force_wall=False header=True show_border=True show_faces=True stream=False width=300 %}

Parameters

Parameter Description Default
locale Used to determine the language of the widget. Django locale (en_US by default)
app_id Facebook Application ID. None
colorscheme The color scheme used by the plugin. Can be “light” or “dark”. “light”
force_wall For “place” Pages (Pages that have a physical location that can be used with check-ins), this specifies whether the stream contains posts by the Page or just check-ins from friends. False
header Specifies whether to display the Facebook header at the top of the plugin. True
height The height of the plugin in pixels. The default height varies based on number of faces to display, and whether the stream is displayed. With stream set to True and 10 photos displayed (via show_faces) the default height is 556px. With stream and show_faces both False, the default height is 63px. Varies, see left.
href The absolute URL of the Facebook Page that will be liked. This is a required setting. None
show_border Specifies whether or not to show a border around the plugin. True
show_faces Specifies whether to display profile photos of people who like the page. True
stream Specifies whether to display a stream of the latest posts by the Page. False
width The width of the plugin in pixels. Minimum is 292. 300

Follow Button

Parameters

Parameter Description Default
locale Used to determine the language of the widget. Django locale (en_US by default)
app_id Facebook Application ID. None
colorscheme The color scheme used by the plugin. Can be “light” or “dark”. “light”
href The Facebook.com profile URL of the user to follow. None
kid_directed_site If your web site or online service, or a portion of your service, is directed to children under 13 you must enable this “False”
layout Selects one of the different layouts that are available for the plugin. Can be one of “standard”, “button_count”, or “box_count”. See the FAQ for more details. “standard”
show_faces Specifies whether to display profile photos below the button (standard layout only). You must not enable this on child-directed sites . “False”
width The width of the plugin. The layout you choose affects the minimum and default widths you can use, please see the FAQ for more details. Depends on layout

Embedded Post

  • Minimal code:

    {% social_widget_render "facebook/embedded_post.html" href="https://www.facebook.com/FacebookDevelopers/posts/10151471074398553" %}

  • Full code:

    {% social_widget_render "facebook/embedded_post.html" locale="en_US" app_id=12345678 href="https://www.facebook.com/FacebookDevelopers/posts/10151471074398553" width=500 %}

Parameters

Parameter Description Default
locale Used to determine the language of the widget. Django locale (en_US by default)
app_id Facebook Application ID. None
href The absolute URL of the Post that will be embedded. None
width The pixel width of the post (between 350 and 750) 500

Activity Feed

  • Minimal code:

    {% social_widget_render "facebook/activity_feed.html" site="developers.facebook.com" %}

  • Full code:

    {% social_widget_render "facebook/activity_feed.html" locale="en_US" app_id=12345678 site="developers.facebook.com" action="likes, recommends" colorscheme="light" header=True height=300 linktarget="_blank" max_age=0 recommendations=False width=300 %}

Parameters

Parameter Description Default
locale Used to determine the language of the widget. Django locale (en_US by default)
app_id Facebook Application ID. None
action A comma-separated list of Open Graph action types to show in the feed. Any action type
app_id Display all actions associated with this app ID. This is usually inferred from the app ID you use to initiate the [JavaScript SDK]. None
colorscheme The color scheme used by the plugin. Can be “light” or “dark”. “light”
filter Allows you to filter which URLs are shown in the plugin. For example, if the site parameter is set to ‘www.example.com’ and the filterparameter was set to ‘/section1/section2’ then only pages which matched ‘http://www.example.com/section1/section2/*‘ would be included in the activity feed section of this plugin. This filter does not apply to any recommendations which may appear in this plugin (see recommendations setting). None
header Show the “Recent Activity” header above the feed. Can be “True” or “False” “True”
height The height of the plugin in pixels. 300
linktarget Determines what happens when people click on the links in the feed. Can be any of the standard HTML target values . “_blank”
max_age Limit the created time of articles that are shown in the feed. Valid values are 1-180, which represents the age in days to limit to. 0 (no limit)
recommendations Specifies whether to always show recommendations (Articles liked by a high amount of people) in the bottom half of the feed. Can be “True” or “False”. “False”
ref A label for tracking referrals which must be less than 50 characters and can contain alphanumeric characters and some punctuation (currently +/=-.:_). See the FAQ for more details. None
site The domain for which to show activity. Current domain
width The width of the plugin in pixels. 300

Recommendations Feed

  • Minimal code:

    {% social_widget_render "facebook/recommendations_feed.html" site="developers.facebook.com" %}

  • Full code:

    {% social_widget_render "facebook/recommendations_feed.html" locale="en_US" app_id=12345678 site="developers.facebook.com" ref="page_ref" action="likes, recommends" colorscheme="light" header=True height=300 linktarget="_blank" max_age=0 width=300 %}

Parameters

Parameter Description Default
locale Used for widget localization Django locale (en_US by default)
app_id Facebook Application ID. None
action A comma-separated list of Open Graph action types to show in the feed. Any action type
app_id Display all actions associated with this app ID. This is usually inferred from the app ID you use to initiate the [JavaScript SDK]. None
colorscheme The color scheme used by the plugin. Can be “light” or “dark”. “light”
header Show the “Recent Activity” header above the feed. Can be “True” or “False” “True”
height The height of the plugin in pixels. 300
linktarget Determines what happens when people click on the links in the feed. Can be any of the standard HTML target values . “_blank”
max_age Limit the created time of articles that are shown in the feed. Valid values are 1-180, which represents the age in days to limit to. 0 (no limit)
ref A label for tracking referrals which must be less than 50 characters and can contain alphanumeric characters and some punctuation (currently +/=-.:_). See the FAQ for more details. None
site The domain for which to show activity. Current domain
width The width of the plugin in pixels. 300

Share Button

  • Minimal code:

    {% social_widget_render "facebook/share_button.html" href="developers.facebook.com" %}

  • Full code:

    {% social_widget_render "facebook/share_button.html" locale="en_US" app_id=12345678 href="developers.facebook.com" layout="none" %}

Parameters

Parameter Description Default
locale Used for widget localization Django locale (en_US by default)
app_id Facebook Application ID. None
href The absolute URL of the Post that will be embedded. None
layout Share button layout type None

Twitter Widgets

Follow Button

  • Minimal code:

    {% social_widget_render "twitter/follow_button.html" username="BillGates" %}

  • Full code:

    {% social_widget_render "twitter/follow_button.html" username="BillGates" show_screen_name=True show_count=False size="medium" dnt=False %}

Parameters

Parameter Description Default
username Username to follow (without @) None
lang Language of the follow button. Available languages: English (en), French (fr), German (de), Italian (it), Spanish (es), Korean (ko) and Japanese (ja). en
width Width of the Follow Button None
align Alignment of the Follow Button. Can either be “left” or “right”. None
show_screen_name The user’s screen name shows up by default, but you can opt not to show the screen name in the button. True
size The size of the button can render in either “medium”, which is the default size, or in “large” - which is the larger button. “medium”
dnt Enable or disable Do Not Track feature. More information . False

Share Button

  • Minimal code:

    {% social_widget_render "twitter/share_button.html" href="http://www.twitter.com" %}

  • Full code:

    {% social_widget_render "twitter/share_button.html" href="http://www.twitter.com" username="BillGates"  %}

Parameters

Parameter Description Default
username Username to use for share None
lang Language of the follow button. Available languages: English (en), French (fr), German (de), Italian (it), Spanish (es), Korean (ko) and Japanese (ja). en
href Url to share None
hashtag Hashtags to add to post None
related Related account to this post None
count Widget counter layout “none”

Google+ and YouTube Widgets

Google+ Person Badge

  • Minimal code:

    {% social_widget_render "google/plus_person_badge.html" href="https://plus.google.com/+SergeyBrin" %}

  • Full code:

    {% social_widget_render "google/plus_person_badge.html" language="en-US" href="https://plus.google.com/+SergeyBrin" layout="portrait" showcoverphoto=True showtagline=True theme="light" width=300 %}

Parameters

Parameter Description Default
language Language of the Google+ badge “en-US”
href URL to the Google+ page None
layout Sets the orientation of the badge. Can either be “landscape” or “portrait”. “portrait”
showcoverphoto Displays the cover photo in the badge if set to true and the photo exists True
showtagline Displays the user’s tag line if set to true. True
theme The color theme of the badge. Use dark when placing the badge on a page with a dark background. “light”
width The pixel width of the badge to render. The following ranges are valid: Portrait layout (180-450 pixels), Landscape layout (273-450 pixels) 300

Google+ Page Badge

  • Minimal code:

    {% social_widget_render "google/plus_page_badge.html" href="https://plus.google.com/110967630299632321627" %}

  • Full code:

    {% social_widget_render "google/plus_page_badge.html" language="en-US" href="https://plus.google.com/110967630299632321627" layout="portrait" showcoverphoto=True showtagline=True theme="light" width=300 %}

Parameters

Parameter Description Default
language Language of the Google+ badge “en-US”
href URL to the Google+ page None
layout Sets the orientation of the badge. Can either be “landscape” or “portrait”. “portrait”
showcoverphoto Displays the cover photo in the badge if set to true and the photo exists True
showtagline Displays the user’s tag line if set to true. True
theme The color theme of the badge. Use dark when placing the badge on a page with a dark background. “light”
width The pixel width of the badge to render. The following ranges are valid: Portrait layout (180-450 pixels), Landscape layout (273-450 pixels) 300

Google+ Community Badge

  • Minimal code:

    {% social_widget_render "google/plus_community_badge.html" href="https://plus.google.com/communities/113527920160449995981" %}

  • Full code:

    {% social_widget_render "google/plus_community_badge.html" language="en-US" href="https://plus.google.com/communities/113527920160449995981" layout="portrait" showphoto=True showowners=False showtagline=True theme="light" width=300 %}

Parameters

Parameter Description Default
language Language of the Google+ badge “en-US”
href URL to the Google+ page None
layout Sets the orientation of the badge. Can either be “landscape” or “portrait”. “portrait”
showphoto Displays the community profile photo if set to true and the photo exists. True
showowners Displays a list of community owners if set to true. False
showtagline Displays the user’s tag line if set to true. True
theme The color theme of the badge. Use dark when placing the badge on a page with a dark background. “light”
width The pixel width of the badge to render. The following ranges are valid: Portrait layout (180-450 pixels), Landscape layout (273-450 pixels) 300

YouTube Subscribe Button

  • Minimal code:

    {% social_widget_render "google/youtube_subscribe_button.html" channel="GoogleDevelopers" %}

  • Full code:

    {% social_widget_render "google/youtube_subscribe_button.html" channel="GoogleDevelopers" theme="default" layout="default" count="default" %}

Parameters

Parameter Description Default
language Language of the button “en-US”
channel The name of the channel associated with the button None
layout The format for the button. Can either be “default” or “full” “default”
theme Specifies the color scheme to use for the button. Can either be “default” or “dark” “default”
count Indicates whether the button displays the number of subscribers that the channel has. Can either be “default” or “count”. “default”

Google+ Share Button

  • Minimal code:

    {% social_widget_render "google/plus_share_button.html" href="https://www.google.com" %}

  • Full code:

    {% social_widget_render "google/plus_share_button.html" language="en-US" href="https://plus.google.com/communities/113527920160449995981" layout="portrait" showphoto=True showowners=False showtagline=True theme="light" width=300 %}

Parameters

Parameter Description Default
language Language of the Google+ badge “en-US”
href URL to share None
annotation Widget style “none”

Instagram Widgets

Instagram Badge

  • Minimal code:

    {% social_widget_render "instagram/badge.html" username="nike" %}

  • Full code:

    {% social_widget_render "instagram/badge.html" size=32 username="nike" %}

Parameters

Parameter Description Default
username Instagram username None
size Size of the badge in pixels. Can either be 16, 32 or 64. 32

Pinterest Widgets

Follow Button

  • Full code:

    {% social_widget_render "pinterest/follow_button.html" href="http://www.pinterest.com/pinterest/" fullname="Pinterest" %}

Parameters

Parameter Description Default
href Pinterest User URL None
fullname User fullname that will be shown on the button None

Pin Widget

  • Full code:

    {% social_widget_render "pinterest/pin_widget.html" href="http://www.pinterest.com/pin/99360735500167749/" %}

Parameters

Parameter Description Default
href Pinterest Pin URL None

Profile Widget

  • Minimal code:

    {% social_widget_render "pinterest/profile_widget.html" href="http://www.pinterest.com/pinterest/" %}

  • Full code:

    {% social_widget_render "pinterest/profile_widget.html" href="http://www.pinterest.com/pinterest/" pin_scale_width=80 pin_scale_height=320 pin_board_width=400 %}

Parameters

Parameter Description Default
href Pinterest User URL None
pin_scale_width Width of a single pin 80
pin_scale_height Height of a singe pin 320
pin_board_width Width of the widget 400

Board Widget

  • Minimal code:

    {% social_widget_render "pinterest/board_widget.html" href="http://www.pinterest.com/pinterest/pin-pets/" %}

  • Full code:

    {% social_widget_render "pinterest/board_widget.html" href="http://www.pinterest.com/pinterest/pin-pets/" pin_scale_width=80 pin_scale_height=320 pin_board_width=400 %}

Parameters

Parameter Description Default
href Pinterest User URL None
pin_scale_width Width of a single pin 80
pin_scale_height Height of a singe pin 320
pin_board_width Width of the widget 400

Changelog

Version 0.3.0 - 2015-09-12

  • Add Facebook, Twitter and Google+ share buttons

Version 0.2.1 - 2014-11-03

  • Minor setup.py fixes

Version 0.2.0 - 2014-11-03

  • Updated tests
  • Added an example project
  • Added PyPi, Read The Docs, Travis CI and Coveralls badges

Version 0.1.2 - 2014-10-13

  • Documentation updates

Version 0.1.1 - 2014-10-11

  • Updated Requirements section
  • Removed unused code
  • Added Travis CI config file
  • Added tox config file

Version 0.1 - 2014-10-08

  • First release