diff --git a/docs/Client/configuration.md b/docs/Client/configuration.md index c22734c..2c6624e 100644 --- a/docs/Client/configuration.md +++ b/docs/Client/configuration.md @@ -39,6 +39,8 @@ try { } ``` +## All configuration options {#all-options} + | Key | Type | Description | Default | Required? | |-------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:| | `auth/api_key` | `string` | The TrustedLogin key for the vendor, found in "API Keys" on https://app.trustedlogin.com. | `null` | ✅ | diff --git a/docs/Client/customization.md b/docs/Client/customization.md new file mode 100644 index 0000000..8523d1d --- /dev/null +++ b/docs/Client/customization.md @@ -0,0 +1,243 @@ +--- +title: Template Customization +sidebar: auto +--- + +# Customizing the TrustedLogin Template + +The TrustedLogin template is designed to be easily customized to match your brand. This guide will walk you through the steps to customize the template. + +[Reference the hooks](hooks#trustedloginnamespacetemplateauth) doc for more information on how to customize the template using hooks. + +:::tip +By removing placeholders you don't need, or replacing the placeholders with your preferred HTML, you can customize all output generated by the TrustedLogin Client. +::: + +## The Grant Support Access Template + +You can modify the Grant Support Access auth form by using the [`trustedlogin/{{ns}}/template/auth` filter](hooks#trustedloginnamespacetemplateauth). + +This is the default HTML structure of the Grant Support Access form: + +```html +
+ {{header}} +
+

+ {{intro}} +

+
+
+ {{auth_header}} +
+
+ {{details}} +
+
+ {{notices}} +
+ {{button}} +
+ {{terms_of_service}} +
+
{{secured_by_trustedlogin}}
+
+ + {{admin_debug}} +
+``` + +### `{{header}}` placeholder + +The header of the auth form outputs the logo of the vendor. + +It is only displayed on the Grant Auth screen, not on the `wp-login.php` screen. + +```html +
+ +
+``` + +### `{{intro}}` placeholder + +The `{{intro}}` placeholder is the introductory text displayed at the top of the Grant Support Access form. + +Based on the context, the `{{intro}}` placeholder will be replaced with one of the following: + +- **Access has been granted:**
+`Vendor Display Name has site access that expires in [expiration time].` +- **On the login screen:**
+`Vendor Display Name would like support access to this site.` +- **On the Grant Support Access screen:**
+`Grant Vendor Display Name access to this site.` + +### `{{auth_header}}` placeholder + +If there are no active Support Users, this placeholder will not be rendered. + +If there are, the auth header shows the display name of the Support User, information about who granted access, and the Revoke Access button. + +#### Screenshot + +![A screenshot of the Grant Support Access form with the placeholder parts highlighted.](/img/client/form-auth-header.png) + +### `{{details}}` placeholder + +The `{{details}}` placeholder contains the bulk of the content of the Grant Support Access form. + +#### Screenshot + +![A screenshot of the Grant Support Access form with the placeholder parts highlighted.](/img/client/form-details.png) + +```html +

This will allow {{name}} to:

+
+

+ {{roles_summary}} +

+ {{caps}} +
+
+

+ {{expire_summary}}{{expire_desc}} +

