Add external_tools user_navigation documentation

refs PLAT-2827 Test Plan: n/a Change-Id: I9981b29902d51b22f08048b3f020a035b1941f94 Reviewed-on: https://gerrit.instructure.com/140007 Tested-by: Jenkins Reviewed-by: Weston Dransfield <[email protected]> QA-Review: August Thornton <[email protected]> Product-Review: Marc Alan Phillips <[email protected]>
sjaveed · Feb 6, 2018 · bfc4d1b · bfc4d1b
1 parent e580e06
commit bfc4d1b
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 25 deletions.
diff --git a/app/controllers/external_tools_controller.rb b/app/controllers/external_tools_controller.rb
@@ -334,7 +334,16 @@ def sessionless_launch
   #        "migration_selection": null,
   #        "resource_selection": null,
   #        "tool_configuration": null,
-  #        "user_navigation": null,
+  #        "user_navigation": {
+  #             "canvas_icon_class": "icon-lti",
+  #             "icon_url": "...",
+  #             "text": "...",
+  #             "url": "...",
+  #             "default": "disabled",
+  #             "enabled": "true",
+  #             "visibility": "public",
+  #             "windowTarget": "_blank"
+  #        },
   #        "selection_width": 500,
   #        "selection_height": 500,
   #        "icon_url": "...",
@@ -634,6 +643,10 @@ def content_item_selection_request(tool, placement, opts = {})
   # @argument user_navigation[text] [String]
   #   The text that will show on the left-tab in the user navigation
   #
+  # @argument user_navigation[visibility] [String, "admins"|"members"|"public"]
+  #   Who will see the navigation tab. "admins" for admins, "public" or
+  #   "members" for everyone
+  #
   # @argument course_home_sub_navigation[url] [String]
   #   The url of the external tool for right-side course home navigation menu
   #

diff --git a/doc/api/navigation_tools.md b/doc/api/navigation_tools.md
@@ -4,42 +4,42 @@ Navigation Tools
 <a name="course_navigation"></a>
 ## Course navigation links
 
-External tools can be configured to appear as links in course-level 
-navigation. If the tool is configured on an account, any course in 
-that account or any of its sub-accounts will have the link added to 
-the course navigation. If the tool is configured on a course, then 
+External tools can be configured to appear as links in course-level
+navigation. If the tool is configured on an account, any course in
+that account or any of its sub-accounts will have the link added to
+the course navigation. If the tool is configured on a course, then
 the navigation will only appear in that course.
 
 
-There are some additional parameters that can be set on course 
-navigation tools to define default behavior. These settings allow 
-the tool to be disabled by default or visible only to some types 
+There are some additional parameters that can be set on course
+navigation tools to define default behavior. These settings allow
+the tool to be disabled by default or visible only to some types
 of users.
 
 
 ### Settings
 All of these settings are contained under "course_navigation"
 
 -   url: &lt;url&gt; (optional)
-    
+
     This is the URL that will be POSTed to when users click the left tab. It can be the same as the tool's URL, or something different. Domain and URL matching are not enforced for course navigation links. In order to prevent security warnings for users, it is recommended that this URL be over SSL (https).
     This is required if a url is not set on the main tool configuration.
 
 -   default: ['enabled', 'disabled'] (optional, 'enabled' by default)
-    
+
     This specifies whether the link is turned on or off by default for courses. Course administrators will see the link appear in Settings just like any other link, and can explicitly order, enable and disable the link from there.
 
 -   visibility: ['public', 'members', 'admins'] (optional, 'public' by default)
-    
+
     This specifies what types of users will see the link in the course navigation. "public" means anyone accessing the course, "members" means only users enrolled in the course, and "admins" means only Teachers, TAs, Designers and account admins will see the link.
 
 -   text: &lt;text&gt; (optional)
-    
+
     This is the default text that will be shown in the left hand navigation as the text of the link. This can be overridden by language-specific settings if desired by using the labels setting.
     This is required if a text value is not set on the main tool configuration.
 
 -   labels: &lt;set of locale-label pairs&gt; (optional)
-    
+
     This can be used to specify different label names for different locales. For example, if an institution supports both English and Spanish interfaces, the text in the link should change depending on the language being displayed. This option lets you support multiple languages for a single tool.
 
 -   enabled: &lt;boolean&gt; (required)
@@ -48,17 +48,17 @@ All of these settings are contained under "course_navigation"
 
 <a name="account_navigation"></a>
 ## Account navigation links
-External tools can also be configured to appear as links in 
-account-level navigation. If the tool is configured on an account, 
-administrators in that account and any of its sub-accounts will see 
+External tools can also be configured to appear as links in
+account-level navigation. If the tool is configured on an account,
+administrators in that account and any of its sub-accounts will see
 the link in their account navigation.
 
 
 ### Settings
 All of these settings are contained under "account_navigation"
 
 -   url: &lt;url&gt; (optional)
-    
+
     This is the URL that will be POSTed to when users click the left tab. It can be the same as the tool's URL, or something different. Domain and URL matching are not enforced for account navigation links. In order to prevent security warnings for users, it is recommended that this URL be over SSL (https).
     This is required if a url is not set on the main tool configuration.
 
@@ -68,7 +68,7 @@ All of these settings are contained under "account_navigation"
     This is required if a text value is not set on the main tool configuration.
 
 -   labels: &lt;set of locale-label pairs&gt; (optional)
-    
+
     This can be used to specify different label names for different locales. For example, if an institution supports both English and Spanish interfaces, the text in the link should change depending on the language being displayed. This option lets you support multiple languages for a single tool.
 
 -   enabled: &lt;boolean&gt; (required)
@@ -77,19 +77,19 @@ All of these settings are contained under "account_navigation"
 
 <a name="user_navigation"></a>
 ## User navigation links
-External tools can also be configured to appear as links in 
-user-level navigation (i.e. by clicking to see a user's profile). 
-User navigation links will only work if they are configured at 
-the root account level. If the tool is configured on a root account, 
-all users logged in to that account will see the link in their 
+External tools can also be configured to appear as links in
+user-level navigation (i.e. by clicking to see a user's profile).
+User navigation links will only work if they are configured at
+the root account level. If the tool is configured on a root account,
+all users logged in to that account will see the link in their
 profile navigation.
 
 
 ### Settings
 All of these settings are contained under "user_navigation"
 
 -   url: &lt;url&gt; (optional)
-  
+
     This is the URL that will be POSTed to when users click the left tab. It can be the same as the tool's URL, or something different. Domain and URL matching are not enforced for user navigation links. In order to prevent security warnings for users, it is recommended that this URL be over SSL (https).
     This is required if a url is not set on the main tool configuration.
 
@@ -99,9 +99,14 @@ All of these settings are contained under "user_navigation"
     This is required if a text value is not set on the main tool configuration.
 
 -   labels: &lt;set of locale-label pairs&gt; (optional)
-    
+
     This can be used to specify different label names for different locales. For example, if an institution supports both English and Spanish interfaces, the text in the link should change depending on the language being displayed. This option lets you support multiple languages for a single tool.
 
 -   enabled: &lt;boolean&gt; (required)
 
     Whether to enable this selection feature.
+
+-   visibility: ['public', 'members', 'admins'] (optional, 'public' by default)
+
+    This specifies what types of users will see the link in the user navigation. "public" and "members" means anyone will see it, and "admins" means only account admins will see the link.
+