Skip to content
This repository has been archived by the owner on Apr 16, 2023. It is now read-only.

Home

Jump to bottom
Aldo Latino edited this page Mar 5, 2022 · 36 revisions

Private Content

Private Content is a plugin for WordPress that displays a portion of a post/page content only to users of a specific role or to a single or multiple users.

The action is performed using a shortcode, for example:

[private role="administrator"]Text for administrators[/private]

A note.

The text of this Wiki is available also in PDF. You can download it from here: https://github.com/aldolat/private-content.latex/blob/master/private-content.pdf.

Table of contents

Description

This plugin provides a shortcode to display a portion of a post or page content only to users of a specific role. For example, you can show the hidden text to Editors or to Authors or to any other WordPress role.

Please, note that an Administrator can read an Editor private content or a Subscriber private content, and so on. Same thing for Editor, Author, Contributor, and Subscriber: a higher role can read a lower role content (in almost all cases, see below), according to the following WordPress roles schema in descending order:

  • Administrator
  • Editor
  • Author
  • Contributor
  • Subscriber

Also you can show the hidden text only to a certain role. For example, you can mark a text as visible only to Contributors and hide it to higher roles, such as Administrators or Editors and so on.

As of version 3.0 you can mark a text as visible only to a certain user, using his login name.

As of version 4.0 you can mark a text as visible to multiple users, using their login names comma separated.

As of version 4.3 you can use either the usual private shortcode or the extra ubn_private, in case the first is already in use.

As of version 5.0 you can use the new option reverse to change the logic of the recipient option. If reverse is activated, it will not allow users in recipient read the private note.

As of version 6.0 you can use custom roles.

As of version 6.1 you can use multiple custom roles. Also Administrators can always read text for custom roles, unless a role="custom-only" option has been used.

As of version 6.2 you can use custom IDs and/or classes for the HTML container.

As of version 6.4 you can use the post-author and post-author-only cases for the role option.

The shortcode command

The shortcode is private:

[private {options}]Text[/private]

There is another shortcode available ubn_private, that can be used in case private is already taken by another plugin:

[ubn_private {options}]Text[/ubn_private]

The shortcode options

Available options for the shortcode

These are the available options for the shortcode, that will be explained in the next sections of this page:

  • role
  • custom_role
  • recipient
  • reverse
  • align
  • alt
  • container
  • id
  • class

[role] Display a text portion to a certain role

Accepted arguments:

  • administrator
  • editor
  • editor-only
  • author
  • author-only
  • contributor
  • contributor-only
  • subscriber
  • subscriber-only
  • visitor or visitor-only (they are equivalent)
  • none
  • custom
  • custom-only
  • post-author
  • post-author-only
  • post-author-custom

Let's see in detail.

Role Result
administrator The hidden text is shown to Administrators.
editor The hidden text is shown to Editors and Administrators.
editor-only The hidden text is shown to Editors only.
author The hidden text is shown to Authors, Editors, and Administrators.
author-only The hidden text is shown to Authors only.
contributor The hidden text is shown to Contributors, Authors, Editors, and Administrators.
contributor-only The hidden text is shown to Contributors only.
subscriber The hidden text is shown to Subscribers, Contributors, Authors, Editors, and Administrators.
subscriber-only The hidden text is shown to Subscribers only.
visitor / visitor-only The hidden text is shown only to non-logged-in users. Administrators can read the hidden text.
none When used, it is mandatory to use also the recipient option. The hidden text is shown only to users in the recipient list. Administrators cannot read the hidden text.
custom When used, it is mandatory to use also the custom_role option. The hidden text is shown only to users that have a role in the custom_role list. Administrators can read the hidden text.
custom-only When used, it is mandatory to use also the custom_role option. The hidden text is shown only to users that have a role in the custom_role list. Administrators cannot read the hidden text.
post-author The hidden text is shown to the author of the post. Administrators can read the hidden text.
post-author-only The hidden text is shown to the author of the post only. Administrators cannot read the hidden text.
post-author-custom When used, it is mandatory to use also the custom_role option. The hidden text is shown publicly when the author of the post has a role in the custom_role list. Administrators cannot read the hidden text.

Here is an image of the cases for the role option:

