ansible/portal-plugin-sdk¶
Shared frontend web library for Portal contributors. Source:
workspaces/portal-core/plugins/portal-plugin-sdk.
Reusable functionality¶
- Page headers, dialogs, empty states, links, and loading components.
- Notification stack and synchronization polling utilities.
- Pagination, cache, and subscription utilities.
- Context/authorization hooks, icons, styles, and theme utilities.
The SDK is not a host page plugin and does not register native contributions. Use portal-extension-api for Blueprint declarations and portal-extension-host for host rendering.
Styling and ownership¶
PageHeader renders a title, optional description/help tooltip, and optional
consumer-supplied actions. It has no authentication or synchronization
requirements. The consumer owns UI permission checks and action handlers, while
backend authorization remains mandatory for protected operations.
Portal-scaffolder composes this layout through its local CatalogSyncHeader for
catalog synchronization. The SDK's sync-aware PageHeaderSection and its props
remain available as deprecated compatibility exports. Existing callers continue
to work. New consumers should use PageHeader, and legacy callers should migrate
before a separately coordinated removal. No removal version is scheduled.
EmptyStateView renders a title with optional description, decorative icon, and
consumer-owned actions. It requires no catalog, authentication, configuration, or
sync APIs. Plugins choose their own wording and control action visibility and
handlers. Backend authorization remains independent of UI presentation.
Portal-scaffolder keeps collection-specific behavior in its local
CollectionsEmptyState wrapper. Repository details uses EmptyStateView directly
with repository-specific missing-data guidance. The SDK's older EmptyState and
EmptyStateProps remain deprecated compatibility exports, without a scheduled
removal. Migrate consumers before a separately coordinated removal.
Prefer shared components and theme-adaptive tokens over importing private RHDH UI implementation details. Synchronization/cache integration uses injected callbacks rather than direct imports of a content plugin.
Authenticated context¶
usePortalContext() discovers portal-operations and reads its authenticated
GET /context endpoint. It returns organizationIds, an optional
organizationId, userEntityRef, loading, and error. A single unambiguous
membership supplies organizationId; multiple memberships do not select one.
Resolution failures leave an empty membership list, not a default fallback.
Use this context for display. Do not infer AAP membership from the user's catalog namespace or use browser-supplied organization values as backend authority. Registered operations receive only subject and input; the backend independently resolves memberships, grants and permissions.
See design tokens and the implementation guide for the remaining content-client and picker boundary.