Theming Guide

Pockets

⚠️ IMPORTANT: Pockets, and their associated widgets, represent our classic design experience. For a more streamlined experience, with deeper layout customization and expanded widget capabilities, we recommend upgrading to our Layout Editor.

📝 NOTE: Pockets only display in legacy layouts, and will not function in Layout Editor layouts.

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.

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:

Only display on mobile browsers.
Never display on mobile browsers.
Don't display for embedded comments. (see main article on embedding)
Display in dashboard. (not recommended)
This pocket is an ad. Users with the no ads permission will not see this pocket. (see main article on permissions)

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

Additional resources

Click the link below to access a video expanding on what you learned in this article.

https://success.vanillaforums.com/kb/articles/455