role-options

Examples

Display this text to Administrators:

[private role="administrator"]Text for Administrators[/private]

Display this text to Administrators and Editors:

[private role="editor"]Text for Editors[/private]

Display this text to Administrators, Editors, and Authors:

[private role="author"]Text for Authors[/private]

Display this text to Administrators, Editors, Authors, and Contributors:

[private role="contributor"]Text for Contributor[/private]

Display this text to Administrators, Editors, Authors, Contributors, and Subscribers:

[private role="subscriber"]Text for Subscribers[/private]

Display this text to the author of the current post:

[private role="post-author"]Text for author of the post[/private]

Display this text to everyone when the author of the post has the Marketing role:

[private role="post-author-custom" custom_role="marketing"]Text for everyone.[/private]

Text only for specific roles excluding other roles

If you want to show a note only to a certain role, you have to use a {role}-only option. In this way, for example, an Administrator or an Editor (roles higher than Author) cannot read a note for Authors only.

These are all the cases:

Display this text to Editors only:

[private role="editor-only"]Text for Editors only[/private]

Display this text to Authors only:

[private role="author-only"]Text for Authors only[/private]

Display this text to Contributors only:

[private role="contributor-only"]Text for Contributors only[/private]

Display this text to Subscribers only:

[private role="subscriber-only"]Text for Subscribers only[/private]

Display this text to Visitors only:

[private role="visitor-only"]Text for Visitors only[/private]

or the equivalent shortcode:

[private role="visitor"]Text for Visitors only[/private]

Display this text to the author of the current post only:

[private role="post-author-only"]Text for author of the post only[/private]

Display this text to Designers only (Designers is a custom role created by the user):

[private role="custom-only" custom_role="designers"]Text for Designers only[/private]

Publicly display a hidden text when the post author has a certain role

This is a special case: the hidden text is publicly shown when the author of the post has a certain role. In this case the logic of the behavior is inverted: here the plugin doesn't see the role of who is reading, but the role of the post author. If the author of the post belongs to a certain role, then the hidden text is shown to the public. Obviously the alt option is available.

For example:

[private role="post-author-custom" custom_role="administrator" alt="The author of this post is NOT an administrator, so you can read the alternate text only."]Hidden text.[/private]

With this shortcode, if the post author is an administrator, the hidden text will be shown to the public, otherwise the alternate text will be displayed. If the alt option is not used, nothing will be displayed. See the example below:

[private role="post-author-custom" custom_role="marketing"]Hidden text.[/private]

In this case, if the post author has the marketing role, then the hidden text will be displayed. If the post author doesn't have the marketing role, nothing will be displayed.

[recipient] Text only for a specific user or multiple users

Accepted arguments:

  • login name of the target user. You can use multiple login names, comma separated.

In the case you want to show a text only to a specific user, assign none to role and a login name to recipient:

[private role="none" recipient="login-name"]Text for a specific user only[/private]

Change login-name with the correct login name of the target user.

You can use a comma separated list of usernames to target certain users:

[private role="none" recipient="login-name1, login-name2, login-name3"]Text for specific users only[/private]

Change login-name1, login-name2, and login-name3 with the correct login names of the target users.

[custom_role] Display a text portion to a custom role or multiple roles

Accepted arguments:

  • the custom role
  • the custom roles, comma separated
Single custom role

If you want to show a text only to users of a custom role, use the option custom_role.

For example:

[private role="custom" custom_role="designers"]Text for Designers group.[/private]

Please, note that texts for custom roles can be read also by Administrators. To avoid this, use the role="custom-only" option, followed by the name of the custom role.

For example:

[private role="custom-only" custom_role="designers"]Text for Designers only[/private]

The option role=custom can be used also for the WordPress standard roles, for example:

[private role="custom" custom_role="author"]Text for role Author.[/private]

In this case, Authors will read the private text, but higher roles (such as Editors) will not read it. It is like using a role-only option. Anyway, Administrators will read it. For more information, see the paragraph below.

Multiple custom roles

If you want to show a text to multiple roles, you can enter them separated by a comma. For example:

[private role="custom" custom_role="designers,engineers"]Text for Designers and Engineers groups.[/private]

