.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt =================================== EXT: Post TYPO3 records to Facebook =================================== :Created: 2010-02-18T17:33:18 :Changed by: Manfred Egger :Changed: 2012-03-26T12:53:31.130000000 :Classification: bc_post2facebook :Description: The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) see more: http://wiki.typo3.org/doc_template#tags ---- :Keywords: facebook, forEditors, forAdmins :Author: Bluechip Software :Email: http://www.bluechip.at :Info 4: :Language: en |img-1| |img-2| EXT: Post TYPO3 records to Facebook - bc\_post2facebook .. _EXT-Post-TYPO3-records-to-Facebook: EXT: Post TYPO3 records to Facebook =================================== Extension Key: bc\_post2facebook Language: en Keywords: facebook, forEditors, forAdmins Copyright 2000-2010, Bluechip Software, < http://www.bluechip.at> This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.org .. _Table-of-Contents: Table of Contents ----------------- `EXT: Post TYPO3 records to Facebook 1 <#__RefHeading__8932_453505048>`_ **`Introduction 3 <#__RefHeading__8934_453505048>`_** `What does it do? 3 <#__RefHeading__8936_453505048>`_ `Screenshots 3 <#__RefHeading__8940_453505048>`_ **`Users manual 5 <#__RefHeading__8946_453505048>`_** `Installation 5 <#__RefHeading__8948_453505048>`_ `Quickstart 5 <#__RefHeading__8950_453505048>`_ `1. Create a Facebook App 5 <#__RefHeading__13660_453505048>`_ `2. Request authorization code 5 <#__RefHeading__13662_453505048>`_ `3. Complete the extension configuration 6 <#__RefHeading__13664_453505048>`_ `4. Optional: add the application to your pages 6 <#__RefHeading__13666_453505048>`_ **`Administration 7 <#__RefHeading__8952_453505048>`_** `Page / User TSconfig reference 7 <#__RefHeading__8954_453505048>`_ `mod.web\_modules.bc\_post2facebook 7 <#__RefHeading__13668_453505048>`_ `Configuration of the TYPO3 records 7 <#__RefHeading__8956_453505048>`_ **`Usage 9 <#__RefHeading__9010_453505048>`_** **`Tutorial 10 <#__RefHeading__9012_453505048>`_** **`Known problems 12 <#__RefHeading__9014_453505048>`_** **`To-Do list 13 <#__RefHeading__9016_453505048>`_** **`ChangeLog 14 <#__RefHeading__9018_453505048>`_** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ This extension posts records out from TYPO3 to Facebook. This extension has been created by `Bluechip Software GmbH `_ . An overview for editors can be found on `http://www.bluemedia.at/post2facebook/ `_ (in german). `|img-3| `_ .. _Screenshots: Screenshots ^^^^^^^^^^^ **Backend wizard:** |img-4| **Succesfull wall post on Facebook:** |img-5| .. _Users-manual: Users manual ------------ .. _Installation: Installation ^^^^^^^^^^^^ Install the extension via the extension manager and fill out the necessary fields in the extension config. .. _Quickstart: Quickstart ^^^^^^^^^^ .. _1-Create-a-Facebook-App: 1. Create a Facebook App """""""""""""""""""""""" Go to `http://www.facebook.com/developer `_ then create new application and fill in the necessary information .. _2-Request-authorization-code: 2. Request authorization code """"""""""""""""""""""""""""" First you need to know which permissions you have to request to get a working extension. Here are some examples: - post to the users wall: publish\_stream - post to a page-wall: publish\_stream,manage\_pages - post to a page- or group-wall: publish\_stream,manage\_pages,user\_groups Get a full listing of all available permission flags at `http://developers.facebook.com/docs/authentication/permissions/ `_ As of the former “offline\_access” permission is deprecated and will be removed in future, you shouldn't add this permission to your config anymore. Instead of this, the extension extends the expiration of the auth token every time it is used. There are two ways to get the authorization code: Via the wizard in the extension configuration Manually (usefull if you have to configure the plugin for several users) .. _Request-authorization-code-via-the-wizard: Request authorization code via the wizard ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You need a valid extension configuration. For this you have to insert the application ID, the application secret and the application Url of your previously created Facebook App and the permissions. If all is well configured you get a warning message, that there is no auth token. You only have to click on the provided link and allow the application to access the needed data. |img-6| Then you are redirected to your applications canvas page. The next step is similar to the manual code request. .. _Request-authorization-code-manually: Request authorization code manually ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Goto https://www.facebook.com/dialog/oauth?client\_id=& redirect\_uri=&scope=&state= After you login and allow the application you will redirect to your redirect url with the authorization code like ?code=AQCXL0ahfaadfh[...]Uh3C6FoUORw#\_=\_ Copy the code at the right side of “=” sign (highlighted in red) to paste in extension configuration Note: If you remove this application from your profile application setting, and you add the application again then you have to generate this code again. **Note:** Allthough the auth code expiration is extended everytime you use the extension, there are some reasons why the token can get invalid: The token expires after expire time (only if you rarely use the extension) Yout/the user changes her password which invalidates the access token You/the user de-authorizes your app In these cases you have to generate the token again. .. _3-Complete-the-extension-configuration: 3. Complete the extension configuration """"""""""""""""""""""""""""""""""""""" Fill out all necessary fields in the extension configuration. To post TYPO3 records you have to configure the TypoScript of the extension for the database table. A standard configuration for tt\_news is included, for further information have a look at the Administration section below. .. _4-Optional-add-the-application-to-your-pages: 4. Optional: add the application to your pages """""""""""""""""""""""""""""""""""""""""""""" If you want to post to your pages you have to add your application to your page. .. _Administration: Administration -------------- .. _Page-User-TSconfig-reference: Page / User TSconfig reference ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Most of the settings made in the extension configuration can be overridden via Page and User Tsconfig. .. _mod-web-modules-bc-post2facebook: mod.web\_modules.bc\_post2facebook """""""""""""""""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _appId: appId ~~~~~ .. container:: table-row Property appId Data type String Description Alternative id of your Facebook App .. _secret: secret ~~~~~~ .. container:: table-row Property secret Data type String Description Alternative secret of your Facebook App .. _authToken: authToken ~~~~~~~~~ .. container:: table-row Property authToken Data type String Description Alternative authentication token for your Facebook App .. _pageId: pageId ~~~~~~ .. container:: table-row Property pageId Data type String Description Alternative default id of the Facebook page you want to post to .. _postAsPage: postAsPage ~~~~~~~~~~ .. container:: table-row Property postAsPage Data type String keyword Description Set to “yes” to enable posting as page Set to “no” to post as user .. _groupId: groupId ~~~~~~~ .. container:: table-row Property groupId Data type String Description Alternative default id of the Facebook groupyou want to post to .. _webUrl: webUrl ~~~~~~ .. container:: table-row Property webUrl Data type String Description Alternative base url for images and links .. _displayListing: displayListing ~~~~~~~~~~~~~~ .. container:: table-row Property displayListing Data type list Description With this option you can specify which options the user has to select the location where to post to Facebook. There are the following options available: - **all:** all available pages, groups and the profile are shown - **none:** the user has no options. In this case the pageId or groupId are used as target. If both are not set, the profile is used - **profile:** show the option to post to the profile - **pages:** show all pages - **groups:** show all groups **Example:** :: mod.web_modules.bc_post2facebook.displayListing = groups, profile The options “pages” and “groups” can be configured more specific: you can add a list of page or group ids between two curly brackets. **Example:** :: mod.web_modules.bc_post2facebook.displayListing = groups{1234, 5678}, pages{9876, 5432} .. _config: config ~~~~~~ .. container:: table-row Property config Data type Array Description Configuration of the TYPO3 records where posting is enabled .. _config-record-table-name: config.record\_table\_name ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property config.record\_table\_name Data type Array Description Configuration of one record .. _config-record-table-name-config-picture-field: config.record\_table\_name.\_config.picture\_field ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property config.record\_table\_name.\_config.picture\_field Data type String Description If you want to post an image to Facebook, specify, in which field of the TYPO3 record the image is saved .. _config-record-table-name-config-picture-as-upload: config.record\_table\_name.\_config.picture\_as\_upload ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property config.record\_table\_name.\_config.picture\_as\_upload Data type Boolean Description If set, pictures are not posted with their urls but as uploads (useful for events) .. _config-record-table-name-config-postAs: config.record\_table\_name.\_config.postAs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property config.record\_table\_name.\_config.postAs Data type String Description Specify in which path of the Facebook Graph API you want to post. To post to the wall enter “feed”, to post to the events enter “events”. More informations at `http://developers.facebook.com/docs/reference/api/ `_ .. _config-record-table-name-api-items: config.record\_table\_name.api\_items ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property config.record\_table\_name.api\_items Data type CObj Description Use the name of the GraphAPI item as key and configure it as Cobject. **Example:** :: picture = IMG_RESOURCE picture { file { import = uploads/pics/ import.field = image import.listNum.stdWrap.data = register: picture_num maxW = 120 maxH = 120 } } .. ###### END~OF~TABLE ###### [tsconfig:mod.web\_modules.bc\_post2facebook] .. _Configuration-of-the-TYPO3-records: Configuration of the TYPO3 records ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The extension offers the possibility to post almost all TYPO3 records to almost all channels on Facebook, which are available via the GraphAPI. The extension already comes with a configuration for tt\_news, use this as reference. To make the extensions wizard available for other records, follow the steps below: .. _generated: ((generated)) """"""""""""" .. _1-Add-a-new-field-tx-bcpost2facebook-facebook-id-to-the-database-table-of-your-record: 1. Add a new field “tx\_bcpost2facebook\_facebook\_id“ to the database table of your record ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Example:** :: CREATE TABLE tt_news ( tx_bcpost2facebook_facebook_id tinytext ); .. _2-Add-the-TCA-configuration-to-your-extensions-ext-tables-php-or-the-extTables-php-located-in-typo3conf: 2. Add the TCA configuration to your extensions ext\_tables.php or the extTables.php located in typo3conf ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Example:** :: $tempColumns = array( 'tx_bcpost2facebook_facebook_id' => array( 'exclude' => 1, 'label' => 'LLL:EXT:bc_post2facebook/locallang_db.xml:tt_news.tx_bcpost2facebook_facebook_id', 'config' => array( 'type' => 'user', 'userFunc' => 'tx_bc_post2facebook_fieldtype->user_TCAform_facebook', 'wizards' => Array( '_PADDING' => 2, 'link' => Array( 'type' => 'popup', 'title' => 'Post News to Facebook', 'icon' => 'EXT:bc_post2facebook/res/icon_wizard.png', 'script' => 'EXT:bc_post2facebook/lib/class.tx_bc_post2facebook_wizard.php', 'JSopenParams' => 'height=630,width=650,status=0,menubar=0,scrollbars=1', ), ), ), ), ); t3lib_div::loadTCA('tt_news'); t3lib_extMgm::addTCAcolumns('tt_news', $tempColumns, 1); t3lib_extMgm::addToAllTCAtypes('tt_news', 'tx_bcpost2facebook_facebook_id;;;;1-1-1'); .. _3-Add-the-configuration-for-your-record-to-page-or-user-Tsconfig: 3. Add the configuration for your record to page or user Tsconfig ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Example:** :: mod.web_modules.bc_post2facebook { config { tt_news { _config { picture_field = image postAs = feed } name = TEXT name.field = title link = TEXT link { dataWrap = {field:_url}| typolink { returnLast = url additionalParams { field = uid wrap = &tx_ttnews[tt_news]=| } } } description = TEXT description { field = short ifEmpty { field = bodytext crop = 300 | ... | 1 } stripHtml = 1 } } } } .. _Usage: Usage ----- If the button for the wizard is well configured it will show up in the edit form of your record. If the record is already posted to Facebook, the checkbox will be checked (B), otherwise not (A). In both cases you can post the record again by simply clicking on the wizard icon. |img-7| The wizard will be opened in an new window where all configured fields will be rendered. All fields can be reviewed, if there are multiple images, you can select the image which should be posted. If it's enabled you can select the posts target (profile, page, group) and by clicking on the button at the bottom, the extension posts the record to Facebook. |img-8| If there is no error, you receive a success message and your record should be visible on Facebook. |img-9| .. _Tutorial: Tutorial -------- Here I will show, how to configure the extension to post tt\_news records as event on Facebook. Because the extension already has the button for the wizard, we can directly go to the configuration step. We want to post the news as event, so we have to look at the appropriate API documentation: `http://developers.facebook.com/docs/reference/api/event/ `_ Here we see, that we need the “create\_event” permission, so we have to generate an authentication token, which provides this permission. Have a look at the chapter “ `Quickstart <#1.2.2.2.2.%20Request%20authorization%20code|outline>`_ ” to learn how to do this. After we got the token, add it to the extension configuration or the Tsconfig: :: mod.web_modules.bc_post2facebook.authToken = YOUR_AUTH_TOKEN Next the API says that events have to be posted to “http://graph.facebook.com/PROFILE\_ID/events”. We only need the part after “PROFILE\_ID/” so we add “events” to our configuration: :: mod.web_modules.bc_post2facebook.config.tt_news { _config { postAs = events } } Next we look at the fields we need to successfully publish an event. We need a field start\_time, which should be an ISO-8601 formated date or an UNIX timestamp. Because a timestamp is not readable for some users we use the ISO fromat. The data for this field is taken from the datetime field of the news. :: mod.web_modules.bc_post2facebook.config.tt_news { start_time = TEXT start_time { field = datetime date = c } } For the end\_time we also use the datetime field and add a default of two hours: :: mod.web_modules.bc_post2facebook.config.tt_news { end_time = TEXT end_time { field = datetime stdWrap.wrap = | +60*60*2 prioriCalc = intval date = c } } Because there is already a configuration for tt\_news you have to deactivate all unwanted fields by setting them to empty or “NONE”. In this case we keep the name, description and picture but remove the link: :: mod.web_modules.bc_post2facebook.config.tt_news { link = } One last thing we need for the event is the picture. Although there is already a working configuration for the picture, we have to take into account, that there is no field for a picture in the GraphAPI. Pictures for events have to be posted as upload. So all you have to do is, to tell the extension that images should be uploaded instead of referenced by an absolute url: :: mod.web_modules.bc_post2facebook.config.tt_news { _config { picture_as_upload = 1 } } If you have your own records and want to define a picture, you have to set the picture\_field to tell the extension where it should take the images from. :: mod.web_modules.bc_post2facebook.config.tt_news { _config { picture_field = images } } That's all, you should have a working configuration to post a news entry as event to Facebook. For completeness, here is the full configuration including the already configured fields by the extension (the added configuration is bold): :: mod.web_modules.bc_post2facebook.config.tt_news { _config { postAs = events picture_as_upload = 1 picture_field = image } name = TEXT name.field = title link = start_time = TEXT start_time { field = datetime date = c } end_time = TEXT end_time { field = datetime stdWrap.wrap = | +60*60*2 prioriCalc = intval date = c } picture = IMG_RESOURCE picture { file { import = uploads/pics/ import.field = image import.listNum.stdWrap.data = register: picture_num maxW = 120 maxH = 120 } } description = TEXT description { field = short ifEmpty { field = bodytext crop = 300 | ... | 1 } stripHtml = 1 parseFunc < lib.parseFunc_RTE } } .. _Known-problems: Known problems -------------- Nothing yet, but we have not tested all use cases or GraphAPI channels .. _To-Do-list: To-Do list ---------- Find a better way to use tslib\_content in backend modules. We use a changed version to get a working IMG\_RESOURCE. Please let us know, if there is a better solution .. _ChangeLog: ChangeLog --------- Take a look at the changelog file |img-2| 14 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. |img-2| image:: img-2.png .. :border: 0 .. :height: 21 .. :hspace: 9 .. :id: Grafik2 .. :name: Grafik2 .. :width: 87 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 82 .. :name: HTTP://WWW.BLUECHIP.AT/ .. :width: 178 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 476 .. :id: graphics1 .. :name: graphics1 .. :width: 571 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 314 .. :id: Grafik1 .. :name: Grafik1 .. :width: 669 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 309 .. :id: Grafik3 .. :name: Grafik3 .. :width: 496 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 86 .. :id: Grafik4 .. :name: Grafik4 .. :width: 131 .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :height: 323 .. :id: Grafik5 .. :name: Grafik5 .. :width: 388 .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :height: 154 .. :id: Grafik7 .. :name: Grafik7 .. :width: 336