Co-Deploy: Empowering Customization for Your Community Forum
At Higher Logic Vanilla (HLV), we understand that each organization has unique needs when it comes to community engagement. While many platforms offer basic theming and branding tools, Co-Deploy goes a step further, allowing Enterprise+ customers to fully customize and extend their Vanilla forums to meet specific brand requirements and business objectives. Whether you need custom integrations, advanced widgets, or entirely bespoke functionality, Co-Deploy gives your team the power to take full control of your community’s design and features.
From local environment setup to advanced addon creation, HLV is here to guide you every step of the way, ensuring your community forum evolves exactly as you envision it.
Limitations
VF Code Deploy comes with several key restrictions to maintain platform integrity:
- Collaboration: Code collaboration is limited to the official client repository under our organization on GitHub.
- Pull Requests: All code changes must be submitted for review via pull requests.
- Collaborators: Each customer is limited to 8 collaborators. These collaborators are managed by HLV staff and are added or removed through a support ticket.
- Cloud-Only Features: We cannot release or share source code for cloud-only features.
- These features include but are not limited to:
- Events, Groups, Sub-communities, Analytics, Webhooks, and KB Articles
- Add-On Approval: Clients must receive approval for new add-ons before proceeding with development. Requests can be made during an implementation guidance call with the Vanilla Engineering team via Zendesk.
- Security and Performance: We may impose additional limitations to protect platform security, minimize performance issues, and reduce maintenance overhead.
- Code Ownership: All code authored by Vanilla staff remains the property of Vanilla. By contributing to the repository, you grant us an unrestricted license to use the code as outlined in the license hosted in your Github Repo.
Challenges
Setting up and maintaining local development environments can be complex, particularly when dealing with a combination of open-source and closed-source components. Here are some challenges you may encounter:
- Closed-Source Components: Some key features, such as Subcommunities and Groups, are not available as open-source and cannot be provided to protect HLV's intellectual property.
- Local Environment Setup: We offer a Mac-based Docker container for local development, which is development-only and not intended for production use. It is possible to run Windows-based Docker environments, but your initial setup maybe challenging and we don't have ongoing support for Windows based docker environments.
- Cloud-Hosted Development: We offer a cloud-hosted environment for testing, which is useful for functionality testing, but not for performance evaluation.
- Support: While we provide public documentation and can answer specific questions, we do not offer general support for local setup issues.
Minimum Technical Requirements
The following are the minimum technical guidelines necessary to pass code review. These requirements address both common pitfalls and platform-specific limitations:
- Database Changes:
- Do not create new database tables; Vanilla Development can create custom tables for you.
- Submit your table name, and desired schema to support via Zendesk ticket.
- Adding columns to your own custom tables is allowed, but adding columns to Vanilla’s default tables (e.g., GDN_*) is not permitted.
- Avoid writing custom SQL queries; use our structured query builder where possible.
- Performance Considerations:
- Cache data using memcached if it’s frequently queried, with a reasonable time-to-live (TTL).
- Do not exceed the following limits:
- 1500 records per query.
- Offset larger than 10,000 records (e.g., for pagination).
- More than 20,000 users notified at once via email.
- 2,000 categories without using Flat Categories.
- Code Practices:
- User-Generated Content (UGC) must be escaped using
htmlspecialchars() or purified with HTMLawed. - Limit outbound API calls to one per inbound request, and ensure responses are cached.
- Use addon.json for managing dependencies between add-ons.
- Forking: Do not fork our add-ons or assets.
- All customizations must be documented in a CUSTOMIZATIONS.md file in your repo.
- All plugins and themes should be placed in their own subfolders under the appropriate directories (plugins or themes).
- The media folder is for storing assets and images but should not be used in production or staging environments.
Any code that violates these principles will be rejected. If you are unsure how to meet the requirements without violating any principles, reach out for a developer call via your CSM.
Code Review Guidelines
Important: HLV does not engage in code reviews on customer code. It is the responsibility of the customer’s team to ensure that all code adheres to our technical and security standards before submitting it for deployment. However, we provide guidelines to help you meet these standards and ensure smooth collaboration during the deployment process.
Release Process
- Development: Use the open-source version of Vanilla for local development. Make pull requests into the appropriate target branch (Dev, Stage, or Master) based on where you intend to deploy your changes.
- Approval: Once the code is reviewed and approved, inform Vanilla staff of your intended release.
- Release Coordination: Vanilla Support will work with you to schedule the release of your custom code during the next scheduled release. If you need a custom release, provide at least one week's notice for adequate staffing.
- Release Timing: Releases on Fridays or weekends are discouraged, as Vanilla Development staff will not be available for support during this time.
1) Organization Setup and Training
a) Onboarding and Access Management
The first step in the Co-Deploy process is for the customer to work with their implementation manager at Higher Logic Vanilla (HLV) to identify team members who will need read and write access to the relevant repositories.
Access to the Co-Deploy GitHub repositories will be managed by HLV staff. The specific repository for the Co-Deploy process can be found at github/vanillaforums.com. The customer must provide the GitHub usernames of their developers to set up this access.
Note: While HLV manages repository access, it is the customer's responsibility to ensure that all individuals have the necessary web development skills to participate. HLV can provide basic deployment support, but code review and best practice guidance are limited to the initial launch phase.
b) Training Sessions
Once the organization and user access have been configured, HLV will schedule two training sessions with the customer’s development team.
- Local Environment Setup (1 Hour)
Coordinated by the customer's implementation manager, this session will walk developers through the necessary steps to set up the open-source version of Vanilla on their local environment using Docker. This allows developers to run Vanilla locally for testing and development purposes. - Building Your First Custom Addon or Theme (1 Hour)
In the second session, developers will learn how to build their first custom addon or theme. Developers must first read through the basic theming and tooling documentation provided by HLV. This is an essential step, as it prepares developers to handle common customization tasks. HLV strongly recommends using in-app tooling for customizations wherever possible to maintain compatibility and efficiency. Developers must also sign up for the support community at success.vanillaforums.com for ongoing assistance.
c) Access to Tools
Access to the app tools is gated by the customer’s site administrator, ensuring that only authorized individuals can perform actions within the platform. Meanwhile, access to the Co-Deploy GitHub repository is managed and granted by HLV staff, with developers being provided with the necessary permissions to interact with the repository after completing the training sessions.
2) Repo Organization
When starting with the Co-Deploy process, customers will be provided with a basic framework within their organization’s repository. This framework is structured to ensure smooth development and easy customization of your Vanilla forum.
a) Repo Structure
The repository will be organized into the following four core directories:
- Media
This directory is used for storing any additional images, GIFs, videos, or other media that you may need to host and reference within your forum. - Plugins
Here, you’ll make the majority of your application-level changes. This is where you’ll implement integrations, make API changes, and extend the Vanilla platform’s functionality with custom plugins. - Static
The Static directory is a working directory where compiled files are stored. It helps ensure that the code structure remains organized and optimized for deployment. - Themes
The Themes directory is where you will specify your custom themes. Note that these are file-based themes, which will override the Styleguide section of the application. Once a theme created here is enabled on your site, it becomes the only place you can make future changes to the site’s design.
Along with these directories, the repository will contain basic files such as .gitignore, LICENSE, and README. The deploy.json file is for HLV staff only and directs which branches are deployed to which environments (Dev, Stage, or Production).
b) Branching and Git Workflow
HLV staff will set up three primary branches for you: Dev, Stage, and Master. These branches form the foundation of your development workflow, but it’s up to the customer to maintain a clean branching and Git strategy.
- Dev Branch: This is where development takes place. Developers should make pull requests to this branch for testing and review.
- Stage Branch: Once changes are approved in Dev, they should be merged into Stage. This environment serves as the pre-production version of the site.
- Master Branch: After testing in Stage, the changes should be merged into the Master branch, which is used for production deployments.
Some customers prefer to have pull requests between all branches to ensure that code is reviewed at each step before it moves forward.
c) Best Practices
As with any development process, adhering to best practices around file and folder naming conventions is essential for keeping the repository organized and manageable. Make sure to name files and folders clearly and consistently to maintain a smooth workflow, especially as the team grows or the project becomes more complex.
3) Building Custom Addons
This guide provides an in-depth approach to building custom widgets and addons for Vanilla using their CodeDeploy system. It covers both backend and frontend development, from setting up the repository to deploying the addon and integrating with Vanilla’s deployment pipeline.
Prerequisites
- Vanilla Platform Access: Ensure you have an active Vanilla account and necessary permissions to deploy to environments (e.g., development, staging, production).
- PHP Knowledge: Required for backend integration.
- React & TypeScript Knowledge: Required for building frontend components.
- GitHub: Familiarity with GitHub for version control and deployment.
Repository Structure
Your addon will be developed inside a GitHub repository, which Vanilla uses for deployments. The structure should be well-organized:
/repo
/php # Backend PHP files (widgets, API calls)
/js # JavaScript files (React components)
/assets # Static assets like images, CSS files
/config # Configuration files (schema, settings)
1. Backend: Creating the Widget PHP Class
Vanilla uses a PHP backend to register custom widgets and handle the logic for widget data retrieval and API integration.
Step-by-Step:
<?php
class MyCustomWidget extends Vanilla\Widgets\Widget {
public $widgetName = 'My Custom Widget';
public $widgetID = 'custom-widget-id';
public $widgetIcon = 'path_to_icon';
// API endpoint for fetching data
private $apiUrl = 'https://api.example.com/data';
// Constructor method, if necessary
public function __construct() {
// Initialize any required properties
}
// Function to fetch widget data
public function fetchData() {
// Example of fetching data from an API
$data = file_get_contents($this->apiUrl);
return json_decode($data, true); // Assuming the response is JSON
}
// Define schema for widget settings
public function schema() {
return [
'organization' => 'Example Org',
'max_items' => 10,
'sort_order' => 'desc',
// Additional widget-specific settings
];
}
}
?>
- Explanation:
- Widget Name/ID: These are used to uniquely identify the widget on the Vanilla platform.
- API Integration: You can fetch data from external APIs, and this can be configured dynamically based on the widget schema.
- Schema: Defines user-configurable settings like the maximum number of items, sorting preferences, etc.
2. Widget Schema for Customization
Schema Definition helps to expose configurable settings for the widget, allowing non-developers (like community managers) to customize the widget.
public function schema() {
return [
'organization' => 'Example Org',
'max_items' => 5, // Number of items to display
'sort_order' => 'asc', // Sorting method
'filter' => 'all', // Custom filter
];
}
The schema will be exposed to the frontend, where users can adjust parameters (such as number of items, sorting order) directly in the Vanilla UI.
3. Frontend: React & TypeScript Integration
The frontend of your widget will be built using React and TypeScript. Here, you will manage the component rendering and UI customization.
- React Component Structure:
- Interface Definition: Define the structure of the widget's properties using TypeScript interfaces.
- Component Development: Create a React component that receives props and renders the widget UI.
// Typescript interface for widget properties
interface WidgetProps {
organization: string;
maxItems: number;
sortOrder: 'asc' | 'desc';
data: Array<any>;
}
// React component to render the widget
const MyCustomWidget: React.FC<WidgetProps> = ({ organization, maxItems, sortOrder, data }) => {
const sortedData = data.sort((a, b) => sortOrder === 'asc' ? a.date - b.date : b.date - a.date);
const limitedData = sortedData.slice(0, maxItems);
return (
<div className="my-widget">
<h3>{organization} Data</h3>
<ul>
{limitedData.map((item, index) => (
<li key={index}>{item.name}</li>
))}
</ul>
</div>
);
};
export default MyCustomWidget;
- Explanation:
- Props:
organization, maxItems, and sortOrder are passed from the backend or schema to the component. - Sorting & Limiting: The data is sorted based on the configuration and limited to
maxItems.
const WidgetWrapper = styled.div`
background-color: #f4f4f4;
padding: 20px;
border-radius: 8px;
`;
- Vanilla uses CSS-in-JS for styling, which is handled by Emotion in the example:
4. Caching Data and Improving Performance
To optimize performance and avoid unnecessary API calls, Vanilla supports data caching for widgets.
// Check if data is already cached before making a new API request
public function fetchData() {
$cacheKey = 'custom-widget-data';
$cachedData = cache($cacheKey);
if ($cachedData) {
return $cachedData;
}
$data = file_get_contents($this->apiUrl);
$data = json_decode($data, true);
cache($cacheKey, $data, 3600); // Cache for 1 hour
return $data;
}
- Frontend Caching:
You can leverage browser cache or service workers to cache data in the browser for further optimizations, especially if the widget data is not changing frequently.
5. Deploying Your Addon
- Deploy Steps:
- Vanilla supports environments like Dev, Stage, and Production.
- Deploy the changes using the UI and monitor the deployment progress.
- Push your changes to the desired branch (e.g.,
master). - On the Deployment page in Vanilla, select the correct branch to deploy from GitHub.
- Click Deploy, and Vanilla will handle the merging and deployment of the code to the platform’s infrastructure.
- Track the deployment status and verify any errors using the deployment logs.
6. Frontend Preview and UI Customization
Once the widget is deployed, stakeholders can preview it directly in the Vanilla UI. They can modify widget parameters like sorting and the number of items displayed.
- Preview Component:
- This component provides a live preview for the UI as changes are made, which is rendered in real-time in the admin panel.
- Widget Management: Vanilla allows admins to:
- Add multiple instances of the widget on different pages.
- Customize widget visibility based on roles (admin, user, etc.) or device type (desktop vs. mobile).
7. Testing & Maintenance
- Local Development: Vanilla offers Docker images for local development that simulate the production environment, so you can preview changes locally before pushing them.
- Version Control: Ensure you’re always working with the correct PHP version by checking Vanilla’s release notes. If the PHP version is upgraded, Vanilla will notify you, and you should update your code to ensure compatibility.