ylqjgm
/
canvas-lms
mirror of https://github.com/instructure/canvas-lms.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

lti manual: document adding new placements 

why:
* the process for configuring a placement for deep linking is already
documented but this process isn't

refs INTEROP-7294
flag=none

test plan:
* the information I wrote should be correct

Change-Id: Icc9f4a21dadac7897d65407c3a52fca2af6393d0
Reviewed-on: https://gerrit.instructure.com/c/canvas-lms/+/288620
Tested-by: Service Cloud Jenkins <svc.cloudjenkins@instructure.com>
Reviewed-by: Alexandre Trindade <alexandre.trindade@instructure.com>
QA-Review: Alexandre Trindade <alexandre.trindade@instructure.com>
Product-Review: Xander Moffatt <xmoffatt@instructure.com>
This commit is contained in:
Xander Moffatt 2022-03-31 09:24:40 -06:00
parent ba185bc3f0
commit c72cacb87b
2 changed files with 37 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/lti_manual/01_lti_overview.md
View File

@ -1,23 +1,24 @@
# LTI Overview
LTI stands for Learning Tools Interoperability and is a standard developed by IMS Global for interfacing between different learning tools. This provides a way for all LMSs and other EdTech products to speak the same language. Helpful links:
- [What is LTI and how it can improve your learning ecosystem | Moodle](https://moodle.com/news/what-is-lti-and-how-it-can-improve-your-learning-ecosystem/)
- [Learning Tools Interoperability Homepage | IMS Global Learning Consortium](https://www.imsglobal.org/activity/learning-tools-interoperability)
## Glossary of Core Concepts
- **Tool:** The main unit of LTI work, a singular piece of software that performs a task associated with the LMS. Examples include:
- submitting homework using Google Drive
- viewing a page of a textbook embedded in an assignment
- creating a meeting in a calendar event with Microsoft Teams
- submitting homework using Google Drive
- viewing a page of a textbook embedded in an assignment
- creating a meeting in a calendar event with Microsoft Teams
- **Tool Consumer/Platform:** an LMS like Canvas, who consumes external content from tools. "Tool Consumer" is from earlier iterations of the standard, and has since been simplified to "Platform".
- **Tool Provider:** External content that provides a tool. From earlier iterations of the standard, and is now discouraged in favor of "Tool".
- **Launch:** The act of loading a tool, usually within an iframe set in a Canvas page. The main way of interacting with LTI tools. Data in this case is flowing from Canvas to the LTI tool, in the form of an HTTP POST request.
- **Placement:** The place in the Canvas UI where an LTI link should be displayed. For example, the `course_navigation` placement indicates to Canvas that a link to the tool should be placed in the course navigation.
- **Placement:** The place in the Canvas UI where an LTI link should be displayed. For example, the `course_navigation` placement indicates to Canvas that a link to the tool should be placed in the course navigation. Note that although this concept never officially appears in the LTI spec, many if not all platforms that implement LTI have some sort of configuration for allowing the tool to be displayed in different places. For more information, see [the Placements page](./14_placements.md)
## Intro to Spec Versions
Canvas and IMS have historically worked hand-in-hand to develop new features and flesh out the core specifications of the LTI standard. This standard has gone through a few versions, all of which Canvas supports and implements in different ways. This is a main source of confusion when working on LTI in Canvas, since these versions are disparate and implemented very differently. In addition, some of these versions are now deprecated, and Canvas supports them only for backwards compatibility. Here is an overview of each of them:
Canvas and IMS have historically worked hand-in-hand to develop new features and flesh out the core specifications of the LTI standard. This standard has gone through a few versions, all of which Canvas supports and implements in different ways. This is a main source of confusion when working on LTI in Canvas, since these versions are disparate and implemented very differently. In addition, some of these versions are now deprecated, and Canvas supports them only for backwards compatibility. Here is an overview of each of them:
### LTI 1.1
@ -68,9 +69,9 @@ The advent of LTI 1.3 in 2019 promised all the same functionality as previous ve
#### Version-Specific Concepts
- **Deployment**: Commonly called an "installation" in Canvas LTI, the scope of contexts under which a tool is made available. For example, a tool can be deployed:
- in a single course
- in a root account, making it available to the whole institution
- in Site Admin, making it available to all Canvas customers
- in a single course
- in a root account, making it available to the whole institution
- in Site Admin, making it available to all Canvas customers
- **Link**: A reference to a Tool stored by a Platform, usually a URL that points to the Tool. Not just an HTML link, though, since other metadata can be included like files, images, or HTML.
- **Resource**: An item of content delivered by a tool, that's usually linked to something like assignment. A Link to a Resource is called, you guessed it, a Resource Link. Launching a tool using a Resource Link is the main form of interaction with a Tool.
- **Message**: One of the two main integrations between Platform and Tool. A Message comes from a user and their actions within their browser, such as clicking on an embedded link for an LTI Resource. This action initiates an OpenID login, which results in the platform passing the Message (a JWT) to the tool.
@ -83,4 +84,3 @@ More information about these are found in the spec [here](http://www.imsglobal.o
Rather than making a clean break in implementation as we did with LTI 2.0, the team decided to piggy-back on as much existing LTI 1.1 code as we could to quickly reach feature parity.
This worked very well in general, although some code may feel initially confusing without knowing it serves LTI 1.1 and LTI 1.3. More details on the LTI launch code can be found [here](./03_lti_launches).

28
doc/lti_manual/14_placements.md Normal file
View File

@ -0,0 +1,28 @@
# Placements
As stated in the [LTI Overview](./01_lti_overview.md), placements are an integral part of the LTI experience in Canvas even though they aren't officially supported by the LTI spec. The list of supported placements in Canvas has grown over the years as both internal and external customers require new functionality.
The officially-documented list of placements is found in the API docs, in the LTI -> Placements section of the sidebar, and contains these placements: - [course_navigation, account_navigation, user_navigation](https://canvas.instructure.com/doc/api/file.navigation_tools.html) - [homework_submission](https://canvas.instructure.com/doc/api/file.homework_submission_placement.html) - [editor_button](https://canvas.instructure.com/doc/api/file.editor_button_placement.html) - [migration_selection](https://canvas.instructure.com/doc/api/file.migration_selection_placement.html) - [link_selection](https://canvas.instructure.com/doc/api/file.link_selection_placement.html) - [assignment_selection](https://canvas.instructure.com/doc/api/file.assignment_selection_placement.html) - [collaborations](https://canvas.instructure.com/doc/api/file.collaborations_placement.html)
The difference between this and the full list of supported placements is partially due to lack of documentation as new placements are added, but also because some placements were made for internal use and so aren't really mentioned to external customers.
## Definition and Configuration
Placement configuration and definition is currently somewhat scattered across a few different places in Canvas (and is ripe for consolidation).
The definitive list of all supported placements in Canvas is currently found in the [`Lti::ResourcePlacement`](/app/models/lti/resource_placement.rb) class.
As far as the front end goes, a list of placements with user-friendly names is also found in [`ExternalToolPlacementList`](/ui/features/external_apps//react/components/ExternalToolPlacementList.js), used by the External Apps UI to display a list of enabled placements for a tool, and the Developer Keys UI constructs the user-friendly name dynamically (and sadly not-i18n-ed either) in [`Placements.js`](/ui/features/developer_keys_v2/react/ManualConfigurationForm/Placements.js).
Placements that support [deep linking](./12_deep_linking.md) are listed and have configuration in [`Lti::Messages::DeepLinkingRequest`](/lib/lti/messages/deep_linking_request.rb).
## Adding a New Placement
Congratulations! If you have made it here, you have been tasked with adding a new placement in Canvas. It's up to you to work with product and design to figure out what this looks like and where it goes, but here are steps to help Canvas and LTI tools recognize this as a valid placement:
1. Choose a name for your new placement. It should describe roughly where it appears and be relatively short. Recent examples include `course_assignments_menu` and `module_index_menu_modal`.
2. Add the new placement to the list in [`Lti::ResourcePlacement::PLACEMENTS`](/app/models/lti/resource_placement.rb).
3. Add it and its user-friendly name (usually just the name of placement capitalized and spaced, eg "Course Assignments Menu" or "Module Index Menu (Modal)") to [`ExternalToolPlacementList.ALL_PLACEMENTS`](/ui/features/external_apps//react/components/ExternalToolPlacementList.js).
4. Add it to the list in [`Schemas::Lti::ToolConfiguration::SCHEMA`](/lib/schemas/lti/tool_configuration.rb), under extensions -> settings -> placements -> placement -> enum.
5. Add it to the list in the [External Tools API Spec](/spec/apis/v1/external_tools_api_spec.rb), following the example of [this commit](https://gerrit.instructure.com/c/canvas-lms/+/287770/6/spec/apis/v1/external_tools_api_spec.rb)
6. If this placement should accept deep links, or items of content returned from the tool, follow the [instructions](./12_deep_linking.md) to configure it for that.