Placements

As stated in the LTI Overview, 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. It can be found here.

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 class.

As far as the front end goes, a list of placements with user-friendly names is also found in ExternalToolPlacementList, 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.jsx. As part of the LIME project, we also have some duplicated code that offers similar functionality in LtiPlacement.ts and i18nLtiPlacement.ts

Placements that support deep linking are listed and have configuration in Lti::Messages::DeepLinkingRequest.

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.
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.
4. Add an entry for the placement in the LtiPlacements, AllLtiPlacements, and LtiPlacementsByMessageType constants, as well as the user facing name of the placement to the LtiPlacementTranslations constant.
5. Add it to the list in the External Tools API Spec, following the example of this commit
6. Add an image of the new placement to the API docs. Make sure that you follow the naming convention of all of the other image files, to ensure we can easily link to our docs.
7. If this placement should accept deep links, or items of content returned from the tool, follow the instructions to configure it for that.