Using theme overrides, experienced web developers can customize existing Wild Apricot themes or create new ones.
Theme override is intended for people with advanced web design skills. Incorrect use may result in your website malfunctioning. We do not provide support related to theme overrides.
Theme overrides involve replacing or overriding theme files – the files that control the appearance and behavior of your current theme. Typically, your override files will include code to customize a feature or element of your theme.
You can also customize the appearance and behavior of your Wild Apricot site in other ways:
- by choosing different settings from the Colors and styles screen
- by entering CSS code on the CSS customization screen
- by add custom JavaScript
You should consider using theme overrides only after exploring these other customization methods, since theme overrides require a solid understanding of HTML and the theme building process.
Activating theme overrides
To activate theme overrides, follow these steps:
- Click the Theme overrides menu option within the Website module. To access the Website module from the main admin menu, click the Website menu.
- From the Theme overrides screen, click the Activate theme overrides button.
- Click the link to download the theme files.
You can download the theme files (stored in a zip file) to any location you choose. - Unzip the theme files to a location of your choice on your computer or network.
Now that you have downloaded and unzipped the theme files, you can modify them and upload your changes to customize an existing theme, or make a copy of them to create a new theme.
Customizing vs creating a theme
There are two approaches to using theme overrides to customize your site: customizing an existing theme, and creating a new theme.
The simplest approach is to customize an existing theme. This is what happens by default when you enable theme overrides. For instructions, see Customizing theme files (below).
If you want to create a theme from scratch, you can create a new folder in WebDav – or copy an existing theme structure – and start creating the theme. You can set the theme parent to one of our themes, or create a standalone theme.
Customizing theme files
Once theme overrides are enabled, a theme-specific folder is added to the Resources/Theme_Overrides folder on your site. The theme folder contains the same folder structure as the downloaded theme files, but the folders themselves are initially empty. Customizing your theme files involves uploading the modified files to the corresponding folder.
To customize your theme, follow these steps:
- Modify the downloaded theme files on your computer. For instructions, see Customizing theme elements, Theme files language syntax
- Upload the modified files to the corresponding theme folder under Theme_Overrides on your site via File management or WebDAV. Your copied files will be loaded in place of the original theme files, thereby overriding the default theme appearance or behavior. For a list of theme folder names and their corresponding themes, see Theme folder names.
- Click the Rebuild theme button on the Theme overrides screen.
- If you've used theme overrides to customize gadget settings or create custom gadgets, you may need to log off and back on again to view these customizations.
If you using theme overrides to customize an existing theme, rather than create a new one, do not modify MainConfig.cfg. Doing so may result in theme inheritance issues.
Testing theme overrides
To test your theme overrides, follow these steps:
- If you want to test your theme overrides without altering your current site, you can ask Wild Apricot Support to create a clone of your current site.
- Apply the theme override.
- Check how the customized pages appear in a different browser, or in the same browser but in incognito mode.
- Check the log files in the Theme_Overrides\Log folder for errors.
Theme override errors
If your override files contain errors, your theme could malfunction, and the appearance and/or accessibility of your site may be affected.
All theme override errors will be logged in the Theme_Overrides\Log folder, accessible through WebDAV.
When a theme override occurs, you can correct the problem by logging in as an administrator and going to the Theme overrides screen.
If the login box isn't available because of the site malfunction, you can login by adding /sys/safelogin to the end of your domain name. For example: http://www.example.com/sys/safelogin.
The Theme overrides screen will display a message for each error, with links to the error log files.
You can correct problems by deactivating theme overrides entirely, disabling individual overrides, or rebuilding the theme files.
Deactivating theme overrides
To deactivate theme overrides, click Disable theme overrides. The original theme settings will be restored.
Disabling individual overrides
The Theme overrides screen lists all override files currently in use on your site.
To disable an individual theme override, click the Delete button to the right of the override file name. This will delete the override file from your site, but not from the downloaded theme files on your computer or network.
Rebuilding theme files
Sometimes a theme file isn't compiled correctly, leading to a site malfunction. Clicking the Rebuild theme button will re-compile the override files. You should also rebuild the theme after uploading a theme override file.
Glossary of terms
To better understand the theme override process, you need to become familiar with the following terms:
Theme
A set of files describing your site's look and feel.
See Website themes
Theme assembly
The process in which theme files are assembled to render the theme.
See Theme generation process
Template engine
Scripting language for theme templates.
See Theme files language syntax
Master layout
A page outline, containing placeholders and graphical elements, to be used as the basis for theme-specific page templates.
See Master layouts, Customizing master layouts
Placeholder
A container in which gadgets and layouts can be dropped.
See Customizing master layouts
Gadget
An element on a web page that displays content.
See Gadgets, Customizing theme gadgets
Control
Reusable code segment that performs a specific action.
See Customizing theme controls
