Follow these simple steps to set up the plugin and begin to automate your patron list management.

Initial setup

After installing the plugin, you should first set up the components. You have two to choose from — a "Patron List" and a "Tier List". While both have the same data available (you can access all patrons from the tier list, and vice versa), their format is slightly different, allowing for two different ways to display the patron list. The first is a simple alphabetical list (you can also sort by the patron's pledge), and the second is a list of all tiers, with nested lists for all patrons that are on that tier. Both components give you plentiful sorting options.

Go to the CMS tab and open up the page where you'd like to display the list of patrons. Drag and drop the component onto the markup section to have it render there. If you prefer to keep it simple and use the pre-defined displaying options, the components will render like such:

The Patron List

Patrons
======

- Patron A (Tier A)
- Patron B
- Patron C (Tier A)

The Tier List

Patrons
======

* Tier name
  This is an optional description that you can edit on your tiers
  - Patron A
  - Patron B
* Tier B name

If you would like to customize the appearance, simply remove the component twig tag, so that it does not render. You then have the list of patrons or tiers available in your twig expressions via componentIdentifier.tiers for the tier list and componentIdentifier.patrons for the patron list. By default it's patreonList.patrons and patreonTiers.tiers.

Both variables are arrays that you can iterate over using a for-loop. Have a look at the default.htm of the tier component to see how it's done. The patron component begins at the nested for-loop that accesses the patrons-array of each tier.

Configuring the Components

Both components give you a set of powerful filters that you can make use of to display only those patrons that you would like to display. Both components give you three shared options:

• Only active patrons: If this is checked (default), the plugin will filter out those records where the patron_status is set to false (hence, in the CSV file their status was not "Active patron").
• Sort by: Determines the field how the patrons are sorted (not the tiers!). You can choose between "Current pledge" (default), the database ID, the name, the overall lifetime pledge or the age of the patron (since when she or he started pledging).
• Sort order: Determines whether the patrons are sorted ascending or descending.

The tier list has an additional switch that allows you to exclude empty tiers, which is good in case you don't want to display/advertise empty tiers.

If you need additional fine-grained sorting and filtering, the best way is to make use of if-statements (for instance, to filter by tier name, you could use {% if tier.name === 'My tier name' %}). This will be especially helpful if you want some higher-order tiers to render different from the lower tiers (e.g. the upper tiers as cards, the lower tiers as simple lists).

Please note that the plugin will by default spit out all database fields, that is name, description and a list of patrons for tiers, and name, email, twitter, patron_status, follows_you, current_pledge, lifetime_pledge, tier, patron_since, max_amount, last_charge, and charge_status for the patrons. You can use whatever you need, but remember that this constitutes a potential privacy breach, if you display emails without asking for the patron's consent! Please always remember to only display name and tier for the patrons, and never other fields (which nevertheless can be used for sorting).

Adding your Patrons

There are in principle two ways to add patrons to the page. You can either create patrons manually on the main tab of the plugin in the backend, but the easier and recommended way is to upload a CSV file that you can retrieve from Patreon. To download a CSV file, go to your Patreon account, open the relationship manager, and then simply pull a CSV file with all your patrons. You can of course perform initial filtering and only download a list of those patrons you know will end up in the list, but the plugin automatically updates all patrons, thereby updating the patron status of old patrons so that they will be automatically hidden.

Once you have the CSV file on your computer, click "Import patrons" and upload the CSV-file. OctoberCMS will automatically provide you a list of all fields that are available in the CSV file on the left side, and to the right, you will find all fields that are in the database. The field names have been matched to what the Patreon CSV looks like right now, so hitting "Auto match columns" should already match all fields of the database to the CSV fields. Do not worry about ID and the three dates — they are used internally and do not need to be filled right now!

If the system cannot match all fields immediately, you can fix this by dragging and dropping the database fields onto the file columns. You also have the option to "customize" format, but it should already match the CSV file produced by Patreon.

When you're done, click "Import Patron List" and the importer will do its work. After it's done it will output some helpful information:

• The number of newly created patrons, the number of updated patrons, and skipped patrons/errors.
• In some cases warnings may be produced.

After recognizing the info, click Ok and you'll be redirected to the Patron list.

After your first import

Behind the scenes the importer has done something else that it did not tell you: As most patrons will be on one of the tiers you offer, the plugin will search for each tier it encounters in the database, to match the patron with his or her respective tier in the database. But if the tier is not found, the importer will automatically create the tier for you. Have a look at the tier page to see how it has done. Importantly, check the information, especially the associated pledge amount. The importer will infer the pledge amount from the first patron it encounters on that tier, which in most cases is right, but it may differ. In this case, you can correct that here.

Also, in case you plan to display the tier information on some page, it is a good idea to add a tier description. This could either be the tier description from Patreon, or something different. You can use the description, but do not have to!

Subsequent Imports

Each month, when the list of patrons is updated after the pledges have been processed, download the new CSV file. Make sure to download using the same filters to only create new patrons, and not old patrons that have re-started their pledge. Simply import that file, and the importer will try to find existing patrons by the User ID-field (that is, the user ID that Patreon has assigned these patrons), and then update the record in the database, instead of creating a new one. This has two benefits: First, it is able to reflect changes in pledges, if the patrons switch tiers. And secondly, old patrons that have stopped their pledge will receive an updated patron status. The records are kept in the database, but depending on your component configuration, they will no longer show up on your supporters' listing. You still might want to double-check that everything went according to plan.

Anonymizing patrons and extra data

Two important things should be mentioned as well. First, some patrons prefer to stay anonymous. In that case, they most likely will contact you via Patreon and inform you of their wish. To follow this wish, you have the ability to hide certain users. The "hidden" status is initially set to false, and can be activated for single patrons. The status will be retained during updating of the records, because the field is not mapped onto a field in the CSV file.

Secondly, the plugin provides you with two extra fields for arbitrary data. This could be anything -- a link to a website, a link to a picture of your patrons, or rather anything. The first field is implemented as a text field, but if you really need more space, the second field is implemented as a textarea, giving you more options to put content in there. Both fields are available on the frontend using the attributes extra1 and extra2. You can, for instance, manually drop the first extra field onto the "Additional Info"-column from the Patreon CSV, in case your patrons use that for some extra perks!