+
+``` + +#### `{{roles_summary}}` placeholder + +If cloning roles is disabled (using the `clone_role` configuration setting), the `{{roles_summary}}` placeholder is replaced by `Create a user with a role of {{role}}.`. + +##### If cloning roles is enabled + +When cloning roles is enabled, `{{roles_summary}}` is replaced by `Create a user with a role based on {{cloned_role}}.`. Further, if custom capabilities are defined (using the `caps/remove` or `caps/add` configuration settings) are set, the `{{caps}}` placeholder will be rendered. + +#### Screenshot + +![The capabilities display, showing additional capabilities that have been added or removed from the cloned role.](/img/client/form-caps.png) + +### `{{notices}}` placeholder + +The `{{notices}}` placeholder is displayed when TrustedLogin is running on a local website that will not be accessible to support. + +It is disabled when `wp_get_environment_type()` is "staging" or "production", so it will not be displayed on a live site. + +#### Screenshot + +![A screenshot of the Grant Support Access form with the notice circled with a green border.](/img/client/form-notices.png) + +#### Settings available + +- `vendor/about_live_access_url` - The URL to the vendor's documentation about live access. Defaults to `https://www.trustedlogin.com/about/live-access/`. + +#### Constants available + +`TRUSTEDLOGIN_DISABLE_LOCAL_NOTICE` - Set to `true` to disable the local notice. + +### `{{button}}` placeholder + +The button to grant or extend access to the support user. Generated by the `TrustedLogin\Form::generate_button()` placeholder. + +- If access **has** been granted to the website, the button text will be "Extend [Vendor Display Name] Support Access". +- If access **has not** been granted, the button text will be "Grant [Vendor Display Name] Support Access". + +Here is sample HTML output for the button: + +#### Screenshot + +```html +Grant [Vendor Display Name] Support Access +``` + +![A screenshot of the Grant Support Access form with the button circled with a green border.](/img/client/form-button.png) + +### `{{reference}}` placeholder + +If reference IDs are being displayed (controlled by the [`trustedlogin/{namespace}/template/auth/display_reference`](#trustedloginnamespacetemplateauthdisplay_reference) filter, render the reference ouput. + +```html +

{{reference_text}}

+``` + +#### Screenshots + +![A screenshot of the Grant Support Access form with the reference ID section circled with a green border.](/img/client/form-reference.png) + +#### Filters available + +- [`trustedlogin/{{ns}}/template/auth/display_reference`](hooks#trustedloginnamespacetemplateauthdisplay_reference) filter to control whether the reference ID is displayed. + +### `{{terms_of_service}}` placeholder + +If the [`terms_of_service/url` setting](configuration#all-options) is not defined, the terms of service output will not be rendered. + +If there is a URL defined for Terms of Service, a link to terms of service will be rendered. The anchor text defaults to "Terms of Service". + +#### HTML output + +```html +
+

+ Terms of Service +

+
+``` + +#### Screenshots + +![A screenshot of the Grant Support Access form with the Terms of Service link circled with a green border.](/img/client/form-tos.png) + +#### Available filters + +- [`trustedlogin/{{ns}}/template/auth/terms_of_service/anchor`](hooks#trustedloginnamespacetemplateauthterms_of_serviceanchor) filter to modify the "Terms of Service" anchor text. + +### `{{secured_by_trustedlogin}}` placeholder + +The "Secured by TrustedLogin" text. + +```html +

{{secured_by_trustedlogin}}

+``` + +### `{{admin_debug}}` placeholder + +The admin debug output. Only displayed if the user has `manage_options` capability and `$_GET['debug']` is set. + +- TrustedLogin Status: `Online` or `Offline` +- API Key: The API key used to authenticate with the TrustedLogin API +- License Key: If a license key is set, it will be displayed here +- Log URL: A link to download the log file +- Log Level: The log level set in the TrustedLogin settings +- Webhook URL: The URL to the webhook endpoint, if set. `Empty` if not set. +- Vendor Public Key: The public encryption key of the vendor, with a link to verify the key + +## Examples of Customization + +### Customizing the Grant Support Access Form + +To customize the Grant Support Access form, you can use the `trustedlogin/{{ns}}/template/auth` filter. + +Here is an example of how to customize the Grant Support Access form: + +```php +// Replace `{{ns}}` with the namespace of your configuration. +add_filter( 'trustedlogin/{{ns}}/template/auth', 'RENAME_THIS_FUNCTION_remove_header', 10 ); + +/** + * Remove the header, including the logo, from the Grant Support Access form. + * + * This is an example function name! Replace `RENAME_THIS_FUNCTION_remove_header` with a unique function name. + * + * @param string $auth_screen_template The HTML template of the Grant Support Access form. + * @return string + */ +function RENAME_THIS_FUNCTION_remove_header( $auth_screen_template ) { + return str_replace( '{{header}}', '', $auth_screen_template ); +} +``` diff --git a/docs/Client/hooks.md b/docs/Client/hooks.md index 2fc59ef..c0f77ce 100644 --- a/docs/Client/hooks.md +++ b/docs/Client/hooks.md @@ -119,33 +119,6 @@ Override the structure of the auth form HTML. |-------------------------|----------|------------------------------------|----------------------------------------------------------| | `$auth_screen_template` | `string` | HTML with placeholders (see below) | The structure for the auth form HTML, with placeholders. | -```html - -
- {{header}} -
-

