Overview
Pockets add areas to your forum where you can inject custom HTML, CSS or Javascript into your theme. It is a powerful tool that makes Vanilla flexible for ad placement, Google Analytics, and other small customizations.
Freeform HTML Pockets are designed to be used by advanced users and developers who can write and review their own code.
For more common use cases, Widgets may be more appropriate. You can read more about Widgets (formerly known as modules) here:
Using Pockets & Widgets to Enhance your Theme - Vanilla Success
Setup
Pockets are available on all plan levels. To activate it, simply locate it in your addon list (/dashboard/settings/addons) and toggle it on. It will then be available in the “settings” tab of your dashboard, listed under “Appearance” in the left side menu. You can navigate to the page directly by going to /settings/pockets
Working With Pockets
Once you navigate to the new Pockets menu in your Dashboard, you’ll have two options immediately available - “Add Pocket” and “Enable Pocket Locations.”
Enable Pocket Locations
Before you work with pockets, you need to know where the specific locations will appear on the front end of your community. Toggling this option ON will allow you to see all the places where a pocket is available. Only users with the permission to add/edit pockets will be able to see the Pocket Locations while this setting is on.
Add Pocket
From the main pockets page (Settings -> Pockets), you can add a pocket by clicking Add Pocket on the top right. Once you do, you will be presented with this interface:
Enable Pocket
Opt to enable or disable the pocket (turn ON or OFF)
Name
Choose something that will make it clear what the intended behaviour of the pocket is. This will not appear to end users.
Type
Once you select “Type” the remaining options will change based on your selection. This article will examine Custom HTML options only, if you are working with a particular widget, please see the corresponding article (Full list of widgets here)
Custom HTML
Here you can add custom HTML, if you are adding a different type of code, for example if you are trying to add CSS, you will need to add a <style> tag.
Placement and Conditions
You will notice there is a second tab labelled “Placement & Conditions” where you can target a pocket at a particular audience or area of the community:
Location
Each placeholder has a specific location in your community, as shown when “Enable Pocket Locations” is active. In this drop-down menu, you are able to select exactly where you want the pocket to appear.
We recently added a new location; After Banner for communities using Foundation.
Page
By default, a new pocket will be set to occupy the selected placeholder on every page of your community. If you’d rather it only work in certain areas, you can narrow the location down by using the drop-down menu and selecting a specific area of your forum - such as user profile pages or the inbox.
Role
You can configure a pocket to display for specific role and permission groups. This is useful if you're creating CTAs that are targeted to specific user groups.
Subcommunities
This option will only appear if you are using our subcommunities feature.
You can configure a pocket to appear for a specific subcommunity. Say you have an English subcommunity and a French subcommunity, or 2 distinct product subcommunities, you can easily create a pocket in one subcommunity, without impacting the other.
Category
Create a pocket for a specific category. You can also select "apply to subcategories" if you'd like your pocket to render in each subcategory in this section.
Note: If you make a selection for this option, you should not make any selection for the Page option.
Repeat
Some Pocket locations, such as “Panel” and “Between Discussions” have multiple placeholders to choose from. You can specify if you want the pocket to appear Before or After, as indicated by their location label. If you have more than one Pocket in the same Location and with the same Repeat value (e.g. two pockets in Content with the Repeat value of "After") they will appear in alphabetical order according to their names.
Numbered placeholders can be selected using “Given Indexes”. You will see for instance within the panel there are 8 available pocket locations; Before, Panel (1) - Panel (6), After.
Selecting “Repeat Every” will open two new settings, allowing you to select the starting point and frequency of the pocket's appearance. This is geared towards placing content, such as advertisements, between comments or discussions.
Conditions
Here you can choose several options:
Test Mode
Before you save your Pocket and have it go live to everyone in your community, you can toggle this switch so the Pocket will only be seen by administrators with permission to manage Pockets. Once you’re satisfied that the Pocket is working as expected, you can toggle Test Mode off and save again, pushing the Pocket out to the public.
Debugging
It’s important to note that Pockets should be reserved for advanced users. JavaScript errors and incorrect HTML can cause conflicts with Vanilla’s functionality. Debugging custom code in Pockets is outside the scope of Vanilla Support, so you must be able to resolve your own errors. Use test mode when trying out new things, test on staging and disable pockets if you suspect they are causing issues. Rotating ads are a common issue, so be diligent.
Using the Pockets Plugin to Add Analytics
While Vanilla Statistics provides an overview of your community, it's also simple to add whatever analytics package you prefer (Google Analytics, GetClicky, Crazy Egg, ect) with our Pockets add-on. Once you have the Pockets Plugin enabled, get the Javascript code or tag from your analytics provider, open up the Pockets plugin and click "Add Pocket". The next step is to fill in the information.
In the body box, copy the code given to you by your Analytics provider. For location, select the Header or Footer section (depending on your provider's requirements). The final step is to choose the repeat option. Select "before" if you want the code to be placed "before" the header (which is recommended by Google Analytics). To place the analytics code in the footer, choose "after" so your Analytics tag will be at the bottom of your page just before the </body> tag.
Common Pocket Usecases
Google Analytics
https://success.vanillaforums.com/kb/articles/368-google-analytics-gtag-js-foundation
Google Tag Manager
https://success.vanillaforums.com/kb/articles/136-google-tag-manager-vanilla-forums
Verifying your site with Google Search Console
https://success.vanillaforums.com/kb/articles/325-verify-your-site-with-google-search-console
Additional resources
Click the link below to access a video expanding on what you learned in this article.
