This widget uses the following external utilities:
There are several core files associated with this widget:
This file contains all of the configuration globals for the utility. The values in this file need to be changed during installation – globals include:
- KEY – The OAuth api key provided after setting up a new OAuth application (see installation steps for the place to obtain this)
- SECRET – The OAuth shared secret key provided after setting up a new OAuth application (see installation steps for the place to obtain this)
- APPID – The application id provided after setting up a new OAuth application (see installation steps for the place to obtain this)
- CALLBACK – The URL to forward back to once setup has completed. This is usually the same URL that the widget is installed at
- REQUEST_TOKEN_URL – The url to the request_token storage file. If file does not exist it will be created. Example: “./tokens/request_token.txt”
- ACCESS_TOKEN_URL – The url to the access_token storage file. If file does not exist it will be created. Example: “./tokens/access_token.txt”
This file contains the session storage routines used to maintain your authenticated OAuth session. This file may be modified to store / retrieve the request & access tokens from a database instead of the incecure flat text file.
File that is called through the AJAX request to instantiate the OAuth session and retrieve YQL data. This file should not be modified.
This is the installation setup file. This file should be run as soon as widget setup is complete and then deleted. This should should not be modified. See installation steps for exact details on this.
This is an example HTML example of how to setp up and call this widget to display private user data.
Follow the steps below to install the PHP YQL widget on your server:
- Go to https://developer.yahoo.com/dashboard and create a new OAuth application (not an Open application). The URL of this application should be where the widget will be installed. Make sure to mark down your api key, shared secret key, and application id when your application is set up.
- Copy all files in this widget example to the directory where you would like the widget to display
- If you are using the text file storage for your tokens, create a “tokens” directory. This name should match the token_url paths within the config.php file.
- Create a folder called “php_sdk”. Download the Y!OS PHP SDK from http://github.com/yahoo/yos-social-php/tree/master and copy the contents of the lib folder within the SDK to this new directory.
- Open config.php and change your key, secret and appid globals to the values obtained from step 1. Change the token URLs to reflect the location defined in step 3.
- Run runmefirst.php to store your access token. It is very important that this file be run right after installation because it will store the token of the first user who authenticates it. If you see a success message you may delete that file.
- Your social updates widget is now ready to use.
HTML file configuration
The provided HTML file displays your updates and has an optional parameter for adding your badge & status automatically. This file may be modified to look / function in any way you wish. It can also pull and display data from different Y!OS social sources (http://developer.yahoo.com/social/rest_api_guide/) if the YQL query is changed. Below is a brakdown of the specifics for the sample HTML file:
Going through the above example, here is the definition for how to format the requests:
Create the container the you would like to drop the widget into (must have an id)
(OPTIONAL) Define the config object. This object has the following available key / value pairs:
- badge (true / false) – If set to true, your profile photo, name, location and status will be displayed at the top of the widget
- num_results (int) – The number of results to display in the widget
- debug (true / false) – If set to true, status messages will be displayed via console.log during widget rendering
Define the YQL query to pass to the private YQL URI.
Define the id of the container you wish to insert the widget into
Push the widget on the stack. If you have multiple widgets to be rendered, you would push each widget on the load stack using push before rendering (as seen on line 9). The push function accepts the following parameters:
- YQL Query (REQUIRED) – The query defined on line 6
- Config (OPTIONAL) – The config object defined on line 4
- Format (REQUIRED) – The content to add for each result into the container defined
- Insert Element (REQUIRED) – The id of the container to insert the widget into
Render all widgets pushed onto the load stack
This project only accepts contributions licensed under the BSD open source license. See the Open Source Initiative’s approved template below.
Each file submitted should contain the following information in the header:
// Created by [contributor]
// Copyright © [enter owning person entity, year]. All Rights Reserved.
// Licensed under the BSD (revised) open source license.
Below is the Open Source Initiative BSD License Template (http://opensource.org/licenses/bsd-license.php):
Copyright © <YEAR>, <OWNER>
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.