` and passing your options. The plugin accepts events either as a static JavaScript array or as a URL string to fetch JSON via AJAX.
Events must adhere to the IEvent interface: ```JavaScript const myEvents = [ { date: "2024-12-25 10:00:00", // Date format depends on `jsonDateFormat` option title: "Christmas Track Day", // Display name url: "https://example.com", // Optional link description: "Join us on the track for Christmas!", isLocked: false, // Show the "cross" icon on the calendar isSpecial: true // Show the "exclamation" coin icon } ]; // Initialize $('#myCalendar').eventCalendar({ jsonData: myEvents, jsonDateFormat: "human", // "human" parses YYYY-MM-DD HH:MM:SS. "timestamp" parses unix ms. locale: "en-US", // Forces English. If omitted, falls back to the browser's language. showDescription: true, openEventInNewWindow: true }); ``` #### Asynchronous Loading (AJAX) If you pass a URL string instead of an array, the plugin will make a GET request to your server. It automatically appends current calendar state parameters so your backend can return paginated data: ``` GET /api/events?limit=4&year=2024&month=11&day=0 ``` ```JavaScript $('#myCalendar').eventCalendar({ jsonData: "/api/events", cacheJson: false // Set to false to trigger a new AJAX call every time the user changes the month }); ``` #### 🌍 **Internationalization (i18n)** jQuery Event Calendar comes with a modern, namespace-driven localization system (``GpsEventCalendar.i18n``). You can load all languages at once using `all.min.js`, or load specific ones (e.g., `it-IT.js`). Unlike older versions, **you do not need to manually pass the i18n object**. Just define the `locale` property: ```html ``` #### ⚡ **Runtime API Methods** You can interact with an already initialized calendar using the public method dispatcher. Currently, you can change the calendar language on the fly without reloading the page or re-fetching events: ```JavaScript // Change the language to Spanish dynamically (proper locale must be loaded) $('#myCalendar').eventCalendar('changeLocale', 'es-ES'); ``` **Destroy the instance safely:** If you need to remove the calendar (e.g., in a Single Page Application), use the `destroy` method to safely unbind all events and prevent memory leaks: ```JavaScript $('#myCalendar').eventCalendar('destroy'); ``` #### 🧩 **Custom Event Templates (Advanced)** If you want to render a completely custom UI for the events in the list (e.g., injecting images, custom buttons, or badges), you can pass an `eventTemplateBuilder` function in the options. > ⚠️ **SECURITY WARNING:** When overriding the internal builder, the plugin bypasses its native HTML sanitization. You **must** sanitize the event data (`event.title`, `event.description`, etc.) to prevent XSS attacks if the data comes from a user or external API. ```JavaScript $('#myCalendar').eventCalendar({ jsonData: myEvents, eventTemplateBuilder: function(event, i18nText) { // Build your completely custom HTML structure return `

${escapeHtml(event.title)}

${escapeHtml(event.description)}

`; } }); // A simple utility to sanitize strings function escapeHtml(unsafe) { if (!unsafe) return ""; return unsafe .replace(/&/g, "&") .replace(//g, ">") .replace(/"/g, """) .replace(/'/g, "'"); } ``` #### 🎨 Theming & Dark Mode (CSS Native Variables) Version 2.0+ adopts CSS Custom Properties (`:root` variables) for styling. This makes the calendar easy to theme without needing to compile SCSS! **Dark Mode is supported out-of-the-box.** The calendar automatically detects the user's OS preferences `(prefers-color-scheme: dark)` and flips the color palette seamlessly. **How to force a mode** If you want to force a mode regardless the local OS configuration, you can use this js code: ```JavaScript // Toggle theme and enforce it globally const newTheme = currentTheme === 'dark' ? 'light' : 'dark'; document.documentElement.setAttribute('data-theme', newTheme); ``` **Custom theme** If you want to create a custom theme or integrate the calendar into your brand colors, simply override the CSS variables in your own stylesheet: ```css /* Your custom stylesheet (loaded after eventCalendar.css) */ :root { /* Change the main theme color to purple */ --ec-title-bg: #6f42c1; --ec-event-title-color: #6f42c1; /* Change the current day highlight to red */ --ec-today-bg: #dc3545; } ``` Here is the list of the most commonly modified variables: - `--ec-title-bg`: Background color of the top bar (Month/Year) - `--ec-event-title-color`: Text color for events in the list - `--ec-today-bg`: Highlight color for the current day - `--ec-event-bg`: Highlight color for days containing events --- ## 🤝 Development & Contributing If you want to contribute or modify the source: 1. Clone the repository. 2. Run `npm install` to grab all development dependencies. 3. Run `npm run build` to compile the TypeScript files into the `/dist` folder. 4. Run `npm run test` to execute the Jest test suites. Maintained with ❤️ by GP Software Engineering.