4.15 User Subscriptions

Subscribers can be given extra features, such as the ability to turn ads off, or permission to read private sections, or even just a token such as an icon next to their name on comments. You can also give permission to use an ``expensive'' (that is, computationally expensive and generally slow) Scoop box in their sidebar, such as the ``Who's online?'' box, available on the Scoop Box Exchange.

You will almost certainly want to have payment processing (4.22) set up to handle payment for those subscriptions.

4.15.1 Setting up Subscriptions

The first step in setting up subscriptions is to create a new user group for the subscribers and giving it the appropriate permissions. Basing it on the Users group then adding permissions is probably a good idea, as nobody will be pleased about losing permissions due to subscribing.

If you will have several levels of subscriptions, you will need to create one user group per subscription level, with the appropriate permissions for each. It's probably a good idea to make each subscription level include the permissions for all levels below, but nothing requires it. Again, nobody will be pleased about losing permissions due to upgrading a subscription.

The second step is to create the subscription type, using the Subscriptions Admin Tool (A.17). You can specify the price per month, the user group (which you created in step 1) a subscriber is moved to, and so on. Save the subscription type once all the boxes are filled in the way you want.

Third, the users must have permission to subscribe; this is set using the allow_subscription perm. This may not be all groups, especially if you have a restricted group for abusive users. See 4.15.3 for such considerations.

If you want Scoop to move people to the subscriber group(s) automatically (this only makes sense if you have payment processing (4.22) set up), you should give the permission sub_allow_group_change to the groups for which you want to allow automated subscriptions. Groups which do not have this permission trigger an email to the site administrator requesting a manual group change to the subscriber group.

Finally, you can activate the subscription system by turning the variable use_subscriptions on in the Site Controls Admin Tool (A.6).

4.15.2 Giving Special Privileges

You can give subscribers special permissions (such as the use of the spellchecker) which the regular users don't have simply by selecting the appropriate perms in the Groups Admin Tool (A.12).

You can also give them access to certain boxes, allowing you to effectively give subscribers access to any feature Scoop could ever have added through the box system. (See sections B and 5 for details on adding features using boxes.)

If you want to give access to a sidebar box, such as the database-intensive ``Who's Online?'' box, only to subscribers, you first create a perm for that box. Add the perm to the variable perms in the Site Controls Admin Tool, in the Security category. Then, in the Groups Admin Tool, load the desired subscriber group, select the new perm, and save. The subscriber group now has permission to do whatever that perm allows.

The perm must then be checked in the relevant box, or it's rather pointless. In the Boxes Admin Tool, load the box with the feature you are giving to subscribers. At the beginning of the box, add the line:

return '' unless( $S->have_perm("new_perm_name") );

and replace new_perm_name with the name of the perm you just created.

This will cause the box to exit immediately (returning an empty string as its final output) unless the user is in a group with the permission named. Boxes that produce no output disappear without a trace, and a user will never know that it is there until they subscribe.

Once the box has been created and tested, place it on the page template where appropriate (such as in the sidebar in the block index_template). Subscribers will then see the box where you placed it; non-subscribers will not be aware of its presence or absence.

You can create a general permission that says that the user is a subscriber, but if you want to have levels of subscriptions, or if you may someday change which box features are avail to which subscriber group, having an appropriately named perm for each would be easier to manage, as you can just check and uncheck the permissions for the different groups, instead of having to edit the boxes.

4.15.3 Some Security Considerations

When giving out extra permissions to subscribers, pay close attention to the descriptions in the Groups Admin Tool documentation (A.12) as some permissions should only be given to trusted users, not just anybody who pays for a subscription.

If you have a restricted group, such as a ratings-prohibited or commenting-prohibited group, created for rating or commenting abuse, they should not have the perm allow_subscription or they will be able to leave their restricted group simply by purchasing the minimum subscription.