@panoramax/web-viewer
Version:
Panoramax web viewer for geolocated pictures
310 lines (236 loc) • 15.6 kB
Markdown
<a name="Panoramax.components.core.PhotoViewer"></a>
## Panoramax.components.core.PhotoViewer ⇐ [<code>Basic</code>](Basic.md/#Panoramax.components.core.Basic)
**Kind**: static class of <code>Panoramax.components.core</code>
**Extends**: [<code>Basic</code>](Basic.md/#Panoramax.components.core.Basic)
**Emits**: [<code>select</code>](Basic.md/#Panoramax.components.core.Basic+event_select), [<code>ready</code>](Basic.md/#Panoramax.components.core.Basic+event_ready), [<code>broken</code>](Basic.md/#Panoramax.components.core.Basic+event_broken)
**Element**: pnx-photo-viewer
**Slot**: `top-left` The top-left corner
**Slot**: `top` The top middle corner
**Slot**: `top-right` The top-right corner
**Slot**: `bottom-left` The bottom-left corner
**Slot**: `bottom` The bottom middle corner
**Slot**: `bottom-right` The bottom-right corner
**Slot**: `editors` External links to map editors, or any tool that may be helpful. Defaults to OSM tools (iD & JOSM).
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| loader | [<code>Loader</code>](../ui/Loader.md/#Panoramax.components.ui.Loader) | The loader screen |
| api | [<code>API</code>](../../utils/API.md/#Panoramax.utils.API) | The API manager |
| psv | [<code>Photo</code>](../ui/Photo.md/#Panoramax.components.ui.Photo) | The Photo Sphere Viewer component itself |
| grid | [<code>CorneredGrid</code>](../layout/CorneredGrid.md/#Panoramax.components.layout.CorneredGrid) | The grid layout manager |
| popup | [<code>Popup</code>](../ui/Popup.md/#Panoramax.components.ui.Popup) | The popup container |
| urlHandler | [<code>URLHandler</code>](../../utils/URLHandler.md/#Panoramax.utils.URLHandler) | The URL query parameters manager |
| presetsManager | [<code>PresetsManager</code>](../../utils/PresetsManager.md/#Panoramax.utils.PresetsManager) | The semantics presets manager |
* [.PhotoViewer](#Panoramax.components.core.PhotoViewer) ⇐ [<code>Basic</code>](Basic.md/#Panoramax.components.core.Basic)
* [new PhotoViewer()](#new_Panoramax.components.core.PhotoViewer_new)
* [.properties](#Panoramax.components.core.PhotoViewer+properties) : <code>Object</code>
* [.onceReady()](#Panoramax.components.core.PhotoViewer+onceReady) ⇒ <code>Promise</code>
* [.oncePSVReady()](#Panoramax.components.core.PhotoViewer+oncePSVReady) ⇒ <code>Promise</code>
* [.onceFirstPicLoaded()](#Panoramax.components.core.PhotoViewer+onceFirstPicLoaded) ⇒ <code>Promise</code>
* [.setPopup(visible, [content])](#Panoramax.components.core.PhotoViewer+setPopup)
* [.moveCenter()](#Panoramax.components.core.PhotoViewer+moveCenter)
* [.moveLeft()](#Panoramax.components.core.PhotoViewer+moveLeft)
* [.moveRight()](#Panoramax.components.core.PhotoViewer+moveRight)
* [.moveUp()](#Panoramax.components.core.PhotoViewer+moveUp)
* [.moveDown()](#Panoramax.components.core.PhotoViewer+moveDown)
* [.addEventListener(type, listener, [options])](#Panoramax.components.core.PhotoViewer+addEventListener)
* [.onceAPIReady()](Basic.md/#Panoramax.components.core.Basic+onceAPIReady) ⇒ <code>Promise</code>
* [.getClassName()](Basic.md/#Panoramax.components.core.Basic+getClassName) ⇒ <code>string</code>
* [.select([seqId], [picId], [force])](#Panoramax.components.core.Basic+select)
* [.isWidthSmall()](Basic.md/#Panoramax.components.core.Basic+isWidthSmall) ⇒ <code>boolean</code>
* [.isHeightSmall()](Basic.md/#Panoramax.components.core.Basic+isHeightSmall) ⇒ <code>boolean</code>
* [.getSubComponentsNames()](Basic.md/#Panoramax.components.core.Basic+getSubComponentsNames) ⇒ <code>Array.<string></code>
* ["menu-opened"](Basic.md/#Panoramax.components.core.Basic+event_menu-opened)
* ["select"](Basic.md/#Panoramax.components.core.Basic+event_select)
* ["ready"](Basic.md/#Panoramax.components.core.Basic+event_ready)
* ["broken"](Basic.md/#Panoramax.components.core.Basic+event_broken)
<a name="new_Panoramax.components.core.PhotoViewer_new"></a>
### new PhotoViewer()
Photo Viewer is a component showing pictures (without any map).
This component has a [CorneredGrid](../layout/CorneredGrid.md/#Panoramax.components.layout.CorneredGrid) layout, you can use directly any slot element to pass custom widgets.
If you need a viewer with map, checkout [Viewer component](Viewer.md/#Panoramax.components.core.Viewer).
Make sure to set width/height through CSS for proper display.
**Example**
```html
<!-- Basic example -->
<pnx-photo-viewer
endpoint="https://panoramax.openstreetmap.fr/"
style="width: 300px; height: 250px"
/>
<!-- With slotted widgets -->
<pnx-photo-viewer
endpoint="https://panoramax.openstreetmap.fr/"
style="width: 300px; height: 250px"
>
<p slot="top-right">My custom text</p>
<p slot="editors"><a href="https://my.own.tool/">Edit in my own tool</a></p>
</pnx-photo-viewer>
<!-- With only your custom widgets -->
<pnx-photo-viewer
endpoint="https://panoramax.openstreetmap.fr/"
style="width: 300px; height: 250px"
widgets="false"
>
<p slot="top-right">My custom text</p>
</pnx-photo-viewer>
```
<a name="Panoramax.components.core.PhotoViewer+properties"></a>
### photoViewer.properties : <code>Object</code>
Component properties. All of [Basic properties](Basic.md/#Panoramax.components.core.Basic+properties) are available as well.
**Kind**: instance property of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Mixes**: [<code>properties</code>](Basic.md/#Panoramax.components.core.Basic+properties)
**Overrides**: [<code>properties</code>](Basic.md/#Panoramax.components.core.Basic+properties)
**Properties**
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| endpoint | <code>string</code> | | URL to API to use (must be a [STAC API](https://github.com/radiantearth/stac-api-spec/blob/main/overview.md)) |
| [psv] | <code>object</code> | | [Any option to pass to Photo component](../ui/Photo.md/#Panoramax.components.ui.Photo) as an object.<br />Example: `psv="{'transitionDuration': 500, 'picturesNavigation': 'pic'}"` |
| [widgets] | <code>string</code> | <code>true</code> | Use default set of widgets ? Set to false to avoid any widget to show up, and use slots to populate as you like. |
| [picture] | <code>string</code> | | The picture ID to display |
| [sequence] | <code>string</code> | | The sequence ID of the picture displayed |
| [fetchOptions] | <code>object</code> | | Set custom options for fetch calls made against API ([same syntax as fetch options parameter](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters)) |
| [lang] | <code>string</code> | | To override language used for labels. Defaults to using user's preferred languages. |
| [url-parameters] | <code>string</code> | <code>true</code> | Should the component add and update URL query parameters to save viewer state ? |
| [keyboard-shortcuts] | <code>string</code> | <code>true</code> | Should keyboard shortcuts be enabled ? Set to "false" to fully disable any keyboard shortcuts. |
<a name="Panoramax.components.core.PhotoViewer+onceReady"></a>
### photoViewer.onceReady() ⇒ <code>Promise</code>
Waits for PhotoViewer to be completely ready (map & PSV loaded, first picture also if one is wanted)
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Overrides**: [<code>onceReady</code>](Basic.md/#Panoramax.components.core.Basic+onceReady)
**Returns**: <code>Promise</code> - When viewer is ready
<a name="Panoramax.components.core.PhotoViewer+oncePSVReady"></a>
### photoViewer.oncePSVReady() ⇒ <code>Promise</code>
Waiting for Photo Sphere Viewer to be available.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Returns**: <code>Promise</code> - When PSV is ready to use
<a name="Panoramax.components.core.PhotoViewer+onceFirstPicLoaded"></a>
### photoViewer.onceFirstPicLoaded() ⇒ <code>Promise</code>
Waits for first picture to display on PSV.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Fulfil**: <code>undefined</code> When picture is shown
<a name="Panoramax.components.core.PhotoViewer+setPopup"></a>
### photoViewer.setPopup(visible, [content])
Change full-page popup visibility and content
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| visible | <code>boolean</code> | | True to make it appear |
| [content] | <code>string</code> \| <code>Array.<Element></code> | <code>null</code> | The new popup content |
<a name="Panoramax.components.core.PhotoViewer+moveCenter"></a>
### photoViewer.moveCenter()
Move the view of main component to its center.
For map, center view on selected picture.
For picture, center view on image center.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
<a name="Panoramax.components.core.PhotoViewer+moveLeft"></a>
### photoViewer.moveLeft()
Moves the view of main component slightly to the left.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
<a name="Panoramax.components.core.PhotoViewer+moveRight"></a>
### photoViewer.moveRight()
Moves the view of main component slightly to the right.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
<a name="Panoramax.components.core.PhotoViewer+moveUp"></a>
### photoViewer.moveUp()
Moves the view of main component slightly to the top.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
<a name="Panoramax.components.core.PhotoViewer+moveDown"></a>
### photoViewer.moveDown()
Moves the view of main component slightly to the bottom.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
<a name="Panoramax.components.core.PhotoViewer+addEventListener"></a>
### photoViewer.addEventListener(type, listener, [options])
Listen to events from this components or one of its sub-components.
For example, you can listen to `psv` events using prefix `psv:`.
```js
me.addEventListener("psv:picture-loading", doSomething);
```
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Overrides**: [<code>addEventListener</code>](Basic.md/#Panoramax.components.core.Basic+addEventListener)
| Param | Type | Description |
| --- | --- | --- |
| type | <code>string</code> | The event type to listen for |
| listener | <code>function</code> | The event handler |
| [options] | <code>object</code> | [Any original addEventListener available options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options) |
<a name="Panoramax.components.core.Basic+onceAPIReady"></a>
### photoViewer.onceAPIReady() ⇒ <code>Promise</code>
Waits for initial API setup.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Fulfil**: <code>null</code> When API is ready.
**Reject**: <code>string</code> Error message
<a name="Panoramax.components.core.Basic+getClassName"></a>
### photoViewer.getClassName() ⇒ <code>string</code>
This allows to retrieve an always correct class name.
This is crap, but avoids issues with Webpack & so on.
Each inheriting class must override this method.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Returns**: <code>string</code> - The class name (for example "Basic")
<a name="Panoramax.components.core.Basic+select"></a>
### photoViewer.select([seqId], [picId], [force])
Change the currently picture and/or sequence.
Calling the method without parameters unselects.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [seqId] | <code>string</code> | <code>null</code> | The sequence UUID |
| [picId] | <code>string</code> | <code>null</code> | The picture UUID |
| [force] | <code>boolean</code> | <code>false</code> | Force select even if already selected |
<a name="Panoramax.components.core.Basic+isWidthSmall"></a>
### photoViewer.isWidthSmall() ⇒ <code>boolean</code>
Is the view running in a small container (small embed or smartphone)
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Returns**: <code>boolean</code> - True if container is small
<a name="Panoramax.components.core.Basic+isHeightSmall"></a>
### photoViewer.isHeightSmall() ⇒ <code>boolean</code>
Is the view running in a small-height container (small embed or smartphone)
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Returns**: <code>boolean</code> - True if container height is small
<a name="Panoramax.components.core.Basic+getSubComponentsNames"></a>
### photoViewer.getSubComponentsNames() ⇒ <code>Array.<string></code>
List names of sub-components (like loader, api, map, psv) available in this component.
**Kind**: instance method of [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Returns**: <code>Array.<string></code> - Sub-components names.
<a name="Panoramax.components.core.Basic+event_menu-opened"></a>
### "menu-opened"
Event for overlaying menu opening
**Kind**: event emitted by [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| detail.menu | <code>Element</code> | The opened menu |
<a name="Panoramax.components.core.Basic+event_select"></a>
### "select"
Event for sequence/picture selection
**Kind**: event emitted by [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| detail.seqId | <code>string</code> | The selected sequence ID |
| detail.picId | <code>string</code> | The selected picture ID (or null if not a precise picture clicked) |
| [detail.prevSeqId] | <code>string</code> | The previously selected sequence ID (or null if none) |
| [detail.prevPicId] | <code>string</code> | The previously selected picture ID (or null if none) |
<a name="Panoramax.components.core.Basic+event_ready"></a>
### "ready"
Event when component is ready to use.
This happens when loader screen disappear, with picture and map loaded.
To follow more precisely loading steps, you can also watch for sub-components `ready` events.
```js
// Watch API-readiness
viewer.addEventListener("api:ready", ...); // From parent
viewer.api.addEventListener("ready", ...); // Or on sub-component
```
**Kind**: event emitted by [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
<a name="Panoramax.components.core.Basic+event_broken"></a>
### "broken"
Event for viewer failing to initially load.
To follow more precisely loading failures, you can also watch for sub-components `broken` events.
```js
// Watch API breaks
viewer.addEventListener("api:broken", ...); // From parent
viewer.api.addEventListener("broken", ...); // Or on sub-component
```
**Kind**: event emitted by [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| detail.error | <code>string</code> | The user-friendly error message to display |