{{intro}}

-
-
- {{auth_header}} -
-
- {{details}} -
-
- {{notices}} -
- {{button}} -
-
-
{{secured_by_trustedlogin}}
-
- -
-``` ### `trustedlogin/{namespace}/template/auth/display_reference` {#trustedloginnamespacetemplateauthdisplay_reference} diff --git a/src/css/custom.css b/src/css/custom.css index 496cba3..91bf27a 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -18,10 +18,13 @@ --ifm-code-font-size: 95%; --ifm-navbar-height: 80px; --ifm-container-width-xl: 1480px; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.05); + --docusaurus-highlighted-toc-item-bg: rgba(0, 0, 0, 0.05); } html[data-theme='dark'] { --ifm-color-primary: var( --ifm-color-primary-light ); + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, .2); } .footer__link-item:hover { color: var(--ifm-color-primary-lightest); @@ -64,10 +67,8 @@ html[data-theme='dark'] article a:visited { overflow: hidden; }*/ - - .docusaurus-highlight-code-line { - background-color: rgba(0, 0, 0, 0.1); + background-color: var( --docusaurus-highlighted-code-line-bg ); display: block; margin: 0 calc(-1 * var(--ifm-pre-padding)); padding: 0 var(--ifm-pre-padding); @@ -76,3 +77,21 @@ html[data-theme='dark'] article a:visited { html[data-theme='dark'] .docusaurus-highlight-code-line { background-color: rgba(0, 0, 0, 0.3); } + +.table-of-contents li a { + font-size: calc( var(--ifm-font-size-base) * 1.1); + font-weight: var(--ifm-font-weight-semibold); + margin: calc( var( --ifm-list-item-margin ) * 3 ) 0; +} + +.table-of-contents li a.table-of-contents__link--active { + font-weight: var(--ifm-font-weight-bold); + /*background: var(--docusaurus-highlighted-toc-item-bg);*/ + /*padding-top: calc( var(--ifm-list-margin) / 3 ); + padding-bottom: calc( var(--ifm-list-margin) / 3 );*/ +} + +.table-of-contents li li a { + font-weight: var(--ifm-font-weight-normal); + margin: var( --ifm-list-item-margin ); +} diff --git a/static/img/client/form-auth-header.png b/static/img/client/form-auth-header.png new file mode 100644 index 0000000..099a365 Binary files /dev/null and b/static/img/client/form-auth-header.png differ diff --git a/static/img/client/form-button.png b/static/img/client/form-button.png new file mode 100644 index 0000000..f91949c Binary files /dev/null and b/static/img/client/form-button.png differ diff --git a/static/img/client/form-caps.png b/static/img/client/form-caps.png new file mode 100644 index 0000000..70f9676 Binary files /dev/null and b/static/img/client/form-caps.png differ diff --git a/static/img/client/form-details.png b/static/img/client/form-details.png new file mode 100644 index 0000000..7673d71 Binary files /dev/null and b/static/img/client/form-details.png differ diff --git a/static/img/client/form-notices.png b/static/img/client/form-notices.png new file mode 100644 index 0000000..b098208 Binary files /dev/null and b/static/img/client/form-notices.png differ diff --git a/static/img/client/form-reference.png b/static/img/client/form-reference.png new file mode 100644 index 0000000..f0b2bdf Binary files /dev/null and b/static/img/client/form-reference.png differ diff --git a/static/img/client/form-tos.png b/static/img/client/form-tos.png new file mode 100644 index 0000000..9933ec7 Binary files /dev/null and b/static/img/client/form-tos.png differ