Permissions

Permissions Version 4.3.0

CartThrob Permissions enables your CartThrob powered site to sell and edit content access permissions. You can use permissions to limit access to content to only those that have purchased access to it.

CartThrob Permissions is an addon for CartThrob. Like other CartThrob addons, it must be uploaded and installed on your website, and CartThrob must be active for it to run. To use this addon, you will need to create permissions in the administrative interface, and add additional template tags to display these permissions. To sell permissions to customers, you must also adjust your template tags to include permissions when items are added to the cart. You can either manually assign permissions to items being added to the cart, or you can assign permissions to items using the CartThrob Permissions field types.

Though you can use this module to create permission items, you can still create dynamic permissions by adding them manually as a parameter of the add_to_cart_form. If you create them through the admin interface though, they'll be easier to identify later, as you are able to set names & descriptions for each permission through the admin interface.

Features

  • Create & edit permission items
  • Review & edit existing customer permissions, and apply new permissions to members
  • Fieldtype for assigning configured permissions directly to entry ids.

Some permissions functionality is built into CartThrob, including the ability to block access to content (using has_permission tag) & to view existing customer permissions (using permissions tag). This addon specifically adds the ability to view and administer existing customer permissions in an administrative interface, as well as the ability to create permission items and display them in templates, and in channel entries using the permissions fieldtype. Essentially this makes administration of permissions much easier than is possible in CartThrob out of the box.

Requirements

  • ExpressionEngine 6.2+
  • CartThrob 6.3+
  • PHP 7.4+

