đź‘‹ Check our new docs

WordPress Plugin

This page provides documentation for the Unlock WordPress plugin.

Introduction

Welcome to Unlock Protocol WordPress plugin user manual.

This manual documents all the basic interactions with the WordPress dashboard and editing interface as relates to the plugin. It assumes a fresh install of the latest WordPress version (v5.8.2 at time of writing).

Unlock Protocol provides a paywall to unlock content inside of pages and posts so that only authorized users can access them. It is an updated version of an earlier version of this plugin.

The plugin is designed to be a plug-and-play solution for site owners who want to control access to their content by their readers or visitors.

The two main interfaces are the Settings page and Gutenberg block. Both of these items will be covered below.

Basics: Logging in to WordPress

This section is written for the benefit of anyone who is new to WordPress. Skip ahead to the main section if you are already familiar with WordPress.

In order to use or configure the Unlock Protocol plugin (henceforth referred to simply as the “plugin”), you need to first access WordPress’ backend, also known as the Dashboard. To do so, replace [Your URL] below with your website’s link.

  • Login URL: [YourURL]/wp-admin

You will need to login as an Admin account to install and configure the plugin.

Figure: Unlock Protocol’s Login Screen

Once you’ve logged in, the WordPress dashboard appears. Below is a screenshot of what your dashboard might resemble. This is where you can access the different sections of your website, including different types of content (pages, posts, comments), administrative settings & tools, as well as the plugins and themes installed. Contact your website administrator for more details.

Read more about the Dashboard on the WordPress.org.

Figure: WordPress default Dashboard

The Unlock Protocol Plugin

Once installed and configured, the Unlock Protocol plugin will provide a way to add locks to content inside of WordPress. Only authorized users can access this locked content.

How to Install the Plugin

  1. Go to Plugins > Add New

  2. Click on the Upload plugin

  3. Upload the provided plugin zip and click on Install Now

  4. Once the plugin is installed, click on Activate Plugin

Figure: Install a plugin

This and other plugins can be managed from the Plugins tab in the left navigation menu. Read more about managing plugins.

Special Notes

  1. For the plugin to work as expected, make sure that Settings > General > Anyone can register is enabled. On a fresh install of WordPress this option is disabled by default. The Unlock Protocol plugin will display a warning in the Dashboard if this is the case.

  2. If you are upgrading from an earlier version of the plugin (earlier than v3.0.0), briefly deactivate and re-activate the plugin in order for the default networks to show up in the Network Settings and in the Ethereum Network setting of the Gutenberg block **** as noted below.

Figure: Dashboard warning to the website admin if new user registration is blocked.

Plugin Settings

Once installed and activated, no change will appear on the website from an end user’s perspective. The plugin activates with a reasonable set of presets so that it can even be used as-is.

However, customization of the Unlock & Checkout buttons and addition of new Ethereum networks is also possible through the plugin’s settings. To access them, go to the WordPress Dashboard > Settings > Unlock Protocol. This will open up a page with two tabs at the top — General & Networks.

General Settings

Settings in this tab are related to customization of the Unlock and Checkout buttons.

Figure: General settings

  • Login button text

Used to define text that will appear within the button that prompts your users to log into WordPress using their WordPress credentials or via Unlock Protocol OAuth. If left blank, the button will display “Login with Unlock”. Note: The button that appears on the login screen will always display the string “Connect Your Crypto Wallet”. This is hard coded into the plugin.

  • Login button type

If enabled, the Unlock button will output a preset or user defined image (via the Upload login background image field). For best results, the image should not exceed 300px in height. The width of any uploaded image will be either the width of the uploaded image or the width of the content block within which it is placed, whichever is smaller.

You can select an image from your media library or upload a new one, which is then added to your media library.

  • Call to action text

Defines the string displayed above the Login button in the image block. Uses the same color as the Login button text color by default. Can be changed via hooks.

  • Login button background color

