Koha Extension: Celebrations

Add a festive touch to your library OPAC for every special occasion! This plugin allows you to apply seasonal themes and animations for celebrations such as Christmas, Halloween, Valentine’s Day, and many more.

For an easier onboarding and to better understand the user experience, it is recommended to take a look at the instructions.

Main features

• Themes activated by date range
• Fully customizable themes
• Intuitive administration interface
• Integrated OPAC preview
• Data-driven architecture (JSON)
• Multi-language support
• Compatible with desktop and mobile OPAC

Installation & Development

This section explains how to install the plugin in development mode in order to modify the code and test it on a local Koha instance.

If you don’t have Koha installed locally, you can easily install it with the following command:

git clone --branch main --single-branch --depth 1 https://git.koha-community.org/Koha-community/Koha.git koha

If you want to learn more about Koha, here is the official documentation:

Steps

1. Fork the project and clone it to your workstation

2. Create a symbolic link to Koha

   In your Koha instance (usually /var/lib/koha/<instance>/plugins), create a symbolic link to the plugin directory:

ln -s /path/to/koha-plugin-celebrations /var/lib/koha/<instance>/plugins/Koha/Plugin/Celebrations

3. Install the plugin in Koha

Run the Koha script to install plugins from your Koha directory:

./misc/devel/install_plugins.pl

4. Install front-end dependencies

Inside the plugin directory:

npm install

5. Build the admin interface JavaScript files

The plugin uses an automatic bundling system: all files located in Koha/Plugin/Celebrations/js/template/ are merged into a single JavaScript file loaded in the admin interface.

To apply your changes:

Development mode (with file watching):

npm run dev

This command continuously watches the js/template/ directory and automatically rebuilds js/dist/celebrations-bundle.js on each change.

First installation or cloning an existing plugin

When installing or cloning the plugin for the first time:

• This generates the celebrations-bundle.js file
• It updates the template to load this bundle

If you are using the plugin in development mode via a symbolic link (in /var/lib/plugins/), bundling must be done before opening the admin page, otherwise no scripts will be loaded.

Architecture (overview)

The plugin is built on a modular, stable, and extensible architecture:

• Perl backend: business logic, OpenAPI, asset management
• JavaScript frontend: admin interface + OPAC preview
• JSON configuration: themes, options, translations

---

Detailed architecture documentation (structure, components, flows) is available here:

Contribution & development

You want to:

• add a new theme
• modify or create a visual effect
• understand the internal architecture
• contribute to the project

Check out the dedicated guide:

Production deployment

In production:

• the plugin must be installed as a .kpz file
• no JavaScript bundling is required
• the js/dist/ files are already included
• make sure all tests pass

Do not use symbolic links in production.

Koha compatibility

This plugin is compatible with:

• Koha ≥ 24.05
• Classic and responsive OPAC
• Modern browsers (Chrome, Firefox, Edge)

Older Koha versions are not guaranteed.

Known limitations

• Heavy visual effects may impact mobile performance
• The iframe preview may slightly alter rendering
• PLACK must be restarted for OpenAPI and static routes to work properly

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.