Difference between revisions of "PT Social Media Version 3.0 Install"

Latest revision as of 18:43, 16 March 2017

Back to PT Social Media

IMPORTANT: v3.0 of this application requires ADF 2.0 or greater (and CommonSpot 10 or greater) 

Download

Download the Social Media Application from the Community Site Project or from the SVN Repository.

Extract the zip files into the following directory: /ADF/apps/pt_social_media/

Site Configuration

The Social Media Application is built within the ADF. The ADF 2.0 or greater must be installed in the site to run the Social Media Application, follow the ADF Installation instructions.

• Make sure the ADF is setup and running on the site. If the ADF is not setup, then follow the instructions for ADF Installation.
• Open the sites 'ADF.cfc' (See Site Configuration (ADF.cfc) for more info) file (located in your site's /_cs_apps/ directory) in a text editor.
• Locate the Load the ADF Application into application space comment in the file. Add (or uncomment) the following command under the comment section:

loadApp("ptSocialMedia");

• Reset the ADF for the server and site.

Styles

There are several out of the box style options for the Social Media application. Most of the styles are defined in the following style sheets located in the /style directory within the ADF Social Media App directory:

• /ADF/apps/pt_social_media/style/socialmedia.css

You have two options: you can either load them into your Base Plus One (recommended) or your can load them into the Social Media Template you create.

Note: the classes and styles defined for the Social Media app are targeted tightly for the layout generated by the Social Media application and should not interfere with your site styles. However, it is a good idea to give these styles sheets higher precedence in your style definitions.

Import Custom Elements

The Social Media App has several Custom Components defined within CommonSpot. These components are available in the Social Media's "exported-objects" folder located at the root of the Social Media application directory (e.g. /ADF/apps/pt_social_media/exported-objects/)

To import these objects, you will need to be an administrator for your site.

Create a "PT Social Media Elements" category and import all portions of each component in the order listed.

Import Custom Elements:

1. SocialMedia Selector (SocialMedia-Selector-Custom-Element.zip)
2. Facebook Pages (Facebook-Pages-Custom-Element.zip)
3. Twitter Accounts Keywords (Twitter-Accounts-Keywords-Selector-Custom-Element.zip)
4. WordPress Blogs (WordPress-Blogs-Custom-Element.zip)
5. YouTube Channels (YouTube-Channels-Custom-Element.zip)
6. ptSocialMedia Configuration (ptSocialMedia-Configuration-Custom-Element.zip)

Verify Imports

The imported components' render handlers and custom field types must be verified. During the import process, the render handler and custom field types paths may have been changed to reflect the current site's path.

Review and update these paths to reference the ADF path. In most cases, this will just require to be unlocked and a change in the path from the site name to 'ADF'. Check the paths for the custom field types that were imported with the custom elements by unlocking them and fixing the explicit paths to point to "/ADF/extensions/".

If the custom elements that are imported contain custom field types that are already in the site, the naming convention for the custom field type will be unique. To resolve this, unlock the field types and elements, and reassign the element field type to the pre-existing field type.

Example: The SocialMedia Selector custom element contains two uses of the General Chooser field type, if the General Chooser field type is already installed on the site then the import process will attempt to import another General Chooser but with a new name such as "General Chooser_import_1250003208472." To resolve this issue, open the custom element and assign the field type (General Chooser_import_1250003208472) to the field type with the simple name General Chooser. After reassigning the field type, delete the new imported field from the list of custom field types.

App Configuration

The Social Media App uses a custom element to store site specific configurations.

Most of these configuration fields will not need to be modified from their default values. Although, there are a few fields that the values will need to be customized for your specific install of the application. These fields are be listed below.

There are several configuration fields:

General Config Tab

1. ui_theme - The Social Media app utilizes jQueryUI Themes for styling of buttons, etc. There are some pre-installed themes that come with the ADF in the Thirdparty folder.
2. socialMediaServiceTypes - Checkboxes used to enable the social media types that will be utilized
   (Default: facebook,twitter,youtube,wordpress)
3. dashboardURL - URL of Social Media App Web Admin Dashboard page where the Feed Cache scheuduled task is managed.
4. serviceManagerURL - URL of Social Media App Web Admin Service Manager page where service accounts are maintained
5. configManagerURL - URL of Social Media App Web Admin Configuration page where all of the App configuration setting are modified
6. enableFeedCache - a checkbox to activate or deactivate the Social Media App service feed caching
7. rebuildFeedCacheInterval - an integer value in minutes for the pause time between feed cache rebuild scheduled tasks
   (Default: 15 mins)

Facebook API Tab

1. apiFacebookAppID - The App ID you receive when you register your App on Facebook
2. apiFacebookAppSecret - The App Secret you receive when you register your App on Facebook

- Facebook App Registration Instructions

Twitter API Tab

1. apiTwitterCustomerKey - The Consumer Key you receive when you register your App on Twitter
2. apiTwitterCustomerSecret - The Consumer Secret you receive when you register your App on Twitter

- Twitter App Registration Instructions

WordPress API Tab

1. wordPressServiceURL - URL of Blog Index page
2. wordPressServiceImage - A service image for Blog Index page
3. apiWordPressFeedSuffix - Suffix for the WordPress Blog RSS feed. ie. '?feed=rss2' or '/feed/' depending how your WordPress site is configured
4. apiWordPressContentWordLimit - Maximum number of words rendered from the blog post content. Default: 100. Use 0 (zero) to display all.

Note: The other API fields in the configuration element (not listed here) should NOT need to be modified from their default values unless one of the social media services changes their data feed format or feed URL and/or URL parameters.

Subsites

A specific subsite for social media pages is optional. The Social Media Feed page which in most cases will be a public facing page (or pages) can live anywhere on your site. But for this install we will create a socialmedia subsite for this page.

It is highly recommended to have a Web Admin subsite that contains a Social Media subsite that will contain the Management pages for for administrators. This allows security to be setup for the subsite to allow only administrators access for the webadmin subsite.

Your site may already have a webadmin subsite. The steps under 'Web Admin will add a socialmedia subsite into the webadmin subsite.

Social Media

1. Create a new subsite under the site root called socialmedia.

Web Admin

1. Create a new subsite under the site root called webadmin.
2. Create a new subsite under webadmin called socialmedia.
3. Configure the /webadmin/socialmedia/ subsite Content Security to give 'No Rights' to 'Anonymous Users' and 'Authenticated Users'.
4. Configure the /webadmin/socialmedia/ subsite Content Security to give permissions to the group of administrators who will need access to the social media management pages.

Templates

Social Media Template - Optional

The Social Media template will be used to render Social Media pages.

Note: A Social Media templates are not critical for this application. A Social Media feeds page can be added to any page based on any template with a large main content column.

1. Create a CommonSpot page called 'Social Media' from the Base Plus One template. (The subsite for this is not critical but it may be a good idea to create a subsite called 'socialmedia').
2. Submit and activate the page.
3. Save the page as a template.
4. Submit the template for public use.

Web Admin Template - Optional

The Web Admin template will be used to render web admin management pages.

1. Create a CommonSpot page called 'Web Admin' from the Base Plus One template. (The subsite for this is not critical but it may be a good idea to create a subsite called webadmin).
2. Submit and activate the page.
3. Save the page as a template.
4. Submit the template for public use.

Admin Pages

Follow the guide to create these 4 Admin pages:

1. CCAPI Configuration
2. Manage App Configuration Page
3. Manage Service Accounts Page with Multiple Datasheets
4. Social Media Dashboard Page

You may also want to create this optional page for service feed debugging:

1. Social Media Stream Debug Page

CCAPI Configuration

The Social Media Application uses the ADF CCAPI to populate each of the social media service custom element records with moderation data. The CCAPI needs to be configured for the site and for the social media application.

First, follow the steps to set up the CCAPI Config file for the site. Once that configuration is complete, follow the steps below to set up the CCAPI config for the Social Media application. Make sure to update the wsVars section with the correct URLs and username/password.

1. Create a new page called 'ccapiSocialMedia'. Recommend creating this page in the /webadmin/socialmedia/ subsite.
2. Add each of the following Social Media elements to the page:
   1. Facebook Pages
   2. Twitter Accounts Keywords
   3. WordPress Blogs
   4. YouTube Channels

1. For each element that was added, click on the element indicator and go to 'more...'. Select 'Name' from the menu.
2. In the Element Name field, enter the appropriate name for each element:
   1. ccapiFacebookPages
   2. ccapiTwitterAccountsKeywords
   3. ccapiWordPressBlogs
   4. ccapiYouTubeChannels

1. Publish this page and view in read mode.
2. Edit the 'ccapi.cfm' file for the site and add the following xml blocks into the <elements> section:
   1. an example 'ccapi.cfm' file is in the pt_social_media > site-files > _cs_apps > config folder

 <FacebookPages>
   <pageID>#####</pageID>
   <subsiteID>##</subsiteID>
   <elementType>custom</elementType>
   <controlName>ccapiFacebookPages</controlName>
 </FacebookPages>
 <TwitterAccountsKeywords>
   <pageID>#####</pageID>
   <subsiteID>##</subsiteID>
   <elementType>custom</elementType>
   <controlName>ccapiTwitterAccountsKeywords</controlName>
 </TwitterAccountsKeywords>
 <WordPressBlogs>
   <pageID>#####</pageID>
   <subsiteID>##</subsiteID>
   <elementType>custom</elementType>
   <controlName>ccapiWordPressBlogs</controlName>
 </WordPressBlogs>
 <YouTubeChannels>
   <pageID>#####</pageID>
   <subsiteID>##</subsiteID>
   <elementType>custom</elementType>
   <controlName>ccapiYouTubeChannels</controlName>
 </YouTubeChannels>

To populate the <pageID> and <subsiteID> tags, view the 'source' code for the 'ccapiSocialMedia' page that was just created.

Identify the following line in the source code and enter this numeric value into the <subsiteID> tag:

  var jsSubSiteID = ##;

Identify the following line in the source code and enter this numeric value into the <pageID> tag:

  var jsPageID = ####;

Manage App Configuration Page

The Social Media Configuration Page will be used to manage the ptSocialMedia Configuration custom element. Follow these steps to configure the datasheet and page for adding the configuration settings.

1. Create a new page called 'Configuration Manager' in the /webadmin/socialmedia/ subsite.
2. In the main content of the page, add a Custom Script element.
3. Enter the explicit module path for:
   • /ADF/apps/pt_social_media/customcf/manage_configuration_header.cfm
4. Publish the page.

Create Social Media Configuration Record

We are creating a single Social Media Configuration element record to be used within the application.

1. Click the Add Configuration button
2. Submit the form to create a configuration record.

Doing this will save the default field values in the configuration record of the custom element.

You can also update the following fields:

1. General Config Tab
   1. ui_theme
   2. socialMediaServiceTypes
2. Facebook API Tab
   1. apiFacebookAppID
   2. apiFacebookAppSecret
3. Twitter API Tab
   1. apiTwitterCustomerKey
   2. apiTwitterCustomerSecret
4. WordPress API Tab
   1. wordPressServiceURL
   2. wordPressServiceImage
   3. apiWordPressFeedSuffix
   4. apiWordPressContentWordLimit

See the App Configuration portion of this page for more information on the fields and the correct values.

Reset the ADF for the server and site.

Manage Service Accounts Page with Multiple Datasheets

The Manage Social Media page is a page that contains the data management datasheets for the four social media custom elements. This page is build using a tabbed interface with one tab for each social media service datasheet.

1. Create a page from the Base Plus One (or a Web Admin) template titled 'Manage Service Accounts' with the page name 'index' in the /webadmin/socialmedia/ subsite.
2. In the main content area of the page, add a Custom Script element.
3. From the Custom Script element interface, click the "Edit" icon.
4. Enter the following text into the Explicit Module path:
   • /ADF/apps/pt_social_media/customcf/manage_social_media_tabs_v2.cfm

(Remember: If any of the social media services have been disabled in the App Configuration
those service tabs will not appear on this management page.)

Facebook Tab

1. From the Datasheet element interface, click the "Datasheet" icon.
2. From the "Datasheet Views" dialog, click the "Add Datasheet View" link.
3. Enter the following information and then click "Next":
   1. Name: Facebook Pages View
   2. Private: unchecked
   3. Default View: checked
   4. Description: View to manage the all Facebook Pages
   5. Datasheet Source: Form Result/Custom Element Sheet
   6. Click "Next"
4. From the Datasheet Source dialog choose the "Facebook Pages" custom element and click "Next"
5. From the Datasheet Columns Dialog select the columns UNIQUEID, FBPAGENAME, FBPAGELINK and FEEDACTIVE from the Available Columns list and move them to the Selected Columns list and then click "Finish" or "Save".
6. You will be brought to the Datasheet View page; click "Close" to return to your page.
7. You will see the datasheet element on this page now. Click the Datasheet element interface icon again and this time choose "Edit Columns".
8. Within the Datasheet View Column Properties dialog choose the UNIQUEID column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/edit-delete.cfm
   2. Click Finish or Save.
   3. In the Header field, switch the text to 'Edit/Delete'
   4. Click Finish or Save
9. Now within the Datasheet View Column Properties dialog choose the FEEDACTIVE column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/value-to-yes-no.cfm
   2. Click Finish or Save
   3. In the Header field, switch the text to 'Active'
   4. Click Finish
10. Close the Edit Column window.
11. Go back to the Datasheet element interface, select the Layout button
    1. Default Sorting = FBPAGENAME Ascending
    2. Uncheck "Show Alphabet Characters for Filtering"
    3. Uncheck "Allow JavaScript data sorting"
    4. Click Save

Twitter Tab

1. From the Datasheet element interface, click the "Datasheet" icon.
2. From the "Datasheet Views" dialog, click the "Add Datasheet View" link.
3. Enter the following information and then click "Next":
   1. Name: Twitter Accounts and Keywords View
   2. Private: unchecked
   3. Default View: checked
   4. Description: View to manage the all Twitter Accounts and Keywords
   5. Datasheet Source: Form Result/Custom Element Sheet
   6. Click "Next"
4. From the Datasheet Source dialog choose the "Twitter Accounts Keywords" custom element and click "Next"
5. From the Datasheet Columns Dialog select the columns UNIQUEID, TWITTERACCOUNTKEYWORD, TYPE and FEEDACTIVE from the Available Columns list and move them to the Selected Columns list and then click "Finish" or "Save".
6. You will be brought to the Datasheet View page; click "Close" to return to your page.
7. You will see the datasheet element on this page now. Click the Datasheet element interface icon again and this time choose "Edit Columns".
8. Within the Datasheet View Column Properties dialog choose the UNIQUEID column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/edit-delete.cfm
   2. Click Finish or Save.
   3. In the Header field, switch the text to 'Edit/Delete'
   4. Click Finish or Save
9. Now within the Datasheet View Column Properties dialog choose the FEEDACTIVE column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/value-to-yes-no.cfm
   2. Click Finish or Save
   3. In the Header field, switch the text to 'Active'
   4. Click Finish
10. Close the Edit Column window.
11. Go back to the Datasheet element interface, select the Layout button
    1. Default Sorting = TwitterAccountKeyword Ascending
    2. Uncheck "Show Alphabet Characters for Filtering"
    3. Uncheck "Allow JavaScript data sorting"
    4. Click Save

YouTube Tab

1. From the Datasheet element interface, click the "Datasheet" icon.
2. From the "Datasheet Views" dialog, click the "Add Datasheet View" link.
3. Enter the following information and then click "Next":
   1. Name: YouTube Channels View
   2. Private: unchecked
   3. Default View: checked
   4. Description: View to manage the all YouTube Channels
   5. Datasheet Source: Form Result/Custom Element Sheet
   6. Click "Next"
4. From the Datasheet Source dialog choose the "YouTube Channels" custom element and click "Next"
5. From the Datasheet Columns Dialog select the columns UNIQUEID, CHANNELTITLE, CHANNELUSERNAME and FEEDACTIVE from the Available Columns list and move them to the Selected Columns list and then click "Finish" or "Save".
6. You will be brought to the Datasheet View page; click "Close" to return to your page.
7. You will see the datasheet element on this page now. Click the Datasheet element interface icon again and this time choose "Edit Columns".
8. Within the Datasheet View Column Properties dialog choose the UNIQUEID column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/edit-delete.cfm
   2. Click Finish or Save.
   3. In the Header field, switch the text to 'Edit/Delete'
   4. Click Finish or Save
9. Now within the Datasheet View Column Properties dialog choose the FEEDACTIVE column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/value-to-yes-no.cfm
   2. Click Finish or Save
   3. In the Header field, switch the text to 'Active'
   4. Click Finish
10. Close the Edit Column window.
11. Go back to the Datasheet element interface, select the Layout button
    1. Default Sorting = CHANNELTITLE Ascending
    2. Uncheck "Show Alphabet Characters for Filtering"
    3. Uncheck "Allow JavaScript data sorting"
    4. Click Save

WordPress Tab

1. From the Datasheet element interface, click the "Datasheet" icon.
2. From the "Datasheet Views" dialog, click the "Add Datasheet View" link.
3. Enter the following information and then click "Next":
   1. Name: WordPress Blogs View
   2. Private: unchecked
   3. Default View: checked
   4. Description: View to manage the all WordPress Blogs
   5. Datasheet Source: Form Result/Custom Element Sheet
   6. Click "Next"
4. From the Datasheet Source dialog choose the "WordPress Blogs" custom element and click "Next"
5. From the Datasheet Columns Dialog select the columns UNIQUEID, BLOGTITLE and FEEDACTIVE from the Available Columns list and move them to the Selected Columns list and then click "Finish" or "Save".
6. You will be brought to the Datasheet View page; click "Close" to return to your page.
7. You will see the datasheet element on this page now. Click the Datasheet element interface icon again and this time choose "Edit Columns".
8. Within the Datasheet View Column Properties dialog choose the UNIQUEID column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/edit-delete.cfm
   2. Click Finish or Save.
   3. In the Header field, switch the text to 'Edit/Delete'
   4. Click Finish or Save
9. Now within the Datasheet View Column Properties dialog choose the FEEDACTIVE column and click "edit":
   1. In the Render Handler field, select the 'Change' button. Enter the following value into the Explicit Module text box:
      • /ADF/extensions/datasheet-modules/1.0/value-to-yes-no.cfm
   2. Click Finish or Save
   3. In the Header field, switch the text to 'Active'
   4. Click Finish
10. Close the Edit Column window.
11. Go back to the Datasheet element interface, select the Layout button
    1. Default Sorting = BLOGTITLE Ascending
    2. Uncheck "Show Alphabet Characters for Filtering"
    3. Uncheck "Allow JavaScript data sorting"
    4. Click Save

1. Publish this page.

Social Media Dashboard Page

The Social Media Dashboard page is a page is used to manage the Service Feed Cache and the Scheduled task that rebuilds the Service Feed Cache at the desired interval. This page contains:

• The status of the Service Feed Cache
• The date & time stamp of when the Service Feed Cache was last built
• A button to Force the Service Feed Cache to be rebuilt
• A button to set the Scheduled task to rebuild the Service Feed Cache at regular intervals
• A data table that displays the current status of the Service Feed Cache scheduled task

To build this page:

1. Create a new page from the Base Plus One (or a Web Admin) template called 'Social Media Dashboard' in the /webadmin/socialmedia/ subsite.
2. In the main content area of the page, add a Custom Script element.
3. From the Custom Script element interface, click the "Edit" icon.
4. Enter the following text into the Explicit Module path:
   • /ADF/apps/pt_social_media/customcf/sm_dashboard_header.cfm

Usage
Go to the Social Media Dashboard section on the Getting Started page for more information on usage of this page.

Social Media Stream Debug Page - Optional

Since the content for this page is primarily under the control of each of the Social Media Services you are receiving the posts from it maybe necessary to have deeper visualization into the raw data coming from these services.

This page is a version of the Social Media Stream Page with a debug tools header custom script. It may be best to go through the steps to create and configure a standard Social Media Stream page before creating this debugging page.

• Social Media Stream Page
• Configure the Social Media Stream Page section on the Getting Started page

It is also highly recommended that this debugging stream page be built in the Social Media Web Admin subsite so it will be protected by the Web Admin security settings.

To construct your Social Media Debugging Stream page complete the following steps:

1. Create a CommonSpot page with a name of 'Social Media Debug' and a title of 'Social Media Debug' using the Social Media template and place it in the '/webadmin/socialmedia/' subsite.
2. In the main content of the page, add a Custom Script element.
3. Enter the explicit module path for:
   • /ADF/apps/pt_social_media/customcf/sm_debug_links.cfm
4. Place the SocialMedia Selector Custom Element on this page.
5. From the SocialMedia Selector element click More in the element interface.
6. Click the Custom Render Handlers menu option, and choose the Default or the Social Media Combined Stream Render Handler.
7. Submit the Page.

Usage

Once the page has been created and configured to display posts from the selected Social Media services you can use the debug tools checkboxes to select different raw data dump combinations and then click the link to reload the page.

When the page is fully reloaded, there will be Coldfusion data dumps visible above the posts that will display the raw data that is used to build the stream page.

If Social Media errors have occurred for the various services, links will be generated to allow access to open the error log files from the CommonSpot logs folder.

(Remember: This debug page needs to remain dynamic since it uses URL variables to modify the
Feed Stream Output. Please make sure that CommonSpot Caching has been disabled on this page.)

Social Media Stream Pages

For this install we will only create one main social media stream page. But many pages can be created throughout your site to meet your specific needs using this same method. For example, a separate page could be created for each of the social media services (ie. YouTube Channels page) or pages could be created for specific social media accounts.

The Social Media Stream Page is where the social media posts from the selected social media service pages, accounts and keywords display. These posts come from the live data feeds available from each service. The posts are not stored locally and with active social media account will possibly change with each page refresh.

To construct your Social Media Stream page complete the following steps. (Remember these steps can be adapted to a page created in any subsite using any template that has a large content area column.)

1. Create a CommonSpot page with a name of 'index' and a title of 'Social Media Stream' using the Social Media template and place it in the 'socialmedia' subsite.
2. Place the SocialMedia Selector Custom Element on this page.
3. From the SocialMedia Selector element click More in the element interface.
4. Click the Custom Render Handlers menu option, and choose the Default or the Social Media Combined Stream Render Handler.
5. Submit the Page.

Go to the Configure the Social Media Stream Page section on the Getting Started page for more info.

Reset the ADF

Reset the ADF for the server and site.