Difference between revisions of "Partner Interface"
Jon Phillips (talk | contribs) (→The remote license engine application) |
Jon Phillips (talk | contribs) (added nice code) |
||
| Line 23: | Line 23: | ||
http://creativecommons.org/license/?partner={partner}&exit_url={exit_url}&stylesheet={stylesheet}&partner_icon_url={partner_icon_url} | http://creativecommons.org/license/?partner={partner}&exit_url={exit_url}&stylesheet={stylesheet}&partner_icon_url={partner_icon_url} | ||
</pre> | </pre> | ||
| + | </div> | ||
| + | |||
| + | The full set of URL variables available are as follows: | ||
| + | |||
| + | <div class="code"> | ||
| + | |||
| + | '''partner (required):''' The name of your application or site, used for tracking usage at Creative Commons. Any descriptive name can be added here. | ||
| + | |||
| + | '''exit_url (required):''' The return URL on your application that will load after a user selects a license and will contain appended variables in the URL that your software will need to read. | ||
| + | |||
| + | '''additional requirement:''' | ||
| + | |||
| + | Your exit_url must include "license_url=[license_url]" and may optionally include the license_name=[license_name], license_button=[license_button], and deed_url=[deed_url] variables. Explanation of each: | ||
| + | |||
| + | '''license_url:''' URL for the selected license. Link to this URL in the licensed page. Example: http://creativecommons.org/licenses/by/2.0/ | ||
| + | |||
| + | '''license_name:''' Pretty name for the selected license. Example: Attribution | ||
| + | |||
| + | '''license_button:''' URL for the image corresponding to the selected license, useful for displaying on a licensed page. Example: http://creativecommons.org/images/public/somerights20.gif | ||
| + | |||
| + | '''deed_url:''' URL for the deed corresponding to the selected license. Usually this will be identical to the value of license_url, unless a "branded" license is selected. Note that even if deed_url is different than license_url, is is still valid to use the URL specified by license_url, as both will point to the same legal code. If you want to support this feature, link to the deed_url in the licensed page. Example: http://creativecommons.org/licenses/by-nc-nd/2.0/deed-music | ||
| + | |||
| + | A sample exit URL would be: | ||
| + | |||
| + | <pre> | ||
| + | http://example.com/return_from_cc?license_url=[license_url]%26license_name=[license_name] | ||
| + | </pre> | ||
| + | |||
| + | The license engine will replace the license_url, license_name, license_button, and deed_url variables with proper variables once a user has chosen a license (more on this in Part 2). | ||
| + | |||
| + | Note that your exit URL can carry your application's URL variables into and out of the license application by URL escaping within your exit URL, for example: | ||
| + | |||
| + | <pre> | ||
| + | http://example.com/return_from_cc?license_url=[license_url]%26license_name=[license_name]%26userID=42%26user-work=foo.jpg | ||
| + | </pre> | ||
| + | |||
| + | The above example will let your application know that a userID of 42 that submitted a user-work titled foo.jpg selected a specific license on exit of the license engine. | ||
| + | |||
| + | If you want to maintain state but do not wish to pass data through the URL (e.g., for reasons of privacy or data size), consider saving the data in a user cookie (which will only be sent to your site, not creativecommons.org), save the data in a file or database and save a lookup key in a cookie or pass the lookup key via the URL, or use the popup or iframe methods (see below), which do not require the user to "leave" your form. | ||
| + | |||
| + | '''stylesheet (optional):''' | ||
| + | |||
| + | URL of a Cascading Style Sheet (CSS) file to customize the layout, look, and feel of the license questions. View source on the license engine to see the ID and classes available to be styled. | ||
| + | |||
| + | '''partner_icon_url (optional):''' if you'd like a custom image displayed at the top of the license application, add the image's URL in this variable. | ||
| + | |||
| + | The following enable choosing licenses ported to the copyright law of specific legal jurisdictions. See the iCommons project for more information. | ||
| + | |||
| + | '''jurisdiction (optional):''' Choose licenses of specified jurisdiction. With jurisdiction_choose on, sets pre-selected jurisdiction. Currently supported jurisdictions: at, au, be, br, ca, de, es, fi, fr, hr, it, jp, kr, nl, tw. | ||
| + | |||
| + | '''jurisdiction_choose (optional):''' If set to '1', user will be given a list of jurisdictions to choose from. | ||
| + | |||
</div> | </div> | ||
Revision as of 19:34, 12 April 2006
Web Integration Developer's Guide
Integrating Creative Commons licenses into your web application
While Creative Commons offers a range of license choices and public domain options direct from its license page, if you have created an application or built a website that allow people to contribute works you may prefer to integrate the license engine directly into your site or application. This guide serves to explain all the steps necessary and options available for integrating Creative Commons into your software.
This guide is generally split into three parts:
- Part 1: Letting users select a license
- Part 2: Processing and Storage of license information
- Part 3: Display of license information
Part 1: Letting users select a license
Whether your software is a website or a downloadable application, the first step to integrating Creative Commons licenses is letting users select a license directly from your software. The process involves loading a simplified Creative Commons license interface from within a popup window, embedded into your website, or launched from an HTML window control in your application. URL variables are read into the page and are appended when complete, allowing data to be extracted from the process and passed through it.
The remote license engine application
The heart of the process is running the remote license interface which is available at this URL:
http://creativecommons.org/license/?partner={partner}&exit_url={exit_url}&stylesheet={stylesheet}&partner_icon_url={partner_icon_url}
The full set of URL variables available are as follows:
partner (required): The name of your application or site, used for tracking usage at Creative Commons. Any descriptive name can be added here.
exit_url (required): The return URL on your application that will load after a user selects a license and will contain appended variables in the URL that your software will need to read.
additional requirement:
Your exit_url must include "license_url=[license_url]" and may optionally include the license_name=[license_name], license_button=[license_button], and deed_url=[deed_url] variables. Explanation of each:
license_url: URL for the selected license. Link to this URL in the licensed page. Example: http://creativecommons.org/licenses/by/2.0/
license_name: Pretty name for the selected license. Example: Attribution
license_button: URL for the image corresponding to the selected license, useful for displaying on a licensed page. Example: http://creativecommons.org/images/public/somerights20.gif
deed_url: URL for the deed corresponding to the selected license. Usually this will be identical to the value of license_url, unless a "branded" license is selected. Note that even if deed_url is different than license_url, is is still valid to use the URL specified by license_url, as both will point to the same legal code. If you want to support this feature, link to the deed_url in the licensed page. Example: http://creativecommons.org/licenses/by-nc-nd/2.0/deed-music
A sample exit URL would be:
http://example.com/return_from_cc?license_url=[license_url]%26license_name=[license_name]
The license engine will replace the license_url, license_name, license_button, and deed_url variables with proper variables once a user has chosen a license (more on this in Part 2).
Note that your exit URL can carry your application's URL variables into and out of the license application by URL escaping within your exit URL, for example:
http://example.com/return_from_cc?license_url=[license_url]%26license_name=[license_name]%26userID=42%26user-work=foo.jpg
The above example will let your application know that a userID of 42 that submitted a user-work titled foo.jpg selected a specific license on exit of the license engine.
If you want to maintain state but do not wish to pass data through the URL (e.g., for reasons of privacy or data size), consider saving the data in a user cookie (which will only be sent to your site, not creativecommons.org), save the data in a file or database and save a lookup key in a cookie or pass the lookup key via the URL, or use the popup or iframe methods (see below), which do not require the user to "leave" your form.
stylesheet (optional):
URL of a Cascading Style Sheet (CSS) file to customize the layout, look, and feel of the license questions. View source on the license engine to see the ID and classes available to be styled.
partner_icon_url (optional): if you'd like a custom image displayed at the top of the license application, add the image's URL in this variable.
The following enable choosing licenses ported to the copyright law of specific legal jurisdictions. See the iCommons project for more information.
jurisdiction (optional): Choose licenses of specified jurisdiction. With jurisdiction_choose on, sets pre-selected jurisdiction. Currently supported jurisdictions: at, au, be, br, ca, de, es, fi, fr, hr, it, jp, kr, nl, tw.
jurisdiction_choose (optional): If set to '1', user will be given a list of jurisdictions to choose from.
