George Lambert
b4150c8250
Compose-ready workspace: packages/zappier (rate card, portal, Stripe), packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier (CLI app), vendor/zapier-platform, and research/zapier vendor corpus. Gate 0 structure checks pass. Product code and research are not yet wired.
142 lines
3.3 KiB
Markdown
142 lines
3.3 KiB
Markdown
# dynamic-dropdown
|
|
|
|
This Zapier integration project is generated by the `zapier-platform init` CLI command.
|
|
|
|
These are what you normally do next:
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install # or you can use pnpm or yarn
|
|
|
|
# Run tests
|
|
zapier-platform test
|
|
|
|
# Register the integration on Zapier if you haven't
|
|
zapier-platform register "App Title"
|
|
|
|
# Or you can link to an existing integration on Zapier
|
|
zapier-platform link
|
|
|
|
# Push it to Zapier
|
|
zapier-platform push
|
|
```
|
|
|
|
Then, to add more features, you can use the `zapier-platform scaffold` command, for example:
|
|
|
|
```bash
|
|
# Add a trigger
|
|
zapier-platform scaffold trigger contact
|
|
|
|
# Add an action
|
|
zapier-platform scaffold create contact
|
|
```
|
|
|
|
Find out more on the latest docs: https://docs.zapier.com/platform
|
|
|
|
# dynamic-dropdown
|
|
|
|
This example integration demonstrates how to create **dynamic dropdowns** (also known as dynamic choices) in Zapier integrations.
|
|
|
|
## Dynamic Dropdown Patterns
|
|
|
|
There are two ways to implement dynamic dropdowns:
|
|
|
|
### 1. Trigger-based (Legacy Pattern)
|
|
|
|
Uses a separate trigger to fetch choices. Reference it with the `dynamic` property:
|
|
|
|
```javascript
|
|
{
|
|
key: 'species_id',
|
|
type: 'integer',
|
|
label: 'Species',
|
|
dynamic: 'species.id.name', // Format: "triggerKey.idField.labelField"
|
|
}
|
|
```
|
|
|
|
The trigger (`species`) fetches data, and Zapier uses `id` for the value and `name` for the display label.
|
|
|
|
### 2. Perform-based (New Pattern)
|
|
|
|
Uses a function to fetch choices directly. Define it with `choices.perform`:
|
|
|
|
```javascript
|
|
{
|
|
key: 'planet_id',
|
|
type: 'integer',
|
|
label: 'Home Planet',
|
|
resource: 'planet', // Explicit resource linking (see below)
|
|
choices: {
|
|
perform: getPlanetChoices,
|
|
},
|
|
}
|
|
```
|
|
|
|
#### Resource Linking
|
|
|
|
The `resource` property explicitly links an input field to a resource. This is particularly important for perform-based dropdowns since they don't have a `dynamic` property to derive the resource from.
|
|
|
|
```javascript
|
|
{
|
|
key: 'spreadsheet_id',
|
|
resource: 'spreadsheet',
|
|
choices: { perform: getSpreadsheets },
|
|
}
|
|
```
|
|
|
|
The perform function must return:
|
|
|
|
```javascript
|
|
{
|
|
results: [
|
|
{ id: '1', label: 'Tatooine' },
|
|
{ id: '2', label: 'Alderaan' },
|
|
],
|
|
paging_token: 'https://api.example.com/planets?page=2', // or null if no more pages
|
|
}
|
|
```
|
|
|
|
#### Pagination Support
|
|
|
|
The perform function receives `bundle.meta.paging_token` for subsequent page requests:
|
|
|
|
```javascript
|
|
const getPlanetChoices = async (z, bundle) => {
|
|
// First request: paging_token is undefined
|
|
// Subsequent requests: paging_token is the value you returned previously
|
|
const url = bundle.meta.paging_token || 'https://api.example.com/planets';
|
|
|
|
const response = await z.request({ url });
|
|
|
|
return {
|
|
results: response.data.results.map((item) => ({
|
|
id: item.id,
|
|
label: item.name,
|
|
})),
|
|
// Return null when there are no more pages
|
|
paging_token: response.data.next,
|
|
};
|
|
};
|
|
```
|
|
|
|
## This Example
|
|
|
|
This integration uses the [Star Wars API](https://swapi.dev/) to demonstrate:
|
|
|
|
- **Species dropdown** - Trigger-based pattern using the `species` trigger
|
|
- **Planet dropdown** - Perform-based pattern with pagination and explicit `resource` linking
|
|
|
|
## Getting Started
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run tests
|
|
zapier-platform test
|
|
|
|
# Push to Zapier
|
|
zapier-platform push
|
|
```
|
|
|
|
Find out more on the latest docs: https://docs.zapier.com/platform
|