# Speakers for The Events Calendar

A WordPress plugin that adds a Speaker custom post type to [The Events Calendar](https://theeventscalendar.com/), letting you create speaker profiles, attach them to events, display them on event pages, and bulk-import them from CSV.

## Requirements

| Requirement | Version |
|---|---|
| WordPress | 6.0+ |
| PHP | 8.0+ |
| The Events Calendar | Any current release |

## Features

- **Speaker CPT** — a dedicated `tec_speaker` post type with title, bio (editor), excerpt, featured image, website URL, and email fields.
- **Event speaker picker** — a searchable multi-select on every event edit screen, powered by SelectWoo (TEC's bundled library) with an automatic CDN fallback.
- **Front-end display** — speakers are rendered in a responsive card grid beneath the event meta block on single event pages.
- **`[tec_speakers]` shortcode** — display a filterable speaker archive anywhere on the site.
- **CSV bulk importer** — import speakers from a spreadsheet; duplicate names are skipped automatically.

## Installation

1. Upload the `speakers-for-the-events-calendar` folder to `/wp-content/plugins/`.
2. Activate through **Plugins → Installed Plugins**.
3. The Events Calendar must be installed and active; the plugin shows an admin notice if it is not.

## Usage

### Adding speakers

Go to **Speakers → Add New**. Fill in the title (speaker name), the bio in the editor, and optionally a website URL and email in the **Speaker Details** sidebar panel. Set a featured image for the speaker photo.

### Attaching speakers to an event

Open any event in the editor. A **Speakers** meta box appears in the main column. Type to search and click names to select; click again to deselect.

### Displaying speakers

Speakers are automatically displayed beneath the event meta block on single event pages — no configuration needed.

To display a speaker directory on any page or post, use the shortcode:

```
[tec_speakers]
[tec_speakers limit="20"]
[tec_speakers search="Jane"]
```

| Attribute | Default | Description |
|---|---|---|
| `limit` | `50` | Maximum number of speakers to display |
| `search` | _(empty)_ | Filter speakers by name or content |

### CSV import

Go to **Speakers → Import CSV**. The CSV must have a header row with these columns (order matters):

```
name, bio, email, website, image
```

| Column | Required | Notes |
|---|---|---|
| `name` | Yes | Speaker's full name |
| `bio` | No | Plain-text biography |
| `email` | No | Stored as private meta, not displayed publicly |
| `website` | No | Full URL including `https://` |
| `image` | No | Ignored — add photos via Featured Image after import |

Speakers whose name (ignoring common honorifics and extra whitespace) matches an existing speaker are skipped. No existing records are overwritten.

## Hooks

### Actions

| Hook | Description |
|---|---|
| `tribe_events_single_event_after_the_meta` | Where speakers are injected on single event pages |

### Filters

None currently. Open an issue if you need to customise output or query arguments.

## Data

| Meta key | Post type | Description |
|---|---|---|
| `_tec_event_speakers` | `tribe_events` | Array of `tec_speaker` post IDs attached to the event |
| `_tec_speaker_website` | `tec_speaker` | Speaker website URL |
| `_tec_speaker_email` | `tec_speaker` | Speaker contact email (private) |

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

GPLv2 or later. See [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html).