Open Badges Directory PHP Client v1.0 - Simple php-based library that allows site developers to integrate open badge directory searches into sites.
This is a simple php-based code library that any developer can use to integrate into his/her site the capability to search for open badges. The library includes a simple configurable form, and the base code to run a cURL session to return open badge information to a webpage.
Note that the code is documented throughout the library, and should be used as a basic starting point for integrating functionality into a site.
https://github.com/mozilla/openbadges/wiki/
https://groups.google.com/d/forum/openbadges
https://groups.google.com/forum/#!forum/openbadges-dev
These configuration / scripts have been tested on a CentOS server running Apache 2.0 and PHP 5.3.2. Version PHP 5 and up should work fine. Note that the webserver that you are running must have the capability of running php cURL functions. See this link for further details: http://php.net/manual/en/curl.requirements.php
There are two sub-directories of the Open Badges Directory PHP Client: css and functions. The css directory contains a very basic starting stylesheet, and can contain any stylesheets you wish to include. The functions directory contains the php code to run the basic functions to control / execute the cURL session that gathers data.
The main directory includes an index.php and results.php file. The index.php file controls the basic form for user submissions (inputs for the cURL session), and results.php renders the cURL output. Both files are very basic starting point functionality files, and both can be leveraged for your site as necessary. Note that if results.php is renamed, and if you are using the form from index.php, the code within index.php must be updated appropriately.
######css/ style.css - Some basic styles to get you started.
######functions/ get_data.php - The basic functionality to control the cURL session which renders a JSON array. Note that this file contains a single function to return data, which results.php outputs to the screen. The code within 'get_data.php' can be modified as necessary and per your site's requirements. The variable that is generated by this file can be used on any downstream code as necessary as long as 'get_data.php' and the function within is referenced within this downstream code.
user_defined_search.php - The basic functionality to build the search string that 'get_data.php' will use in the cURL session. This file contains a single function that can be modified based on your site's requirements, or as per user requiremnts for interacting with the open badge repository. The code within 'user_defined_search.php' is fully documented, and details how to restrict the search capabilities of your site. Note that the Open Badges Directory API Explorer (http://test-openbadges-directory.herokuapp.com/developers/api-explorer#!/search/search) is the basis of the search functionality, and the only functionality NOT present in this library is the "page" query.
index.php: Renders the basic form that controls the Open Badge search. The code within 'index.php' is fully documented, and the form can be modified as necessary for your site's search functionality.
results.php: Renders the results of the cURL session to the screen. Currently a basic page that is sequenced from 1. to 'X' with results. Note that variable '$values' that are passed through the cURL session are output at the top of the page via 'results.php'. This section of 'results.php' can be rebuilt as necessary for your site, and in addition, the php/HTML withih 'results.php' can be copied into any page on your site by calling the results of variable $data in your page. Instructions on this are documented within 'results.php'.
- Place all code from the openbadges-directory-php-client git repo into a public directory on your web host. Note that because the files can be called per your site's structure, the location of the files on your site are not as important as making sure the files within the library call each other's filepaths properly. Ex: Your site contains a directory called "badges", and you would like all of this functionality to exist within "badges". You can rename "index.php" to whatever page within your site you would like it to be called -OR- copy / paste the form code from 'index.php' into a file within directory 'badges' in order to integrate the repo's functionality into your site.
- Follow the workflow of the library through to the other supporting files within the library, and update filepahts / naming conventions as necessary.
- If you want to integrate only specific searh capabilities, you can restrict via the code that builds the form. If you do this, it is highly suggested that you update the php conditionals in 'user_defined_search.php' so that you are only using the search functionality that the form is calling.
- You may need to update your existing .htaccess file in the public root directory of your host (where your index file is) because your host's apache settings may not recognize .json files (your badge assertions). You'll know this to be the case if the issuer api returns a content type error when you issue a badge. In the existing .htaccess file, or create a new one if you don't have one, and add this line:
AddType application/json .json
- Once the code is embedded within your site, navigate to www.yourdomain.com/search-page - Where "search-page" is the page you've configured to render your form. The form should be available, and the capability to run a test search should exist.
- The 'get_data.php' page has been configured to print an error message if there is a problem with your cURL session. If you experience errors with your integration, below is a quick checklist:
- Make sure Apache is configured to run cURL sessions (see above, "Requirements").
- Make sure your filepaths are all referenced correctly within the library.
- Ensure that you can reach the link that is referenced in 'user_defined_search.php' as the page that will be used for the cURL session.
- Ensure that the users running the cURL sessions have site access to the necessary pages.
- If all else fails, post to the Q&A of the git repo.
- Query some Open Badges!
The Open Badges Directory PHP Client 1.0 launched 9/22/2014! This version uses a Swagger UI (http://test-openbadges-directory.herokuapp.com/developers/api-explorer#!/search/search) as a config basis for interacting with the Open Badges API. It will work with Open Badges 1.0.
This configuration does not use any javascript, jQuery, or AJAX. This does not mean that this library's php-based functionality cannot utilize javascript. This release was configured to be php-based, and allow customization as necessary; thus, the code is all php/HTML.
If you download from github as a zip or tar file, you will need to uncompress the files and place them manually into your site.
Your feedback and questions are welcomed and needed to make this better. Drop an email to [email protected] or submit issues.