...
[?]
```
## Controls Reference
| Control id | Tab → Section | Type | Purpose |
| --- | --- | --- | --- |
| `eael_instafeed_access_token` | Content → Settings | TEXT | Instagram Graph access token |
| `eael_instafeed_data_cache_limit` | Content → Settings | NUMBER | Cache TTL (hours) |
| Layout | Content → Layout | SELECT | Grid / masonry / carousel |
| Columns | Content → Layout | NUMBER | Grid columns (1–6) |
| Items per page | Content → Layout | NUMBER | Initial item count |
| Load more | Content → Layout | SWITCHER | Enable pagination |
| Show caption / hover overlay | Content → Display | SWITCHER | Visibility toggles |
## Conditional Dependencies
```text
load_more = 'yes'
└── shows load-more button + uses pagination
└── enqueues Lite's load-more CSS via config.php Lite-path entry
layout = 'carousel'
└── shows carousel-specific controls (autoplay, arrows, dots)
```
## JavaScript Lifecycle
`src/js/view/instagram-gallery.js`:
```js
var InstaFeedHandler = function( $scope, $ ) {
var $wrap = $scope.find( '.eael-instafeed-gallery-wrap' );
var layout = $wrap.data( 'layout' );
if ( layout === 'masonry' ) {
// Init Isotope
} else if ( layout === 'carousel' ) {
// Init Swiper
}
// Load-more click handler — AJAX to a Lite endpoint that calls back into the trait's get_instagram_data
};
```
## Hooks & Filters
### Elementor hooks consumed
Standard widget render. No extension-style hooks.
### Pro / EA hooks emitted
None visible.
### AJAX endpoints
Load-more goes through Lite's standard `wp_ajax_eael_load_more` handler. Pro's contribution is in the trait's data getter. Verify the integration point when editing.
## Common Issues
| Symptom | Likely cause | Diagnose | Fix |
| --- | --- | --- | --- |
| "No items" / blank gallery | Access token expired (Instagram tokens expire every 60 days) | Check `wp_remote_get` response for 401 | User re-issues token at Instagram developer console |
| Items stale after Instagram post | Transient cache TTL not yet elapsed | Check cache key in DB | Reduce TTL or manually delete transient |
| Slow page render | N+2 API calls hit per refresh | Network: many `graph.instagram.com` requests | Increase cache TTL; reduce media count |
| Access token visible in page source | Token concatenated into image URLs by Instagram | View source — `access_token=...` in image URL | Document for users — this is Instagram's URL design, not a Pro bug |
| Load more fetches duplicates | `paging.next` URL not stripping already-shown IDs | Inspect AJAX response | Track shown IDs client-side; dedupe on append |
## Known Limitations
- **N+2 API calls** for N media items per cache refresh — high quota burn on free tier
- **Access token in URL** is Instagram-API design; cannot be passed via header. Mitigation: short cache TTL = more refreshes = more leaks
- **Token stored plaintext in post meta** — same risk as Mailchimp / Google Sheets
- **Token expiry not auto-handled** — refresh-token rotation not visible in Pro code. Tokens expire after ~60 days; user must manually re-issue
- **No fallback to stale cache on API failure** — if Instagram returns 500 / 4xx, the gallery renders empty
- **No retry / backoff** on Graph API errors
- **No timeouts** on `wp_remote_get` — uses WP default 5s. Slow Instagram response stalls render
## Cross-References
- Architecture: [`docs/architecture/external-api-integrations.md`](../architecture/external-api-integrations.md) — Instagram surface
- Shared patterns: [`_patterns.md`](_patterns.md) — External-API widget pattern
- Rule: [`.claude/rules/external-api-integrations.md`](../../.claude/rules/external-api-integrations.md)