From 85c625c40ad873d0efac33f8a63c1ee256185e36 Mon Sep 17 00:00:00 2001 From: Peter Amstutz Date: Wed, 22 Mar 2023 16:57:49 -0400 Subject: [PATCH] 20259: Add documentation for banner and tooltip features Arvados-DCO-1.1-Signed-off-by: Peter Amstutz --- doc/_config.yml | 1 + doc/install/setup-login.html.textile.liquid | 16 ++-- doc/install/workbench.html.textile.liquid | 90 +++++++++++++++++++++ 3 files changed, 99 insertions(+), 8 deletions(-) create mode 100644 doc/install/workbench.html.textile.liquid diff --git a/doc/_config.yml b/doc/_config.yml index 35dfe03ae3..4f86253018 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -242,6 +242,7 @@ navbar: - install/install-ws.html.textile.liquid - install/install-workbench-app.html.textile.liquid - install/install-workbench2-app.html.textile.liquid + - install/workbench.html.textile.liquid # - install/install-composer.html.textile.liquid - Additional services: - install/install-shell-server.html.textile.liquid diff --git a/doc/install/setup-login.html.textile.liquid b/doc/install/setup-login.html.textile.liquid index 47d0c21bea..21b986fb89 100644 --- a/doc/install/setup-login.html.textile.liquid +++ b/doc/install/setup-login.html.textile.liquid @@ -35,26 +35,26 @@ Use the Google D # Add the Redirect URI: @https://ClusterID.example.com/login@ # Copy the values of *Client ID* and *Client secret* to the @Login.Google@ section of @config.yml@. -
+{% codeblock as yaml %}
     Login:
       Google:
         Enable: true
         ClientID: "0000000000000-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.apps.googleusercontent.com"
         ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
-
+{% endcodeblock %} h2(#oidc). OpenID Connect With this configuration, users will sign in with a third-party OpenID Connect provider. The provider will supply appropriate values for the issuer URL, client ID, and client secret config entries. -
+{% codeblock as yaml %}
     Login:
       OpenIDConnect:
         Enable: true
         Issuer: https://accounts.example.com/
         ClientID: "0123456789abcdef"
         ClientSecret: "zzzzzzzzzzzzzzzzzzzzzzzz"
-
+{% endcodeblock %} Check the OpenIDConnect section in the "default config file":{{site.baseurl}}/admin/config.html for more details and configuration options. @@ -64,7 +64,7 @@ With this configuration, authentication uses an external LDAP service like OpenL Enable LDAP authentication and provide your LDAP server's host, port, and credentials (if needed to search the directory) in @config.yml@: -
+{% codeblock as yaml %}
     Login:
       LDAP:
         Enable: true
@@ -72,7 +72,7 @@ Enable LDAP authentication and provide your LDAP server's host, port, and creden
         SearchBindUser: cn=lookupuser,dc=example,dc=com
         SearchBindPassword: xxxxxxxx
         SearchBase: ou=Users,dc=example,dc=com
-
+{% endcodeblock %} The email address reported by LDAP will be used as primary key for Arvados accounts. This means *users must not be able to edit their own email addresses* in the directory. @@ -90,11 +90,11 @@ With this configuration, authentication is done according to the Linux PAM ("Plu Enable PAM authentication in @config.yml@: -
+{% codeblock as yaml %}
     Login:
       PAM:
         Enable: true
-
+{% endcodeblock %} Check the "default config file":{{site.baseurl}}/admin/config.html for more PAM configuration options. diff --git a/doc/install/workbench.html.textile.liquid b/doc/install/workbench.html.textile.liquid new file mode 100644 index 0000000000..9e08b56e6f --- /dev/null +++ b/doc/install/workbench.html.textile.liquid @@ -0,0 +1,90 @@ +--- +layout: default +navsection: installguide +title: Customizing Workbench +... +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. + +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} + +h2. Site name + +Use the @Workbench.SiteName@ configuration option to set the site name rendered at the top of Workbench. + +{% codeblock as yaml %} + Workbench: + SiteName: Arvados Workbench +{% endcodeblock %} + +h2. Welcome page + +Use the @Workbench.WelcomePageHTML@ configuration option to set the text that is rendered when a user arrives at the front page (and has not yet logged in). + +{% codeblock as yaml %} + Workbench: + WelcomePageHTML: | + +

Please log in.

+ +

If you have never used Arvados Workbench before, logging in + for the first time will automatically create a new + account.

+ + Arvados Workbench uses your information only for + identification, and does not retrieve any other personal + information. +{% endcodeblock %} + +h2. Inactive user page + +Use the @Workbench.InactivePageHTML@ configuration option to set the text that is rendered when a user logs in but is inactive. + +{% codeblock as yaml %} + Workbench: + InactivePageHTML: | + +

Hi! You're logged in, but...

+

Your account is inactive.

+

An administrator must activate your account before you can get + any further.

+{% endcodeblock %} + +h2(#banner). Message banner on login and custom tooltips + +Set the @Workbench.BannerUUID@ configuration option to the UUID of a collection. *This collection should be shared with all users.* + +{% codeblock as yaml %} + Workbench: + BannerUUID: zzzzz-4zz18-0123456789abcde +{% endcodeblock %} + +h3. Banner + +You can have box pop up when users load Workbench to give information such as links to site-specific documentation or notification about anticipated downtime. + +The banner appears when a user loads workbench and have not yet viewed the current banner text. Users can also view the banner after dismissing it by selecting the *Restore Banner* option from the *Notifications* menu. + +The banner text (HTML formatted) is loaded from the file @banner.html@ in the collection provided in @BannerUUID@. + +h3. Tooltips + +You can provide a custom tooltip overlay to provide site-specific guidance for using workbench. Users can opt-out by selecting *Disable Tooltips* from the *Notifications* menu. + +The tooltips are loaded from the file @tooltips.json@ in the collection provided in @BannerUUID@. + +The format of this file is a JSON object where the key is a "CSS selector":https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors and the value is the text of the tooltip. Here is an example: + +{% codeblock as yaml %} +{ + "[data-cy=side-panel-button]": "Click here to create a new project!", + "[data-cy=project-panel] tbody tr:nth-child(1)": "First element in the project list" +} +{% endcodeblock %} + +The first example adds a tooltip displaying "Click here to create a new project!" to the HTML node with the attribute @data-cy="side-panel-button"@. + +The second example adds a tooltip displaying "First element in the project list" by finding the project panel element, finding the table body element within the project panel, then matching the first table row. + +Use the web developer tools offer by your browser to determine what identifiers are available and construct selections that will anchor your tooltips to the desired workbench components. -- 2.30.2