Vanilla allows you to configure certain roles so that users can request membership in them through an application form. Community managers then approve or deny the applications from the dashboard.
This feature requires configuration via the API that will require services if you do not have developers on staff. This article will give you the information you need to know so that you can understand what information to give to your CSM to configure role applications.
Why Role Applications?
You might want to configure role applications for several reasons.
- Maybe you have volunteer moderators and you want to have a formal application process to approve them. In this case you can configure your moderator role with a questionnaire to fill out. Be careful when giving moderator access to people you don't know. The default moderator role has some permissions that are not appropriate for untrusted members so you will most likely want to create a new role for this purpose.
- Maybe you have several categories that require privileged access. You can configure a role that gives members access to the category and have them apply for the role.
Configuring Role Applications
To set up a role application you have configure information for each role you want to have applications. This is done via the various /api/v2/role-requests/metas endpoints. There is no user interface for configuring Role Applications. Normally you would only do it once per RoleID and never have to touch it again. There are a lot of configuration options. The customization options are listed below.
- Role: Each role must be configured separately to allow applications. Create the role you want to configure first before enabling applications on it.
- Fields: You can provide custom fields that the user must fill out in order to apply. Each field can have a name, label, description, and type of control (textbox, text area, and checkbox are currently supported). You can also have some basic validation information such as min length, required, type (number, string, boolean). Because each field is accessible via the API we recommend you name each field with the
camelCase version of its label. - Notification: When users are approved to the role they get sent a notification. You can customize the name (subject) and body of the notification by passing them as Attributes to the endpoint.
- Link: We provide a module of links to role applications based on what roles the current user already has. You can customize the name (link text) and description for each link. Note that our default view does not output link descriptions so you would have to do some custom theming to output them. Link properties would passed as Attributes to the role-requests/metas endpoint.
- NotifyDenied: By default we do not send a notification to the applicant when they are denied a role by a moderator. If you wish to notify applicants when their application is rejected set the attribute `notifiyDenied` to `true`.
You only have to provide a role to set up a customization, although we recommend customizing most of the other options in order to provide the easiest user experience possible.
So, for example, if you want to create a Role Application for the Moderator role (RoleID 32) you PUT the following JSON object to /api/v2/role-requests/metas :
PUT https://[your-forum-domain]/api/v2/role-requests/metas
{
"roleID": 32,
"type": "application",
"name": "Apply to be a moderator.",
"body": "Fill in the form below.",
"format": "markdown",
"attributesSchema": {
"type": "object",
"properties": {
"license": {
"type": "string",
"description": "Enter your license code."
},
"referral": {
"type": "string",
"description": "Name a moderator who can vouch for you."
},
"notes": {
"type": "string",
"x-control": "textarea"
}
}
},
"attributes": {
"link": {
"name": "Click here to become a moderator"
},
"notification": {
"name": "Congratulations! You are now a moderator",
"body": "With great power comes great responsibility.",
"format": "html"
},
"notifyDenied": false,
}
}
This PUT will return a JSON representation of the Application Form that will be presented to the user when he/she is applying for the role and the URL to the that Application Form.
To retrieve the URL to the Application Form after the Form was made you can call the API to GET the list of Application Forms you have made.
GET https://[your-forum-domain]/api/v2/role-requests/metas
[
/* ...},*/
{
"roleID": 32,
"type": "application",
"name": "Apply to be a moderator.",
"body": "Fill in the form below.",
"format": "markdown",
"attributesSchema": {
"type": "object",
"properties": {
"license": {
"type": "string",
"description": "Enter your license code."
},
"referral": {
"type": "string",
"description": "Name a moderator who can vouch for you."
},
"notes": {
"type": "string",
"x-control": "textarea"
}
}
},
"attributes": {
"link": {
"name": "Click here to become a moderator"
},
"notification": {
"name": "Congratulations! You are now a moderator",
"body": "With great power comes great responsibility.",
"format": "html"
}
},
"dateInserted": "2020-09-10T17:02:51+00:00",
"insertUserID": 1,
"dateUpdated": "2020-09-10T17:02:59+00:00",
"updateUserID": 1,
"url": "https://[your-forum-domain]/requests/role-applications?role=32"
}
]
Updating Role Applications
If you need to modify an existing role application use the same PUT method, just explicitly set the RoleID to the role application you want to update. The best way to get the exact structure you want is to do a GET request for the role application you want to modify and copy out the JSON object from the response, make your modifications and send it in a PUT request. Make sure you get only the object ({ "RoleID": 31,...}), the GET response returns an array ([{ "RoleID": 31, ...}]), you will get an error if you try to PUT an array.
The Role Application Links Module
Once you've configured Role Applications you will need to link to them somehow. Make sure you add a condition to present the link only to Users who do not already have the intended Role. In Vanilla's Twig rendering library, a User's Roles are not readily available. To do this you test if the current User has permissions to view Discussions in a Category only available to Users with the intended Role. In this Twig example CategoryID '21' is only available for Users with the RoleID 32:
{# If the Current User cannot view Discussions in a Category 21 (that Role 32 can view). #}
{% if not hasPermission("Vanilla.Discussions.View", 21) %}
{# Give them a message and a link to the role request. #}
<div><a href="{{ url("/requests/role-applications?role=32") }}">Apply here</a></div>
{% endif %}
This will link to the page that will render the RoleApplicationLinksModule , or in other words, the Form that Users can fill in to apply for the intended Role.