KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

WPFAevent

★ 799 Open GitHub ↗

Wordpress Plugin for FOSSASIA events website

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# WordPress FOSSASIA Event Plugin (WPFAevent)

![Node version](https://img.shields.io/badge/node-%3E%3D24-brightgreen)

The **FOSSASIA Event Plugin** provides WordPress integrations for [Eventyay](https://eventyay.com)-based events. It lets you display event landing pages, speakers, events, past events, schedules, and code of conduct content using classic page templates, Gutenberg blocks, or shortcodes. Shortcodes and blocks use embedded template rendering so WPFA content can live inside existing theme pages without the standalone template header/footer.

This plugin is maintained by [FOSSASIA](https://fossasia.org) and is compatible with the **eventyay** platform.

## Features

- Display **speakers**, **sessions**, and **event schedules** from Eventyay or other compatible APIs.
- Works with the unified **Eventyay (Django + Vue 3)** architecture.
- Includes an **admin settings page** to configure JSON API endpoints and cache duration.
- Supports WPFA template **shortcodes** for embedding event pages anywhere on your site.
- Provides Gutenberg **blocks** for the landing, speakers, events, past events, schedule, and code of conduct templates.
- Uses embedded template output for shortcodes and blocks so templates work in classic and block themes.
- Built with modern WordPress development practices:
  - Class‑based structure
  - Hooks and actions
  - Internationalization (translation‑ready)
- Includes **placeholder data** for local development and testing.
- Easily extendable with custom templates, endpoints, or additional shortcodes.

---

## Requirements

- WordPress **5.8** or higher
- PHP **7.4** or newer
- HTTPS‑enabled server (for API calls)
- The WordPress REST API and `wp_remote_get()` must be available

> **For contributors only:** Node.js >= 24 is required for the npm-based lint/format toolchain (`npm install`, `npm run lint`, etc.). It is not needed to install or use the plugin.

## Installation

1. **Clone the repository** into your WordPress `wp-content/plugins/` directory:
   ```bash
   git clone https://github.com/fossasia/WPFAevent.git event-plugin
   ```
2. **Install JavaScript dev tooling** *(contributors only — not required to use the plugin)*:
   ```bash
   # If you use nvm:
   nvm install 24 && nvm use 24
   npm install
   ```
3. Activate **Event Plugin** in the WordPress Admin under `Plugins → Installed Plugins → Event Plugin → Activate`.
4. Configure your API endpoints:
   - Go to **Settings → Event Plugin** in the WordPress Admin.
   - Enter the URLs of your Eventyay API endpoints for **Speakers**, **Sessions**, and **Schedule**.
   - Optionally adjust the **cache time (TTL)** in seconds.
5. Add WPFA template shortcodes to your pages or posts, for example:
   ```text
   [wpfaevent_landing]
   [wpfaevent_speakers]
   [wpfaevent_events]
   [wpfaevent_past_events]
   [wpfaevent_schedule]
   [wpfaevent_code_of_conduct]
   ```

You can also add the matching WPFA blocks in the block editor.

## Development

| Script | Command | Description |
|--------|---------|-------------|
| `npm run lint` | `eslint .` | Lint all JavaScript files using the WordPress ESLint config |
| `npm run lint:fix` | `eslint . --fix` | Auto‑fix lint errors |
| `npm run format` | `prettier --write "**/*.{js,json}"` | Apply Prettier formatting |
| `npm run phpcs` | `composer phpcs` | Run PHP_CodeSniffer on PHP files |
| `npm run phpcbf` | `composer phpcbf` | Auto‑fix PHP coding‑standard violations |
| `npm run phpstan` | `composer phpstan` | Run PHPStan static analysis |
| `npm run check` | `npm run lint && npm run phpcs && npm run phpstan` | One‑command quality check (JS + PHP) |

> **Tip:** Before opening a Pull Request, run `npm run check` locally to ensure both JavaScript and PHP code meet the project’s standards.

## Directory Structure

```
event-plugin/
│
├─ event-plugin.php                 → main plugin file (entry point)
│
├─ includes/
│   ├─ class-event-loader.php       → initializes hooks and shortcodes
│   ├─ class-event-api.php          → handles remote API fetching with caching
│   ├─ class-event-admin.php        → admin settings page (API config, cache)
│   ├─ class-event-speakers.php     → logic for speakers shortcode
│   ├─ class-event-sessions.php     → logic for sessions shortcode
│   └─ class-event-schedule.php     → logic for schedule shortcode
│
├─ public/
│   ├─ partials/
│   │   ├─ event-speakers.php       → speaker display template
│   │   ├─ event-sessions.php       → sessions display template
│   │   └─ event-schedule.php       → schedule display template
│   ├─ css/
│   │   └─ event-public.css         → public-facing styles
│   └─ js/
│       ├─ event-public.js          → public-facing scripts
│       └─ event-admin.js           → admin JS for “Test Connection” buttons
│
├─ assets/
│   └─ img/
│       └─ speaker-placeholder.jpg  → placeholder image (no real data)
│
├─ languages/
│   └─ event-plugin.pot             → base translation template
│
└─ README.md
```

## Shortcodes Overview

| Shortcode                             | Description                                      | Output Source  |
| ------------------------------------- | ------------------------------------------------ | -------------- |
| `[wpfaevent_landing]`                 | Displays the WPFA event landing page.            | WPFA template  |
| `[wpfaevent_speakers]`                | Displays the speaker directory.                  | WPFA template  |
| `[wpfaevent_events]`                  | Displays the upcoming events hub.                | WPFA template  |
| `[wpfaevent_past_events]`             | Displays the past events archive.                | WPFA template  |
| `[wpfaevent_schedule]`                | Displays the event schedule.                     | WPFA template  |
| `[wpfaevent_code_of_conduct]`         | Displays the code of conduct content.            | WPFA template  |
| `[wpfaevent_template template="events"]` | Embeds a selected WPFA template by template key. | WPFA template |

**Note:** All shortcodes now accept an optional `align` attribute (`align="wide"` or `align="full"`). When provided, the shortcode output will be wrapped in a corresponding alignment container, e.g., `[wpfaevent_events align="full"]`. If omitted, the shortcode renders the raw embed without altering the surrounding layout.

The generic `wpfaevent_template` shortcode accepts a `template` attribute. Supported values include `landing`, `speakers`, `events`, `past_events`, `schedule`, and `code_of_conduct`.

## Blocks Overview

| Block Title              | Block Name                         |
| ------------------------ | ---------------------------------- |
| WPFA Landing             | `wpfaevent/landing`                |
| WPFA Speakers            | `wpfaevent/speakers`               |
| WPFA Events              | `wpfaevent/events`                 |
| WPFA Past Events         | `wpfaevent/past-events`            |
| WPFA Schedule            | `wpfaevent/schedule`               |
| WPFA Code of Conduct     | `wpfaevent/code-of-conduct`        |

WPFA blocks render dynamically and share the same embedded template mode as the shortcodes.

Each generic template shortcode can accept optional attributes, for example:

```text
[wpfaevent_template template="speakers"]
```

## Speaker Data Model

Speaker profiles use the `wpfa_speaker` custom post type, registered speaker metadata, and the event-speaker relationship fields `wpfa_event_speakers` and `wpfa_speaker_events`.

See [`docs/speaker-data-model.md`](docs/speaker-data-model.md) for the speaker fields, REST-exposed metadata, relationship sync behavior, and the interim session metadata approach.

## Settings Page

Navigate to **Settings → Event Plugin** to configure:

* **Speakers Endpoint:** `https://example.org/api/v1/events/{id}/speakers`
* **Sessions Endpoint:** `https://example.org/api/v1/events/{id}/sessions`
* **Schedule Endpoint:** `https://example.org/api/v1/events/{id}/schedule`
* **Cache TTL (seconds):** Duration for transient caching of API results
* **Test Buttons:** Verify that endpoints respond with valid JSON data

If the fields are left empty, the plugin falls back to placeholder content for development.

## Calendar Export And Timezones

The schedule page exposes an **Add to calendar** link when an event has a valid start date. The link opens a Google Calendar event template. Individual events can also be downloaded as `.ics` files from `/wp-json/wpfaevent/v1/events/{event_id}/ics`.

Event timezone behavior is deterministic:

* Each event can save an explicit timezone. If it is empty, WPFAevent falls back to the WordPress site timezone.
* All-day events export date-only `DTSTART` and exclusive date-only `DTEND` values.
* Timed events are interpreted in the event timezone and exported as UTC `DTSTART`/`DTEND` values.

Run the calendar export checks with:

```bash
php tests/calendar-test.php
```

## Development Notes

* Core logic resides in `includes/`, presentation templates in `public/partials/`.
* All user-facing text should use translation functions `__()` or `_e()`.
* Load assets using `wp_enqueue_script()` and `wp_enqueue_style()`.
* Use the built-in caching layer via transients in `class-event-api.php`.
* Do **not** commit large demo data or real images — use placeholders only.
* To modify the layout, you can override templates in your theme directory:

```
  your-theme/event-plugin/partials/event-speakers.php
  ```

WordPress will automatically use the theme’s version if it exists.

---

## Local Development

1. Install WordPress locally (e.g., using LocalWP, Docker, or WP-CLI).
2. Place this plugin in `wp-content/plugins/`.
3. Activate it and navigate to **Settings → Event Plugin**.
4. Test with public Eventyay JSON endpoints or your own mock data.
5. Use `wp wpfa import` again whenever you need to refresh imported events and speakers from the configured Eventyay source.

To debug API calls, enable WordPress debug logging in `wp-config.php`:

```php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
```

Logs can be found in `/wp-content/debug.log`.

## Translation

* The plugin is fully internationalization-ready (`Text Domain: event-plugin`).
* Translations are located in the `languages/` directory.
* You can generate `.mo` and `.po` files using tools such as **Poedit** or **Loco Translate**.

## Contributing

Contributions are welcome!

* Fork the repository on GitHub
* Create a feature branch:

```bash
  git checkout -b feature/my-feature
  ```
* Commit and push your changes, then submit a **Pull Request**
* Follow **WordPress PHP coding standards**

### Development commands

```bash
# Install dev dependencies
composer install

# Run code style checks
composer phpcs

# Auto-fix code style violations
composer phpcbf

# Run static analysis
composer phpstan

# Bootstrap the WordPress test environment
# Requires WP_DB_USER and WP_DB_PASS env vars (defaults: wp_test / test_password)
composer setup-tests

# Run the test suite
composer test

# Run a specific test suite
composer test -- --testsuite Unit
composer test -- --testsuite Integration
```

Before submitting:

* Run `npm run check` to ensure both JS and PHP quality checks pass.
* Run `composer test` to ensure the full PHP test suite passes.
* Avoid committing binary or large files
* Test locally with caching disabled
* Ensure translations are wrapped correctly in `__()` or `_e()`

## License

WPFAevent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README