Differences

This shows you the differences between two versions of the page.

--- paywall_invoker:declarative [2023/11/07 10:09] – [data-paperview-paywall] joaosaraiva
+++ paywall_invoker:declarative [2026/03/27 17:24] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+====== Paywall declarative invocation ======
+The Paperview Paywall can be invoked by declaring regular HTML5 data attributes in HTML DOM elements -- such as ''div''s or ''span''s -- in a manner that we dub "declarative invocation".
+In the declarative invocation, the Paywall javascript -- loaded by a script inserted somewhere in your web page (see [[paywall_invoker:start#loading_the_paywall|"Loading the Paywall"]]) -- will wait until the page finishes loading, and then look at the whole web page and search for Paperview-related data attributes. The Paywall will then be shown to the Reader if any such attributes are found.
+The following is an example of a ''div'' DOM element that, when included in a web page, will lead to displaying the Paywall to the Reader. Note that this snippet, along with the inclusion of the Paywall script somewhere in your page, is the minimum needed for you to show the Paywall for a specific article.
+<code html>
+<div data-paperview-publication="--publication-ID--" data-paperview-article="--article-ID--">
+</div>
+</code>
+Within the HTML element, you can place any content you wish; the content will be replaced with the article's real content if the Reader is entitled to it.
+===== Data attributes =====
+This is a complete list of the data attributes supported by the Paywall script. Note that all attributes are prefixed with ''data-paperview-'', to avoid conflicts with other Javascript libraries that may use data attributes in the same manner.
+==== data-paperview-publication ====
+The Publication ID for the Publication which provides the desired article, bundles, or subscriptions. This attribute is **always mandatory**, except in elements with the [[#data-paperview-reading-token|data-paperview-reading-token]] attribute.
+==== data-paperview-article ====
+The Article ID for the desired article.\\
+If this is provided, the Paywall will show the article acquisition screen, along with the possibility to acquire any bundles in which the article is included. Otherwise, only the Publication's bundles or subscriptions can be acquired.
+==== data-paperview-content ====
+An integer (starting at 1), indicating that the DOM element will contain the specified piece of the article's content. This attribute is mandatory when the element is to display the article's content.
+==== data-paperview-referrer ====
+The ID of the Reader that referred the current Reader to this article (and Paywall).\\
+In most cases, this attribute will not be used, and the referrer will be determined from the current URL instead.
+==== data-paperview-seller ====
+The ID of the Reseller that is "selling" the article, subscription, or bundle. This is only used when selling Publication contents via a Reseller's web site.
+==== data-paperview-reading-token ====
+A [[reading_token_provider:start|reading token]] to allow the Reader to view the article's content without needing to acquire it. Developers can use this attribute to easily perform an integration with their own subscription management mechanism.\\
+This attribute can be used in a DOM element on its own (without needing the [[#data-paperview-publication|data-paperview-publication]] attribute), making it easier for developers to inject the attribute into the web page when the Reader has a valid external subscription to the Publication.
+==== data-paperview-roauth-token ====
+A ROAuth token to automatically login the Reader. This can be used to enable single sign-on (SSO) scenarios.\\
+This attribute can be used in a DOM element on its own (without needing the [[#data-paperview-publication|data-paperview-publication]] attribute), making it easier for developers to inject the attribute into the web page.
+==== data-paperview-paywall ====
+The Paywall workflow to be used. Can be one of ''acquire_article'', ''acquire_bundle'', ''subscribe_publication'', or ''obtain_roauth_token''. If this attribute is not specified and the [[#data-paperview-article|data-paperview-article]] attribute is provided, this will default to ''acquire_article''; otherwise, the default will be ''subscribe_publication''.
+==== data-paperview-except ====
+A comma-separated list of Paywall screens that should be hidden from the Reader. The screens available are ''payment_introduction'', ''article_payment_introduction'', ''acquire_article'', ''acquire_bundle'', and ''subscribe_publication''.
+  * ''payment_introduction'': Shown to the anonymous Reader when no [[#data-paperview-article|article for acquisition]] is provided.
+  * ''article_payment_introduction'': Shown to the anonymous Reader when an [[#data-paperview-article|article for acquisition]] has been provided.
+  * ''acquire_article'': The screen where the Reader can acquire the article.
+  * ''acquire_bundle'': The screen where the Reader can acquire the Publication's bundles (filtered by the provided article, if any).
+  * ''subscribe_publication'': The screen where the Reader can subscribe to the Publication
+An example for a Paywall that should **only** display the article acquisition screen would be: ''acquire_bundle,subscribe_publication''
+==== data-paperview-publisher-transaction-token ====
+A Publisher-specific token that should be associated with any transaction that is performed during this paywall interaction. Can be used by the Publisher to associate purchases (such as subscriptions) with other information that has previously been collected by the Publisher.
+==== data-paperview-trigger ====
+What should trigger the Paywall's appearance. Can be one of ''click'', ''wload'' (window load), or ''autodetect''. Default value is ''autodetect''.
+  * ''click'': the Paywall will only be triggered when the DOM element is clicked.
+  * ''wload'': the Paywall will display as soon as the web page finishes loading.
+  * ''autodetect'': the behaviour will depend on the DOM element
+    * If the element is of type ''a'' (anchor) or ''button'', the behaviour will be that of ''click''.
+    * Otherwise, it will be that of ''wload''.
+==== data-paperview-replace ====
+What part of the declarative HTML DOM element should be replaced by the article content. Can be one of ''element'' or ''content''. Default value is ''content''.
+  * ''element'': the HTML element itself should be replaced (and the element will be unavailable after replacement, of course).
+  * ''content'': the HTML element's content will be replaced, but the element itself will remain in the DOM (and be available after replacement).
+==== data-paperview-go-back-on-close ====
+Whether the Paywall should go back to the previous page if it is manually closed by the Reader. If the trigger is ''click'', the default value will be ''false''. Otherwise, the default will be ''true''.
+==== data-paperview-skip-intro ====
+Whether **anonymous** Readers should **not** view the initial text explaining that they need a Paperview account in order to acquire an article, bundle, or subscription. Authenticated Readers will not view that message.\\
+Any "truthy" value is ''true'', otherwise ''false''. Note that an empty string, or the attribute's absence, means ''false''. Default value is ''false''.
+==== data-paperview-element-set ====
+Indicates the element set to which this DOM element belongs.
+An element set is used to aggregate multiple DOM elements into a single set, regardless of the other data attributes present in the element. This allows a developer to include Paywalls to multiple articles in the same web page, for example.
+If this attribute is not provided, the element belongs to a set identified by the [[#data-paperview-publication|data-paperview-publication]], [[#data-paperview-article|data-paperview-article]], [[#data-paperview-paywall|data-paperview-paywall]], and [[#data-paperview-trigger|data-paperview-trigger]] attributes. This is meant to address most Paywall scenarios, but developers may find this feature useful for more unorthodox scenarios.