Listings
Listings: titled collections of items (cards, directory entries) shown on a page. Reading is public; changing needs the signed-in portal session.
Quick start
const result = await window.Portal.listings.fetchListing('LISTING_ID');
result.items.forEach((item) => console.log(item.title));API reference
window.Portal.listings
Listings. Reading (fetchListings, fetchListing) is public; everything that creates, changes or deletes needs the signed-in portal session, so a public page uses only the reads.
createOrUpdateListing()
Creates a listing, or updates the one whose listing_id is given (signed in).
const listing = await window.Portal.listings.createOrUpdateListing(listing);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listing | Partial<PortalListing> | Yes | A listing: a titled collection of items (cards, directory entries) shown on a page. |
Returns
Resolves with a PortalListing: A listing: a titled collection of items (cards, directory entries) shown on a page.
createOrUpdateListingItem()
Creates or updates an item (signed in).
const listingItem = await window.Portal.listings.createOrUpdateListingItem(listingId, item);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
item | Partial<PortalListingItem> | Yes | One item of a listing. |
Returns
Resolves with a PortalListingItem: One item of a listing.
deleteListing()
Deletes a listing (signed in).
const ok = await window.Portal.listings.deleteListing(listingId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
Returns
Resolves with a boolean.
deleteListingItem()
Deletes an item (signed in).
const ok = await window.Portal.listings.deleteListingItem(listingId, itemId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
itemId | string | Yes | — |
Returns
Resolves with a boolean.
fetchListing()
One listing with its items.
const result = await window.Portal.listings.fetchListing(listingId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
listing | PortalListing | Yes | — |
items | PortalListingItem[] | Yes | — |
fetchListingItems()
The items of a listing.
const listingItems = await window.Portal.listings.fetchListingItems(listingId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
Returns
Resolves with an array of PortalListingItem.
fetchListingOutput()
The rendered markup of a listing.
const listingOutput = await window.Portal.listings.fetchListingOutput(listingId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
Returns
Resolves with a PortalListingOutput: A listing's rendered markup.
fetchListings()
All listings.
const listings = await window.Portal.listings.fetchListings();Returns
Resolves with an array of PortalListing.
saveListingOutput()
Stores the rendered markup of a listing (signed in).
const ok = await window.Portal.listings.saveListingOutput(listingId, html, name);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listingId | string | Yes | The listing's id. |
html | string | Yes | — |
name | string | null | No | The name. |
Returns
Resolves with a boolean.
uploadListingImage()
Uploads an image for a listing item; app is the portal's application object (portal pages only).
const result = await window.Portal.listings.uploadListingImage(file, app);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
file | File | Yes | The file. |
app | unknown | Yes | Uploads an image for a listing item; app is the portal's application object (portal pages only). |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | An address. |
generated_name | string | Yes | — |
Types
PortalListing
A listing: a titled collection of items (cards, directory entries) shown on a page.
| Name | Type | Required | Description |
|---|---|---|---|
listing_id | string | Yes | The listing's id. |
name | string | Yes | The listing's name. |
internal_id | string | Yes | The owner's own id for the listing. |
style_variant | string | Yes | The visual style. |
details_page_enabled | boolean | Yes | Whether each item has a details page. |
config | PortalListingConfig | Yes | Display settings. |
created_at | string | No | ISO creation time. |
updated_at | string | No | ISO update time. |
PortalListingConfig
A listing's display settings.
| Name | Type | Required | Description |
|---|---|---|---|
style_variant | string | Yes | The visual style of the listing. |
details_page_enabled | boolean | Yes | Whether each item has its own details page. |
[key: string] | unknown | No | Further fields the server may add. |
PortalListingItem
One item of a listing.
| Name | Type | Required | Description |
|---|---|---|---|
listing_item_id | string | Yes | The item's id. |
listing_id | string | Yes | The listing it belongs to. |
title | string | Yes | The item's title. |
description | string | Yes | The item's description. |
images | string[] | Yes | Image addresses. |
details_title | string | No | Heading of the item's details page. |
details_content | string | No | Body of the item's details page. |
details_url | string | No | Link to the details page. |
sort_order | number | No | Position in the listing (lowest first). |
config | Record<string, unknown> | No | Item display settings. |
created_at | string | No | ISO creation time. |
updated_at | string | No | ISO update time. |
PortalListingOutput
A listing's rendered markup.
| Name | Type | Required | Description |
|---|---|---|---|
listing_id | string | Yes | The listing. |
typeaction | number | Yes | Internal output type code. |
html | string | Yes | The HTML of the listing. |
name | string | null | No | The output's name, if any. |