Installation

  • Upload the /system/user/addons/cartthrob_permissions/ folder to /system/user/addons/
  • Make sure Extensions are enabled on your system
  • Install the CartThrob Permissions module and extension (through EE's add-ons/modules panel)

Upgrading

  • Upload the /system/user/addons/cartthrob_permissions/ folder to /system/user/addons/ Overwriting existing files.
  • Go to EE settings » addons » and click "Run Module Updates"

Setting up the FieldType

Note the FieldType is deprecated and planned for removal in 5.0

  • Install the CartThrob Permissions FieldType through (through EE's addons/fieldtypes panel)
  • Go to the admin » channel administration » channel fields settings
  • Choose your product channel fields group (you may add this FieldType to multiple channel field groups) and add this field type to this field group.

Once the FieldType is installed, and set up in a channel field group, the related channel will now have the option of applying permissions for each individual entry in that channel. When set, you can use these permissions to sell access and block access.

To create new permissions, you must use the CartThrob Permissions admin module. Once you create permissions in the admin module, they will show up as selectable permissions in this FieldType.

There are two ways to use this field type,

  1. as a variable pair: follow the same syntax used in the permission_items tag.

In this example, the field name is "permissions"

{permissions}
    {id}
    {status}
    {description}
    {access_overview}
{/permissions}
  1. as a single variable

 

{permissions} (this will output the permission IDs: something like 1|3|4|11|22)

You can add one or more permissions to items added to the cart. The IDs need to be separated by a pipe | character. When used as a single tag, the permissions are output in this format.

Settings

For the most part the settings are fairly self explanatory. To create permission items, and assign permission items to customers, go to the CartThrob Permissions admin module. Once in the module, you can view, edit and create permissions. All permissions created here will be viewable. Any permission set for any customer whether set manually in this module, or added to their account during purchase/checkout will also be listed.

Tags

permissions

Outputs data about existing user permissions

*NOTE* The permissions tag is always available when using CartThrob, not only when this module is installed.
Parameters
id

Vault id (not subscription id)

id="123"
sub_id

Subscription id associated with permission (if any)

sub_id="123"
member_id

Member id of the person that made the subscription purchase

member_id="123"
order_id

Order ID associated with the permission (if any)

order_id="123"
item_id

Item ID associated with the permission (if any)

item_id="123"
limit

Number of results to return

limit="10"
Variables

id

The unique id of the vault in the CartThrob system

permission

The permission ID

member_id

ID of the member that authorized this vault

sub_id

subscription id (it item is not a subscription this will be blank)

item_id

item id associated with this permission

order_id

Order that initially spawned the subscription

Example
{exp:cartthrob:permissions limit="10" member_id="{member_id}"}
    {id}
    {member_id}
    {sub_id}
    {item_id}
    {order_id}
{/exp:cartthrob:permissions}

has_permission

Used to protect data from users that don't have the proper permissions.

*NOTE* The has_permission tag is always available when using CartThrob, not only when this module is installed.
Parameters
permissions
permissions="123"
member_id

Member id of the customer who's access you need to check

member_id="123"
sub_id

Subscription ID you need to check. When used, if the subscription is not "open" content will be blocked from display. This allows you to hide content that should not be shown if the related subscription is expired or pending. 

sub_id="123"
Conditionals

{if no_results}

Outputs alternate content if the user doesn't have permissions to access the content

Example
{exp:cartthrob:has_permission permissions="123" member_id="{member_id}"}
    Some content!

    {if no_results}
        You don't have access to this
    {/if}
{/exp:cartthrob:has_permission}

permission_items

Outputs data about configured permission items

Parameters
id

Permission item id. You can set this to get information about a single permission item.

id="123"
status

Status of the permission items.

status="open" available values are open|closed
Variables

id

The permission item ID

title

The name / title of the permission item

status

The current status of the permission item. Values are open or closed

description

A simple description of the permission item.

access_overview

A more detailed description of what this permission item provides for the purchaser

Example
{exp:cartthrob:permission_items limit="10" member_id="{member_id}"}
    {id}
    {status}
    {title}
    {description}
    {access_overview}
{/exp:cartthrob:permission_items}

Adding permissions to the cart

To sell a permission, you just have to add it to the cart when selling an item. You can sell dynamic items with permissions, or you can sell products with permissions attached. Either way, it simply involves using the permissions parameter.

*NOTE* You can add one or more permissions to items added to the cart. The IDs need to be separated by a pipe `|` character. For example: `permissions="1|5|11|22"`
Example

In this example, we're assuming that this channel has the Permissions Fieldtype set, and is in use. In this example the fieldtype is called "permissions"

{exp:channel:entries channel="products"  limit=""  dynamic="no" show_future_entries="yes" }
    {exp:cartthrob:add_to_cart_form 
        return=""
        permissions= "{permissions}"
        entry_id="{entry_id}"
        }

    <input type="submit" value="Add to Cart" />

    {/exp:cartthrob:add_to_cart_form}

{/exp:channel:entries}

You can also dynamically create products to sell based on permissions. In this example we're outputting permission items, and selling them as dynamic products

{exp:cartthrob:permission_items status="open"}
    {exp:cartthrob:add_to_cart_form 
        return=""
        on_the_fly="yes"
        title="{title}"
        permissions="{id}"
        price="10"
        entry_id="{entry_id}"
        }

        Permission: {title}<br>
        Description: {description}<br>
        What does it get you: {access_overview}<br>

    <input type="submit" value="Add this permission to Cart" />

    {/exp:cartthrob:add_to_cart_form}
{/exp:cartthrob:permission_items}

Changelog

Version 2.5

Released January 23, 2014

Major fixes & enhancements to backend administration and integration with Subscriptions

  • ADDED: ability to set a permission on a subs plan
  • ADDED: bettor error reporting in subs manager to make it more obvious when something has failed.
  • ADDED: members with vaults method to vault model
  • ADDED: method to permissions model to get permissions related to a specific sub_id
  • ADDED: method to permissions tag where you can pass a sub_id to check for active permissions. If the sub_id is closed, the permissions will not be assigned
  • ADDED: method to update / close permissions if the related subscription is expired.
  • FIXED: issue in permissions backend where permissions couldn't be assigned manually. Form would just reload.
  • FIXED: issue where permissions were assigned twice when purchasing subscription products.
  • FIXED: issues in module where permissions were not being serialized and unserialized correctly, causing permissions added to a subscription to either be ignored, or only the first permission set to be used.
  • FIXED: Many small issues and inconsistencies with Permissions
  • FIXED: various fixes perms field types to get around incompatibility with GRID field type

All previous changes are listed in CartThrob's changelog

Buy Now