You can mix custom roles and standard WordPress roles, with a caveat.

For example:

[private role="custom" custom_role="designers,engineers,author"]Text for Designers, Engineers, and Authors group.[/private]

As you can see, Designers and Engineers are custom roles, while Author is a standard WordPress role. In the above example, Administrator will read the private text. Even in this case, as wrote before, you can use the role="custom-only" option to avoid Administrators can read the private text:

[private role="custom-only" custom_role="designers,engineers,author"]Text for Designers, Engineers, and Authors group.[/private]

A note about using standard WordPress roles with role=custom option.

If you use a standard WordPress role with the custom_role option, you expect that a higher role can read the private text for lowers roles, i.e. a text for Author role should be read by Editor role (which is a role higher that Author). Actually, Editor role won't read that text. This is normal, because the option role="custom" follows a path different than standard WordPress role management. It's like you'd use a role-only option, in our example a role="author-only" option. For example, this shortcode:

[private role="custom" custom_role="designers,engineers,author"]Text for Designers, Engineers, and Authors group.[/private]

will be read by Designers, Engineers, Authors, and Administrators, but not by Editors (even if Editors is a higher role that Author).

[reverse] Reverse the logic of hiding text

Accepted arguments:

  • 1 - Activate the reverse option

The option reverse=1 is used when you want to hide a private text to some users or to some custom roles. Since it would be uncomfortable to add a lot of users/group in the shortcode, it is more convenient to tell the plugin to show the private text to all users/groups and hide it to some.

The reverse option is available only with the following options:

  • single users: role=none, adding also the recipient option and the reverse;
  • custom roles: role=custom, adding also the custom_role option and the reverse.

See here below the two cases.

Use of the "reverse" option for single users

If you want to show a text to all users but not to some, activate the option reverse, so that users added in the recipient option will not read the note.

For example:

[private role="none" recipient="alice,bob,charlie" reverse=1]We all read this message while Alice, Bob, and Charlie can't read it![/private]

This shortcode will show the text to all users, excluding Alice, Bob, and Charlie (which cannot read the text).

Use of the "reverse" option for roles

You can use the reverse option also when using roles. In this case you will not use the recipient option, but simply in this way:

[private role="custom" custom_role="designers" reverse=1]Text for all roles, excluding Designers.[/private]

With this shortcode, all users will read the private message, while Designers will be excluded. If you define an alternate message with alt option, Designers will read the alternate message only.

You can also exclude multiple roles. For example:

[private role="custom" custom_role="designers, engineers, author" reverse=1 alt="You can't read hidden texts because you are part of Designers and/or Engineers and/or Author roles"]Text for all roles, excluding Designers, Engineers, and Author roles.[/private]

Take note that Administrators will read the hidden text, even if the current Administrator has also one or more of the excluded roles. See the next paragraph for more information and also the table above.

The Administrator role

The Administrator role is a special role in this plugin. This role can always read the hidden texts, unless one of these options has been used:

  • a {role}-only option (excluding visitor and visitor-only);
  • a none (with recipient) option;
  • a custom-only option.

For example, let's say that the role Designers has been excluded from reading a hidden text. If an Administrator is reading that page and he has also the Designers role, he will read the hidden text. In the following example, Administrator (which has the Designer role too) can read the hidden text:

[private role="custom" custom_role="designers" reverse=1]Text for all roles, excluding Designers role.[/private]

In the following examples, instead, Administrators cannot read the hidden texts:

[private role="author-only"]Private note for Author.[/private]

[private role="post-author-only"]Private note for the author of the post.[/private]

[private role="none" recipient="john"]Private note for John.[/private]

[private role="custom-only" custom_role="engineers"]Private note for Engineers role.[/private]

[align] Align style

Accepted arguments:

  • left - Left align the paragraph
  • center - Center align the paragraph
  • right - Right align the paragraph
  • justify - Justify the paragraph

[alt] Alternate text for excluded users

If you want to show an alternate text in case the reader can't read, you can use:

[private role="author" alt="You have not rights to read this."]Text for authors only[/private]

Please, take note that the alternate text, if defined, is always publicly displayed.

