Package: collective.simplesocial
Introductioncollective.simplesocial exposes some basic features of Facebook’s
API for use within Plone.The goals of this Plone add-on product are to:Provide the basic infrastructure required as a foundation for custom
Facebook API integrations. (e.g. application ID configuration, inclusion
of needed code snippets)Expose selected high-value prepackaged components of Facebook’s API without
requiring deep knowledge of the inner workings of the API.Current features include:Like ButtonLike Box PortletFeed Form PortletPost to Facebook Fan PageCustom Facebook Connect IntegrationCompatibilitycollective.simplesocial has been tested with Plone 3.x and Plone 4.0.It has been tested with Firefox 3.5, Safari 4, and Internet Explorer 7 and 8.
Internet Explorer 6 is no longer supported.collective.simplesocial is not compatible with sc.social.like.Creating a Facebook ApplicationBefore you can use the features of collective.simplesocial, you need to create
a Facebook application. To do so, follow these steps:Go to theFacebook Developer application. If prompted, allow it access to
your profile.Click theSet Up New Applicationbutton and fill out the form.Take note of theApplication IDthat is displayed.In the Facebook application’s settings, click on theConnecttab.
Enter the URL of the site into theConnect URLfield.Return to your Plone site, and enter the Facebook application ID in the
Facebook Settings control panel. Then use the provided button to log into
Facebook and connect with your Facebook application.Like ButtonA FacebookLike buttonallows visitors to establish a lasting connection
between their Facebook profile and a piece of content on your site.PrerequisitesTo add Like buttons to your site, first follow the instructions forCreating a
Facebook Applicationabove.Adding Like ButtonsGo to Site Setup.Click Facebook Settings.Log into Facebook using the provided button if you have not done so already.On the Like Button tab, make sure that “Display Like buttons on this site”
is checked.Choose the content types where you want Like buttons to appear by default.Set the display options for your Like buttons.Save your settings.Enabling and Disabling Like ButtonsIn addition to choosing the content types where Like buttons will be displayed,
you can also turn the Like button on or off for a particular piece of content.
To do so, browse to the content item, and select “Show Like Button” or “Hide
Like Button” from the Actions menu.Customizing Open Graph MetadataTo find out about the piece of content that is being liked, Facebook reads
metadata from Open Graph tags in the head of the page. By default, Simple
Social provides metadata based on these fields:The title of the content itemThe URL of the content itemThe content item’s description, if it provides oneThe content item’s preview image, if it provides one, or the site logoThe site nameThe Facebook application IDAll content items other than the site’s home page are listed as type “article.”
The site’s home page is listed as type “website.”The Open Graph metadata can be customized on a per-content type basis by
registering an adapter that provides
collective.simplesocial.likebutton.interfaces.IOpenGraphProvider for the
content type’s interface. In cases where more than one content type provides
the same interface, the adapter can be named to match the desired portal type.
For an example, see the default implementation in
collective.simplesocial.likebutton.opengraph.DefaultOpenGraphProvider.Like Box PortletFacebook provides a basicLike Boxwidget which can be used to promote
a Facebook Page by prompting visitors to your website to like the Page and
allowing them to view the Page’s activity stream and fans.
collective.simplesocial allows insertion of a Like Box as a portlet.PrerequisitesTo use the Like Box portlet, you must complete the steps in the section onCreating a Facebook Application. You also need a Facebook Page.
Take note of the URL of the Page, and enter in when you create the portlet.Adding a Like BoxNavigate to the location in the site where you want to add the portlet.Click ‘Manage portlets’.Click on the dropdown to add a portlet to the column where you want
the like box to appear, and select ‘Facebook Like Box’.Paste in the URL of the Facebook Page you want to promote.You may configure whether or not an activity stream appears, the number of
fan connections to display, and the width of the like box.Click save and return to the location where you assigned the portlet to
view the Like box.Feed Form PortletFacebook allows sites to publish messages to users’ activity streams using
thestream.publishAPI method.collective.simplesocial provides a “Feed Form” portlet. This allows you to
configure a dialog which will pop up on page load and prompt the user to post
a message to his or her Facebook feed.  This can be used to prompt a visitor to
your Plone site to publicize some action that they took on the site.  For
example, you could add this portlet to the thank you page of a PloneFormGen
form, asking the user to tell his or her friends about the site.To see a demonstration of the feed form portlet in use, watch thescreencast.PrerequisitesTo use the Feed Form portlet, you must first complete the steps in the
section onCreating a Facebook Application.Adding a Feed FormNavigate to the location in the site where you want to add the portlet.Click ‘Manage portlets’.Click on the dropdown to add a portlet to the column where you want
the feed form to appear, and select ‘Facebook Feed Form’.Edit the settings as prompted.  When finished, click Save.Return to the location where you assigned the portlet to view the feed
form.If a visitor to a page with a feed form is not logged into Facebook, then the
feed form will not appear automatically.  Instead, a message will be shown
along with a Facebook login button.  Clicking this button will allow the
visitor to log into Facebook, after which the feed form will be displayed.Customizing the Feed AttachmentWhen a user submits a feed form, collective.simplesocial sends along an
attachment to Facebook with information about the content item where the
feed form was displayed. By default, this attachment contains the following
information:The title of the content itemThe URL of the content itemThe content item’s description, if it provides oneThe content item’s tile image, if it provides one, or the site logoThese defaults are provided by the DefaultFeedFormDataProvider adapter. It
is possible to override the defaults globally or for a particular content type
by registering an adapter that provides the IFeedFormDataProvider interface.
This interface provides methods for getting the attachment for the current
context and for overriding the settings specified in the portlet assignment.
For more information, see
collective.simplesocial.feedform.facebookfeedform.IFeedFormDataProvider and the
documentation for thestream.publishmethod andstream attachmentobject.Post to Facebook Fan PageThis feature adds a “Post to Fan Page” link to the document actions area of a
Plone page.  The link only shows up for Managers.The string “utm_source=facebook” will be added to the page URL, so that visitors
who arrive at your site via the posted link can be tracked in Google Analytics.PrerequisitesTo use the Post to Facebook Fan Page feature, you must first complete the steps
in the section onCreating a Facebook Application.Configuring the ‘Post to Fan Page’ featureGo to Site Setup.Click Facebook Settings.Log into Facebook using the provided button if you have not done so already.On the Post to Page tab, make sure that “Allow site managers to post updates
to a Facebook Page” is checked.Select the Facebook page you want to post to. Click Save.Now the ‘Post to Fan Page’ link should show up when you are logged in. To post
to Facebook, click on the link.  You will be prompted to confirm the message
that will be posted.Custom Facebook Connect IntegrationThis product provides the basic pieces needed to integrate with Facebook using
customXFBMLand/or theFacebook JavaScript SDK. These include:The Facebook Settings control panel for configuring your application ID.The SimpleSocial javascript library, which wraps some of the most common
calls to the Facebook API and provides a standard framework for queuing
and executing functions when the Facebook javascript library has loaded.A Facebook initialization viewlet in the portaltop viewlet manager, which
connects to Facebook using the application ID provided in the Facebook
Settings control panel.With these pieces in place and a correct application ID, you should be
able to use XFBML wherever you like in Plone templates. You can also
make use of the Facebook Javascript API. (See the example below for
correct usage.)Miscellaneous TipsThe TAL parser likes to complain about mismatched tags when using tags with
the ‘fb’ XML namespace.  You may need to escape such tags and include them
with a tal:replace or put them in a separate file and include them via a
browser view method that reads that file.The Facebook javascript library is loaded asynchronously, which means that
Facebook API calls cannot be made immediately when the page is loaded.
To address this issue, the SimpleSocial javascript library implements a
queue that stores functions that depend on the Facebook API until the API
is fully loaded. It then executes all of the functions in the queue in the
order that they were inserted. Functions passed to the queue after the
Facebook API has loaded are executed immediately.SimpleSocial.queue behaves like a javascript array. To add a function to
the queue, use the push method:SimpleSocial.queue.push(function () {
  // Do something using the Facebook API.
});Use logic like the following to do something different depending on whether
or not the user is already logged into Facebook and connected to your
application:SimpleSocial.queue.push(function () {
  FB.getLoginStatus(function (response) {
    if (response.session) {
      // The user is logged in and connected.
    } else {
      // The user is not logged in or is not connected
      // to your application.
    }
  });
});For more information, see the documentation forFB.getLoginStatus.Additional Facebook API ResourcesFacebook Developer DocumentationFacebook JavaScript SDKSocial PluginsXFBMLCreditscollective.simplesocial was developed by David Glick forGroundwire(formerly ONE/Northwest).  Matt Yoder has also contributed.Thanks toNouvellerfor the Facebook icon.Changelog1.8 (2013-11-12)Use new prefered location for getSite
[encolpe]Plone4.3 changes
[sureshvv]Added channel file and updated SDK initialization.
[yomatters]Fixed a permission error when enabling and disabling the Like button.
[yomatters]1.7 (2011-12-12)Use OAuth 2.0 for authentication.
[yomatters]Resolved Chameleon error by properly escaping init javascript.
[yomatters]Track likes and unlikes in Google Analytics using social media tracking.
[yomatters]Moved javascript generation from fb_init.pt to view to fix Chameleon warning
[swampmonkey]1.6 (2011-05-31)Added a like and unlike tracking plugin for collective.googleanalytics.
[yomatters]1.5 (2011-05-06)Updated instructions for creating a Facebook app.
[yomatters]Added the ability to toggle on and off the display of profile pictures in the
Like box.
[yomatters]1.5b2 (2011-04-13)Fixed an issue with the Like button that prevented content from being
copied and pasted.
[yomatters]Use simplejson/json to resolve issues with JSON escaping.
[yomatters]1.5b1 (2011-02-23)Hid the portlet header for the Like box portlet.
[yomatters]Added an adapter for looking up the image that gets sent to Facebook to make
it more easily customizable.
[yomatters]Added ref attribute to Like button.
[yomatters]Added support for the Like button and Open Graph meta tags.
[yomatters]Merged profiles to simplify upgrades.
[yomatters]Changed control panel form to use z3c.form.
[yomatters]Added height option to Like box portlet.
[yomatters]Removed width restriction on Like box because Facebook no longer enforces it.
[yomatters]Updated Like box portlet options to match Facebook’s options.
[yomatters]Added a a data provider for PloneFormGen thank you pages that pulls data
for the attachment from the form.
[yomatters]Fixed an error related to missing action links.
[yomatters]Fixed position of modal dialogs in IE7 with the Sunburst theme.
[yomatters]1.4 (2010-09-21)Removed user message option from feed form because Facebook no longer
supports it.
[yomatters]Dropped support for Internet Explorer 6 because Facebook no longer
supports it.
[yomatters]Fixed escaping bug in the feed form portlet’s action title.
[yomatters]Replaced fan box with a like box. The like box portlet is rendered
using XFBML, so the basic Facebook support profile is now a dependency.
[yomatters]Took advantage of the Facebook’s new Javascript SDK.
[yomatters]Provided defaults for fanbox portlet thus make it possible to assign it using
portlets.xml GS file.
[piv]1.3 (2010-06-02)Also catch NotFound when trying to look up ‘image_tile’.
[davisagli]Added a feed form tracking plugin for collective.googleanalytics.
[yomatters]Added the option to only show the feed form after a save.
[yomatters]Changed Facebook fanbox portlet HTML to meet Plone standards, fixes #1.
[jaroel]1.2 (2010-04-06)Fixed a unicode decode bug in the JSON serializer.
[yomatters]1.1 (2010-03-26)Added the ‘Post to Fan Page’ feature.
[davisagli]Stripped line breaks from the description in the default feed form adapter
to avoid breaking the javascript.
[yomatters]Added a view to resize the site logo to the size that Facebook requires.
[yomatters]Added an adapter interface so that we can override the feed form portlet
and attachment settings on a per-site or per-content-type basis.
[yomatters]1.0 (2009-12-22)Add z3c.autoinclude Plone plugin entry point.
[davisagli]Fix control panel authenticator to work in Plone 4.
[davisagli]Added a jq() wrapper to the feature loader initialization call so that it
doesn’t happen until the DOM is fully loaded.
[yomatters]Removed bogus dependency of the Fan Box profile on the Basic Facebook Connect
integration profile.
[davisagli]1.0b1 (2009-08-13)Initial release.
[davisagli]