Skip to content
This repository has been archived by the owner on May 29, 2024. It is now read-only.

Commit

Permalink
README
Browse files Browse the repository at this point in the history
  • Loading branch information
Seth Battis committed Jul 2, 2015
1 parent 4c662ae commit 316f71f
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 7 deletions.
14 changes: 7 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,20 @@ This is a starter template for projects that want to…
2. Access the Canvas APIs (either to provide information to the users or _as_ the users)
3. Embed the presentation layer of the project back into Canvas

This came about as a result of Hack Night at InstructureCon 2015, when it became clear to me that desire to both authenticate
users _and_ access the API using OAuth-provided tokens was more than could be done through simple OAuth authentication. (Well,
it _can_ be done, but it generates two OAuth tokens in the user's account and causes them to think that they are being logged
in twice: once to authenticate their identity (which can be persistent -- "check to remember this login") and once to generate
an API key. This seemed confusing, at best.)
This came about as a result of Hack Night at InstructureCon 2015, when it became clear to me that desire to both authenticate users _and_ access the API using OAuth-provided tokens was more than could be done through simple OAuth authentication. (Well, it _can_ be done, but it generates two OAuth tokens in the user's account and causes them to think that they are being logged in twice: once to authenticate their identity (which can be persistent -- "check to remember this login") and once to generate an API key. This seemed confusing, at best.)

### Usage

1. Start by [forking this repository](https://help.github.com/articles/fork-a-repo/).
2. Load your fork on to your favorite LAMP server (ideally including SSL-authentication -- Canvas plays nicer that way, and it's just plain more secure).
2. Be sure to run `composer install` ([Composer rocks](https://getcomposer.org/)).
3. Point your browser at https://<install-url>/admin/ and you will run the install script. You will need to have your MysQL credentials handy, as well as your Canvas developer credentials. Answer whatever questions it asks. (This will generate a secrets.xml file for you, if you don't want to make one yourself, based on [secrets-example.xml](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/secrets-example.xml).)
2. Be sure to run `composer install` ([Composer rocks](https://getcomposer.org/)) -- this has a few dependencies defined in [composer.json](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/composer.json).
3. Point your browser at `https://<install-url>/admin/` and you will run the install script. You will need to have your MySQL credentials handy, as well as your Canvas developer credentials. Answer whatever questions it asks. This will generate a `secrets.xml` file for you (if you don't want to make one yourself, based on [secrets-example.xml](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/secrets-example.xml)) and it will password-protect the `admin` directory.
- When you return to `https://<install-url>/admin/` thereafter, you will be redirected to [consumers.php](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/admin/consumers.php) which provides some rudimentary LTI Consumer management for the tool.
- [metadata-example.xml](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/metadata-example.xml) lists some of the basic `$metadata` keys, along with some default values and the validation regexes (which the [AppMetadata](https://github.com/battis/appmetadata) object may start actually using eventually). A lot of other possible keys are evident in [config.xml](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/config.xml).
4. Modify the CanvasAPIviaLTI class as needed -- most of your app logic can just go into [app.php](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/app.php), which is loaded after a user has been authenticated (via [launch.php](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/launch.php)).
5. Including [common.inc.php](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/common.inc.php) will provide access to several handy global variables (as well as populating the `$_SESSION` variable with relevant information):
1. `SimpleXMLElement $secrets`, the secrets.xml file.
2. `mysqli $sql`, a database connection to your MySQL server.
3. `AppMetadata $metadata`, an associative array bound to the app_metadata table in your database.
6. When it comes time for users to install the api, they can do it 'By Url' using `https://<install-url>/config.xml` and a key and secret from `https://<install-url>/admin/consumers.php`.
- Nota bene: the root [.htaccess](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/.htaccess) file does some jiggery-pokery to protect `*.inc.php` and `secrets.xml` _and_ it forces [config.xml](https://github.com/smtech/starter-canvas-api-via-lti/blob/master/config.xml) to be treated by Apache as a PHP file.
129 changes: 129 additions & 0 deletions metadata-example.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
<?xml version="1.0"?>
<!-- An example of what might be stored in the AppMetadata $metadata global, see config.xml for even more potential keys -->
<resultset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" statement="select `key`,`value`,`validate` from `app_metadata` ORDER by `key` ASC">
<row>
<field name="key">ACCOUNT_NAVIGATION</field>
<field name="value">FALSE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
<row>
<field name="key">APP_DESCRIPTION</field>
<field name="value">A starter app for building an LTI that makes use of the Canvas APIs.</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_DOMAIN</field>
<field name="value"/>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_ICON_URL</field>
<field name="value">@APP_URL/icon.png</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_ID</field>
<field name="value">canvas-api-via-lti-starter</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_LAUNCH_URL</field>
<field name="value">@APP_URL/launch.php</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_NAME</field>
<field name="value">Canvas API via LTI Starter</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_PATH</field>
<field name="value">/var/www/area51.stmarksschool.org/canvas/canvas-api-via-lti</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">APP_PRIVACY_LEVEL</field>
<field name="value">public</field>
<field name="validate">/public|name_only|anonymous/</field>
</row>
<row>
<field name="key">APP_URL</field>
<field name="value">https://area51.stmarksschool.org/canvas/canvas-api-via-lti</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">CANVAS_INSTANCE_URL</field>
<field name="value">https://stmarksschool.test.instructure.com</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">CANVAS_INSTANCE_URL_PLACEHOLDER</field>
<field name="value">https://stmarksschool.instructure.com</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">COURSE_NAVIGATION</field>
<field name="value">TRUE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
<row>
<field name="key">COURSE_NAVIGATION_DEFAULT</field>
<field name="value">enabled</field>
<field name="validate">/enabled|disabled/</field>
</row>
<row>
<field name="key">COURSE_NAVIGATION_ENABLED</field>
<field name="value">true</field>
<field name="validate">/true|false/</field>
</row>
<row>
<field name="key">COURSE_NAVIGATION_ICON_URL</field>
<field name="value">@APP_ICON_URL</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">COURSE_NAVIGATION_LAUNCH_URL</field>
<field name="value">@APP_LAUNCH_URL</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">COURSE_NAVIGATION_LINK_TEXT</field>
<field name="value">@APP_NAME</field>
<field name="validate" xsi:nil="true"/>
</row>
<row>
<field name="key">COURSE_NAVIGATION_VISIBILITY</field>
<field name="value">public</field>
<field name="validate">/public|members|admins/</field>
</row>
<row>
<field name="key">CUSTOM_FIELDS</field>
<field name="value">TRUE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
<row>
<field name="key">CUSTOM_FIELD_debug</field>
<field name="value">true</field>
<field name="validate">/true|false/</field>
</row>
<row>
<field name="key">EDITOR_BUTTON</field>
<field name="value">FALSE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
<row>
<field name="key">HOMEWORK_SUBMISSION</field>
<field name="value">FALSE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
<row>
<field name="key">RESOURCE_SELECTION</field>
<field name="value">FALSE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
<row>
<field name="key">USER_NAVIGATION</field>
<field name="value">FALSE</field>
<field name="validate">/TRUE|FALSE/</field>
</row>
</resultset>

0 comments on commit 316f71f

Please sign in to comment.