Defines the background color of the Login button in hex, RGB or HSL formats. By default, the color is black (#000000).

  • Login button text color

Defines the background color of the Login button in hex, RGB or HSL formats. By default, the color is white (#ffffff).

  • Checkout button text

Used to define text that will appear within the button that prompts your users to purchase a key to any locked content. If left blank, the button will display “Purchase this”.

  • Checkout button type

If enabled, the Checkout button will output a preset or user defined image (via the Upload checkout background image field). For best results, the image should not exceed 300px in height. The width of any uploaded image will be either the width of the uploaded image or the width of the content block within which it is placed, whichever is smaller.

You can select an image from your media library or upload a new one, which is then added to your media library.

  • Call to action text

Defines the string displayed above the Checkout button in the image block. Uses the same color as the Checkout button text color by default. Can be changed via hooks.

  • Checkout button background color

Defines the background color of the Checkout button in hex, RGB or HSL formats. By default, the color is black (#000000).

  • Login button text color

Defines the background color of the login button in hex, RGB or HSL formats. By default, the color is white (#ffffff).

Network Settings

This tab is used to register new Ethereum networks. When the plugin is first activated, the following Ethereum networks are added by default:

  • Mainnet

  • Ropsten

  • Rinkeby

  • Kovan

  • xDAI

  • Polygon

  • Arbitrum

  • Binance

Figure: Network settings

You can add more networks by providing a name, ID and RPC endpoint. The name and ID are arbitrary; however, the ID has to be unique.

Unlock Protocol Gutenberg Block

On activation, the plugin will make a new Unlock Protocol block available that can be used via WordPress’ Gutenberg editor. This block acts as a “container” block for any content you want to put behind a lock. This means that by itself, it adds no content or markup on the page.

The Unlock Protocol block pulls double duty, depending on your users’ login status:

  1. If NOT logged in, the block will obscure any content within the Unlock Protocol container block, instead prompting your users to log in to your website using either their WordPress credentials or via a one click login button linked to their Ethereum wallet.

  2. If logged in, the block will obscure any content within the Unlock Protocol container block, instead prompting your users to purchase a key to the lock that you have placed on the content.

Configuring an Unlock Block

The Unlock Protocol block can be added like any other Gutenberg block to any post or page. See WordPress documentation for instructions.

The block can be configured with multiple locks. For each lock, there are 2 settings that you will need to set:

  • Ethereum Network

Select the Ethereum network where you have deployed your lock from this dropdown. If the network is not displayed, it needs to first be registered from the Network settings.

  • Lock Address

Add your lock address into this field. Only Ethereum addresses are accepted, validated via the following regex: /^0x[a-fA-F0-9]{40}$/

Note: If an Unlock Protocol block is added to a post or page and left unconfigured, it will throw an error and block the page from being published or updated.

To avoid accidental access issues, Unlock Protocol blocks cannot be nested; ie., placing one block within another has been restricted. However, a workaround to this is to register an Unlock Protocol block as a reusable block and add that into another block, effectively nesting them. This cannot be patched due to a limitation with how WordPress handles reusable blocks.

Multiple Unlock Protocol blocks (with the same or different locks) on a page or post are permissible and work as expected.

Full Page Locked Content

The Unlock Protocol block can contain all the content on any page post, or any subset. The title and footer components of a page cannot be locked.

If all the content on any page or post is locked, archives containing that page or post will only display the excerpt content. If no excerpt is set, the archive page will only display the other metadata associated with the post.

What exactly is output will depend on the theme in use, but it will usually include the title, published data and taxonomy data of the post. The content on the archive page will be empty as in the screenshot below.

Figure: Archive pages display only excerpt content when all other content on a post is locked.

Additional formatting via CSS

You may wish to apply additional formatting via CSS. The Login and Checkout buttons can be targeted by the .login-button-container and .checkout-button-container classes respectively.

For example, to change the alignment and center the buttons, add the following snippet to the Customizer > Additional CSS

.login-button-container { 
    text-align: center; 
}

.checkout-button-container {
    text-align: center;
}

Here's a screencast to show this process:

https://drive.google.com/file/d/1sG4IyZXhvMZ-vMhlEbcLvNo3MsM43wS0/view?usp=sharing

Hooks

Hooks are the WordPress way of providing you with extensibility to build on top of the plugin. The plugin has several hooks built into its codebase that can be used to interact or modify its output at specific points in the runtime. Each of them are specified below.

Actions

Actions allow you to add extra functionality at specific points. The actions should be added in the functions.php file or somewhere callable.

do_action( 'unlock_protocol_user_created', $user_id, $user );

Fires when a user is created by the plugin.

Parameters:

$user_id

(int) ID of the user.

$user

(Object) User data fields.

Source: inc/classes/class-login.php

do_action( 'unlock_protocol_network_deleted', $removed_network, $new_updated_networks );

Fires when a network is deleted.

Parameters:

**** $removed_network

(array) Contains the network ID, name and RPC endpoints.

$new_updated_networks

(array) Multidimensional array of existing networks.

Source: inc/classes/rest-api/class-settings.php

do_action( 'unlock_protocol_network_updated', $new_updated_networks );

Fires when a network is added.

Parameters:

**** $new_updated_networks

(array) Multidimensional array of existing networks.

Source: inc/classes/rest-api/class-settings.php

do_action( 'unlock_before_checkout_button' );

Used to add content before the Checkout button.

Source: templates/login/checkout-button.php

do_action( 'unlock_after_checkout_button' );

Used to add content after the Checkout button.

Source: templates/login/checkout-button.php

do_action( 'unlock_before_login_button' );

Used to add content before the Login button.

Source: templates/login/button.php

do_action( 'unlock_after_login_button' );

Used to add content after the Login button.

Source: templates/login/button.php

Filters

Filters are functions that are used to pass data through. Using filters, you can modify the content returned from WordPress. Filters should be added in the functions.php file or somewhere callable.

apply_filters( 'unlock_protocol_user_validate_params', $data );

Used to change the parameters of user validation.

Parameters:

**** $data:

(array): array of user params.

Source: inc/classes/blocks/class-unlock-box-block.php

apply_filters( 'unlock_protocol_validate_auth_code_params', $data );

Used to add or change the parameter while authentication of code validation.

Parameters:

**** $data:

(array): array of authentication code parms.

Source: inc/classes/class-unlock.php

apply_filters( 'unlock_protocol_paywall_config', $data );

Used to modify the network ID or lock address.

Parameters:

$data:

(array): Paywall configuration.

Source: inc/classes/class-unlock.php

apply_filters( 'unlock_protocol_get_client_id', $host );

Used to modify the client for login URL or email address.

Parameters:

$host:

(String): Domain name.

Source: inc/classes/class-unlock.php

apply_filters( 'unlock_protocol_get_redirect_uri', $url );

Used to modify the URL rendered after OAuth validation.

Parameters:

$url:

(String): Redirect URL.

Source: inc/classes/class-unlock.php

apply_filters( 'unlock_protocol_get_login_url', $url);

Used to modify the login URL.

Parameters:

$url:

(String): Unlock Protocol login OAuth URL.

Source: inc/classes/class-unlock.php

apply_filters( 'unlock_protocol_register_user', $ethereum_address);

Used when a new user needs to be registered.

Parameters:

**** $ethereum_address:

(String): Ethereum address of the user.

Source: inc/classes/class-login.php

PreviousCollab.LandNextDrupal Plugin

Last updated