The alternate text can contain some HTML tags. The list is:

  • b or strong for bold text;
  • em or i for italic text;
  • a for links, with href and title included. For href and title do not use double quote, but single quote.

For example:

[private role="subscriber" alt="<a href='https://www.example.com/subscribe' title='Subscribe now!'>Subscribe</a> to read this <strong>super powered</strong> text!"]Hidden text.[/private]

[container] The HTML container for the text

Starting from version 2.4, the user can choose the HTML container element for the text.

Accepted arguments:

  • p - The default value;
  • div - This element allows you use HTML elements like lists, headings, and more.
  • span - This element allows you to add private content inline.

Usage:

Wrap the note inside a DIV:

[private container="div"]This is the text[/private]

Wrap the note inside a SPAN:

This is my home I bought a year ago [private container="span"](the key is under the doormat)[/private].

[id] Adding custom IDs for the HTML container

The user of the plugin can add custom IDs to the HTML container using the option id=name-of-the-id, for example:

[private id="myid1, custom-id-2, my_id_3"]Private text.[/private]

The single ID names must be separated by a comma, not by a space. Also, if the ID is composed by more words, the words must be separated by a dash or by an underscore, otherwise the words will be considered as separated ID names.

[class] Adding custom classes for the HTML container

The user of the plugin can add custom classes to the HTML container using the option class=name-of-the-class, for example:

[private class="myclass1, custom-class-2, my_class_3"]Private text.[/private]

The single class names must be separated by a comma, not by a space. Also, if the class is composed by more words, the words must be separated by a dash or by an underscore, otherwise the words will be considered as separated class names. Only consider that underscores in login names will be changed into a dash, starting from version 6.4.0.

Giving a style to the text generated by Private Content

The text generated by this plugin uses some CSS classes, listed here:

  • private - Applied to each HTML element generated by this plugin.
  • {role}-content - Applied to the text for a particular role. Here is the complete list:
    • administrator-content
    • editor-content
    • author-content
    • contributor-content
    • subscriber-content
    • visitor-content
    • user-content - When used for specific user(s).
      • user-only - When used for specific user(s). This class is always preceded by user-content class.
      • {user_login}-only - When used for specific user(s). The placeholder {user_login} will be changed into the actual login name. This class is always preceded by user-content and user-only classes.
      • user-only-reverse - When the reverse option is used. This class is always preceded by user-content class.
    • {custom_role}-content - When used for custom roles. The placeholder {custom_role} will be changed into the actual custom role.
  • {role}-only - Applied to the text for a specific role. This class is always preceded by {role}-content class.
  • post-author-custom - Applied to the text when the post-author-custom option is used. This class is always followed by {user_login}-content and {custom_role} class. The placeholders {user_login} and {custom_role} will be changed into the actual login name and custom role respectively.
  • {custom-id-names} - Added when specified by the user.
  • {custom-class-names} - Added when specified by the user.
  • alt-text - Applied to the alternate text.

Capabilities created by Private Content plugin

These are the capabilities created by this plugin:

  • read_ubn_editor_notes
  • read_ubn_author_notes
  • read_ubn_contributor_notes
  • read_ubn_subscriber_notes

These capabilities will be removed when the plugin is uninstalled using the usual uninstallation command in the WordPress Dashboard.

Available filters

  • ubn_private_align_style - Filters the style string. An example of a string is:
$align_style = ' style="text-align: justify;"';

Please note the leading space before style=.

  • ubn_private_containers - Filters the array containing the HTML container for the private and alternate text.

An example is:

$containers = array(
  'open'  => '<p',
  'close' => '</p>',
);

Notice that the first element of the array must not have the closing >.

  • ubn_private_content - Filters the private content.
  • ubn_private_alt - Filters the alternate content.
  • ubn_private_text - Filters the entire private and alternate text, just before the output. The string contains also the HTML container.
  • ubn_private_text_empty - Filters the text if it is empty, just before the output.
  • ubn_private_class_selector - Filters the HTML output for the classes.
  • ubn_private_id_selector - Filters the HTML output for the IDs.

Testing the shortcode

It could be useful to test if the shortcode is working as intended. To do this, you can use a plugin that lets you temporarily switch between accounts. The plugin is User Switching.

Clone this wiki locally