Skip to content

Commit

Permalink
Add Customization page
Browse files Browse the repository at this point in the history
  • Loading branch information
zackkatz committed Apr 19, 2024
1 parent a7e61db commit 22a0137
Show file tree
Hide file tree
Showing 11 changed files with 267 additions and 30 deletions.
2 changes: 2 additions & 0 deletions docs/Client/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` ||
Expand Down
243 changes: 243 additions & 0 deletions docs/Client/customization.md
Original file line number Diff line number Diff line change
@@ -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
<div class="tl-{{ns}}-auth tl-{{ns}}-{{has_access_class}}">
{{header}}
<section class="tl-{{ns}}-auth__body">
<h2 class="tl-{{ns}}-auth__intro">
{{intro}}
</h2>
<div class="tl-{{ns}}-auth__content">
<header class="tl-{{ns}}-auth__header">
{{auth_header}}
</header>
<div class="tl-{{ns}}-auth__details">
{{details}}
</div>
<div class="tl-{{ns}}-auth__response" aria-live="assertive"></div>
{{notices}}
<div class="tl-{{ns}}-auth__actions">
{{button}}
</div>
{{terms_of_service}}
</div>
<div class="tl-{{ns}}-auth__secured_by">{{secured_by_trustedlogin}}</div>
</section>
<footer class="tl-{{ns}}-auth__footer">
{{footer}}
{{reference}}
</footer>
{{admin_debug}}
</div>
```

### `{{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
<header class="tl-{{ns}}-auth__header__top">
<div class="tl-{{ns}}-auth__logo">
<a href="{{vendor/website}}" title="Visit the {{vendor/title}} website (opens in a new tab)" target="_blank" rel="noreferrer noopener"><img src="{{vendor/logo_url}}" alt="{{vendor/title}}" /></a>
</div>
</header>
```

### `{{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:**<br />
`<a href="{{vendor/website}}">Vendor Display Name</a> has site access that expires in [expiration time].`
- **On the login screen:**<br />
`<a href="{{vendor/website}}">Vendor Display Name</a> would like support access to this site.`
- **On the Grant Support Access screen:**<br />
`Grant <a href="{{vendor/website}}">Vendor Display Name</a> 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
<p><span class="dashicons dashicons-info-outline dashicons--small"></span> This will allow <strong>{{name}}</strong> to:</p>
<div class="tl-{{ns}}-auth__roles">
<h2>
<span class="dashicons dashicons-admin-users dashicons--large"></span>{{roles_summary}}
</h2>
{{caps}}
</div>
<div class="tl-{{ns}}-auth__expire">
<h2>
<span class="dashicons dashicons-clock dashicons--large"></span>{{expire_summary}}{{expire_desc}}
</h2>
</div>
```

#### `{{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 <strong>{{role}}</strong>.`.

##### If cloning roles is enabled

When cloning roles is enabled, `{{roles_summary}}` is replaced by `Create a user with a role based on <strong>{{cloned_role}}</strong>.`. 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
<a href="{{vendor/support_url}}" class="button button-hero authlink button-primary tl-client-grant-button button-trustedlogin-{{ns}}" data-access="grant">Grant [Vendor Display Name] Support Access</a>
```

![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
<div class="tl-{{ns}}-auth__ref"><p><span class="tl-{{ns}}-auth_ref__id">{{reference_text}}</span></p></div>
```

#### 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
<div class="tl-{{ns}}-auth__tos">
<p>
<a href="{{terms_of_service/url}}" target="_blank" rel="noopener noreferrer">Terms of Service</a>
</p>
</div>
```

#### 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
<p class="tl-{{ns}}-auth__secured_by">{{secured_by_trustedlogin}}</p>
```

### `{{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 );
}
```
27 changes: 0 additions & 27 deletions docs/Client/hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

<div class="tl-{{ns}}-auth tl-{{ns}}-{{has_access_class}}">
{{header}}
<section class="tl-{{ns}}-auth__body">
<h2 class="tl-{{ns}}-auth__intro">{{intro}}</h2>
<div class="tl-{{ns}}-auth__content">
<header class="tl-{{ns}}-auth__header">
{{auth_header}}
</header>
<div class="tl-{{ns}}-auth__details">
{{details}}
</div>
<div class="tl-{{ns}}-auth__response" aria-live="assertive"></div>
{{notices}}
<div class="tl-{{ns}}-auth__actions">
{{button}}
</div>
</div>
<div class="tl-{{ns}}-auth__secured_by">{{secured_by_trustedlogin}}</div>
</section>
<footer class="tl-{{ns}}-auth__footer">
{{footer}}
{{reference}}
</footer>
</div>
```

### `trustedlogin/{namespace}/template/auth/display_reference` {#trustedloginnamespacetemplateauthdisplay_reference}

Expand Down
25 changes: 22 additions & 3 deletions src/css/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand All @@ -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 );
}
Binary file added static/img/client/form-auth-header.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/client/form-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/client/form-caps.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/client/form-details.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/client/form-notices.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/client/form-reference.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/client/form-tos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 22a0137

Please sign in to comment.