Merge pull request #27 from getAlby/issue/26

Enable overriding template for unpaid button from theme folder
getAlby · Jun 5, 2023 · e49d57a · e49d57a
2 parents 0bcc230 + 5223e3f
commit e49d57a
Show file tree

Hide file tree

Showing 6 changed files with 313 additions and 240 deletions.
diff --git a/README.md b/README.md
@@ -8,58 +8,58 @@ It allows you to monetize any digital content with instant microtransactions and
 The plugin is the easiest and most flexible plugin to sell your digital content and to receive donations or Value 4 Value payments.
 Using the Bitcoin Lightning Network you can create the best visitor experience with seamless one-click payments.
 
-
 ### Features
 
 #### Paywall to sell content
-Sell any digital content (pay-per-post, pay-per-view, pay-per-download, etc.) with a highly configurable paywall
 
-* [WebLN enabled](https://www.webln.guide/) by default for easy on-click payments
-* Add a paywall to posts and pages to easily charge for any published content
-* Crowdfund option: make the content freely available after a certain amount is received
-* Time-in option: keep the article freely available for a certain time and then enable the paywall after that
-* Time-out option: make the article freely available after a certain time
-* Configure the price in Satoshis, EUR, USD, or GBP (with real-time exchange rate)
-* Configure the paywall with a shortcode (`[lnpaywall]`)
-* Or configure the paywall with a Gutenberg Block
-* Integrate with other tools and plugins like membership tools to control if the paywall should be enabled (see Paywall Hook section)
+Sell any digital content (pay-per-post, pay-per-view, pay-per-download, etc.) with a highly configurable paywall
 
+-   [WebLN enabled](https://www.webln.guide/) by default for easy on-click payments
+-   Add a paywall to posts and pages to easily charge for any published content
+-   Crowdfund option: make the content freely available after a certain amount is received
+-   Time-in option: keep the article freely available for a certain time and then enable the paywall after that
+-   Time-out option: make the article freely available after a certain time
+-   Configure the price in Satoshis, EUR, USD, or GBP (with real-time exchange rate)
+-   Configure the paywall with a shortcode (`[lnpaywall]`)
+-   Or configure the paywall with a Gutenberg Block
+-   Integrate with other tools and plugins like membership tools to control if the paywall should be enabled (see Paywall Hook section)
 
 #### Donation/Value4Value payments
-The plugin comes with various options to receive donations and [Value 4 Value payments](https://blog.getalby.com/the-case-for-value-4-value/).
 
-* Gutenberg block for a donation widget
-* Donation widget for themes
-* Enable Value 4 Value tags for your website and feeds:
-* Enable the [Lightning meta tag](https://github.com/BitcoinAndLightningLayerSpecs/rfc/issues/1) to allow users to send payments (Value 4 Value)
-* Enable the [`podcast:value` tag](https://github.com/Podcastindex-org/podcast-namespace/blob/main/value/value.md) in your RSS feed to receive payments for your podcast
+The plugin comes with various options to receive donations and [Value 4 Value payments](https://blog.getalby.com/the-case-for-value-4-value/).
 
+-   Gutenberg block for a donation widget
+-   Donation widget for themes
+-   Enable Value 4 Value tags for your website and feeds:
+-   Enable the [Lightning meta tag](https://github.com/BitcoinAndLightningLayerSpecs/rfc/issues/1) to allow users to send payments (Value 4 Value)
+-   Enable the [`podcast:value` tag](https://github.com/Podcastindex-org/podcast-namespace/blob/main/value/value.md) in your RSS feed to receive payments for your podcast
 
 ### Lightning Node connections
-Connect to your existing Bitcoin Lightning node or simply create a new [Alby account](https://getalby.com/) to instantly receive Lightning payments.
 
-* [Alby](https://getalby.com/)
-* [LND](https://github.com/lightningnetwork/lnd/)
-* [LNDHub](https://github.com/getalby/lndhub.go) (e.g. BlueWallet)
-* [LNBits](https://lnbits.com/)
-* [BTCPay Server](https://btcpayserver.org/)
-* [Lightning Address](https://lightningaddress.com/)
+Connect to your existing Bitcoin Lightning node or simply create a new [Alby account](https://getalby.com/) to instantly receive Lightning payments.
 
+-   [Alby](https://getalby.com/)
+-   [LND](https://github.com/lightningnetwork/lnd/)
+-   [LNDHub](https://github.com/getalby/lndhub.go) (e.g. BlueWallet)
+-   [LNBits](https://lnbits.com/)
+-   [BTCPay Server](https://btcpayserver.org/)
+-   [Lightning Address](https://lightningaddress.com/)
 
 ### REST-API for full advanced custom usage
-For more advanced, custom Lightning integrations you can use the REST API to create and verify invoices. The API also provides a [LNURL-pay](https://github.com/fiatjaf/lnurl-rfc/blob/luds/06.md) endpoint. See the REST-API section for details.
 
+For more advanced, custom Lightning integrations you can use the REST API to create and verify invoices. The API also provides a [LNURL-pay](https://github.com/fiatjaf/lnurl-rfc/blob/luds/06.md) endpoint. See the REST-API section for details.
 
 ## Requirements
 
-* WordPress 5.6 or higher
-* PHP 7.4 or higher (with [internationalization functions](https://www.php.net/manual/en/book.intl.php)
+-   WordPress 5.6 or higher
+-   PHP 7.4 or higher (with [internationalization functions](https://www.php.net/manual/en/book.intl.php)
 
 ## Demo
 
 Here quick Demo videos showing how to setup and use the plugin:
-+ [Quck Start - setup + paywall setup](https://www.loom.com/share/095b49a87e444442ac7b297f9483dfa7)
-+ [Admin Panel](https://www.loom.com/share/dbe501fe9d91445082a2c5c07a1a8ce8)
+
+-   [Quck Start - setup + paywall setup](https://www.loom.com/share/095b49a87e444442ac7b297f9483dfa7)
+-   [Admin Panel](https://www.loom.com/share/dbe501fe9d91445082a2c5c07a1a8ce8)
 
 ## Installation
 
@@ -74,14 +74,15 @@ git clone https://github.com/getAlby/lightning-publisher-wordpress.git
 cd lightning-publisher-wordpress
 composer install # (maybe you need to add `--ignore-platform-reqs` if it asks you to update PHP)
 ```
+
 To build a .zip file of the WordPress plugin run:
+
 ```bash
 ./build.sh # this builds a `wordpress-lightning-publisher.zip`
 ```
 
 Then upload and activate the plugin through the WordPress Plugin admin panel.
 
-
 ## Paywall Hook to have custom logic when to enable/disable the paywall
 
 To integrate with other plugins or to write custom conditions on when the paywall should be enabled a hook can be used. This means you can use a custom PHP function to decide if content should be behind the paywall or not.
@@ -129,18 +130,63 @@ function wp_bln_has_paid_for_post($show_full_content, $post_id) {
 
 ```
 
+## Overriding template for unpaid button
+
+**Warning**: Do not edit these files within the core plugin itself as they are overwritten during the upgrade process and any customizations will be lost.
+Use variable `$plugin` to access plugin options inside of the template file.
+
+Required markup for custom button:
+
+```HTML
+<div class="wp-lnp-wrapper">
+    <button class="wp-lnp-btn">Custom labeled button</button>
+</div>
+```
+
+##### Option 1
+
+Copy file `wp-content/plugins/lightning-publisher-wordpress/public/templates/paywall-button-unpaid.php` to `wp-content/themes/yourtheme/lightning-publisher-wordpress/paywall-button-unpaid.php`
+
+The copied file will now override the default template file.
+
+##### Option 2
+
+If you would prefer to place template file in a custom location, then you can use filter: `bln_paywall_unpaid_button_template`
+
+1. Copy file `wp-content/plugins/lightning-publisher-wordpress/public/templates/paywall-button-unpaid.php` to custom location, eg `wp-content/themes/yourtheme/plugin-mods/paywall-button-unpaid.php`
+2. Use filter `bln_paywall_unpaid_button_template` to override button template path.
+   You can e.g. in `functions.php`
+
+```php
+
+// your function receives 1 argument:
+// $template_path string, absolute path to template file used to render the button template
+//
+// return HTML template
+function update_bln_paywall_unpaid_button($template_path) {
+    // Absolute path to template file
+    $new_path = get_stylesheet_directory() . '/plugin-mods/paywall-button-unpaid.php';
+
+    return $new_path;
+}
+
+// Check out the `add_filter` documentation for more information: https://developer.wordpress.org/reference/functions/add_filter/
+add_filter( 'bln_paywall_unpaid_button_template', 'update_bln_paywall_unpaid_button' );
+
+```
+
 ## Shortcode
 
 If you do not use the Gutenberg editor you can use the `[lnpaywall]` shortcode. The content after the shortcode will be behind the paywall.
 The following configuration options are possible:
 
-* amount
-* currency
-* description
-* button_text
-* total
-* timeout
-* timein
+-   amount
+-   currency
+-   description
+-   button_text
+-   total
+-   timeout
+-   timein
 
 #### Example
 
@@ -152,23 +198,23 @@ The following configuration options are possible:
 
 Folder structure is based on https://github.com/DevinVinson/WordPress-Plugin-Boilerplate
 
-- `bln-publisher.php` is the entrypoint of the plugin
-- `includes` is where functionality shared between the admin area and the public-facing parts of the site reside
-- `admin` is for all admin-specific functionality
-- `public` is for all public-facing functionality
-- `includes/class-bln-publisher.php` is the main plugin class which handles including all the related classes.
-- `includes/class-bln-publisher-loader.php` is responsible for registering the action and filter hooks, and shortcodes.
+-   `bln-publisher.php` is the entrypoint of the plugin
+-   `includes` is where functionality shared between the admin area and the public-facing parts of the site reside
+-   `admin` is for all admin-specific functionality
+-   `public` is for all public-facing functionality
+-   `includes/class-bln-publisher.php` is the main plugin class which handles including all the related classes.
+-   `includes/class-bln-publisher-loader.php` is responsible for registering the action and filter hooks, and shortcodes.
 
 ## REST API
 
 The plugin also provides a set of REST API Endpoints for handling payments and donations.
 
 #### Initiate Payment for Paywall
 
-- URL: `/lnp-alby/v1/paywall/pay`
-- Method: `POST`
-- Auth Required: No
-- Data example
+-   URL: `/lnp-alby/v1/paywall/pay`
+-   Method: `POST`
+-   Auth Required: No
+-   Data example
 
 ```
 {
@@ -178,10 +224,10 @@ The plugin also provides a set of REST API Endpoints for handling payments and d
 
 #### Verify Payment for Paywall
 
-- URL: `/lnp-alby/v1/paywall/verify`
-- Method: `POST`
-- Auth Required: No
-- Data example
+-   URL: `/lnp-alby/v1/paywall/verify`
+-   Method: `POST`
+-   Auth Required: No
+-   Data example
 
 ```
 {
@@ -193,9 +239,9 @@ The plugin also provides a set of REST API Endpoints for handling payments and d
 
 #### LNURL-pay
 
-- URL: `/lnp-alby/v1/lnurlp`
-- Method: `GET`
-- Auth Required: No
+-   URL: `/lnp-alby/v1/lnurlp`
+-   Method: `GET`
+-   Auth Required: No
 
 ```
 {
@@ -208,16 +254,16 @@ The plugin also provides a set of REST API Endpoints for handling payments and d
 }
 ```
 
-- URL: `/lnp-alby/v1/lnurlp/callback`
-- Method: `GET`
-- Auth Required: No
+-   URL: `/lnp-alby/v1/lnurlp/callback`
+-   Method: `GET`
+-   Auth Required: No
 
 #### Initiate a general payment to generate an invoice
 
-- URL: `/lnp-alby/v1/invoices`
-- Method: `POST`
-- Auth Required: No
-- Data example
+-   URL: `/lnp-alby/v1/invoices`
+-   Method: `POST`
+-   Auth Required: No
+-   Data example
 
 ```
 {
@@ -228,10 +274,10 @@ The plugin also provides a set of REST API Endpoints for handling payments and d
 
 #### Verify Payment for an invoice
 
-- URL: `/lnp-alby/v1/invoices/verify`
-- Method: `POST`
-- Auth Required: No
-- Data example
+-   URL: `/lnp-alby/v1/invoices/verify`
+-   Method: `POST`
+-   Auth Required: No
+-   Data example
 
 ```
 {
@@ -244,7 +290,6 @@ The plugin also provides a set of REST API Endpoints for handling payments and d
 
 Do you need help? Create an issue or reach out to us: support[at]getalby.com
 
-
 ## About Alby
 
 This plugin is powered by [Alby](https://getalby.com/) - We create tools to rethink content monetization on the web.