Oma toteutus soittolistalukijalle

Edistyneiden käyttäjien on mahdollista tehdä oma toteutus soittolistalukijalle. Tällöin voit itse luoda koko soittimen ulkoasun ja piilottaa oletuksena näkyvän soittimen. Soittimen toimintoja ohjataan JavaScriptillä lukijan tarjoaman API:n kautta.

Valmistelu

Ota soittolistalukija käyttöön normaalisti edellisen sivun ohjeen mukaan.

Kun soittolistalukija on otettu käyttöön, se luo automaattisesti namespacen window.AimPlaylist, jonka kautta lukijaa voi ohjata.

Soittolistalukijan saatavuus

Soittolistalukijan namespace on saatavilla vasta sen jälkeen, kun lukijan skripti on ladattu. Voit tarkastaa saatavuuden suoraan namespacen kautta tai kuuntelemalla eventiä 'AimPlaylist.ready'.

if (window.AimPlaylist?.ready) {
    // Soittolistalukija on käytettävissä
} else {
    window.addEventListener('AimPlaylist.ready', () => {
        // Soittolistalukija on käytettävissä
    }, { once: true });
}

Oletussoittimen piilotus

Kun luot itse soittolistalukijan ulkoasun, kannattaa oletussoitin piilottaa kokonaan näkyvistä. Voit piilottaa soittimen käyttämällä seuraavaa CSS-koodia.

.aim-playlist-host {
    display: none !important;
}

Monta soittolistaa

Jos sivustollasi on samanaikaisesti useita soittolistoja näkyvillä, voit tunnistaa soittolistat antamalla niille uniikin ID-arvon. ID-arvo määritetään data-aim-playlist-id-attribuutin avulla.

<div class="aim-playlist" data-aim-playlist-id="my-playlist-1">
    ...
</div>

<div class="aim-playlist" data-aim-playlist-id="my-playlist-2">
    ...
</div>

Voit tämän jälkeen käyttää ID-arvoa API:n metodeissa, jotka tukevat sitä. Voit esimerkiksi aloittaa toistamaan jälkimmäistä soittolistaa kutsumalla window.AimPlaylist.play('my-playlist-2').

API

Kun AimPlaylist namespace on saatavilla, seuraavat ominaisuudet ja funktiot ovat käytettävissä namespacen kautta, esimerkiksi window.AimPlaylist.play().

Ominaisuudet

Ominaisuus	Tyyppi	Kuvaus
ready	true, readonly	Onko AimPlaylist namespace valmis käyttöön.
speed	number	Lukijan toistonopeus välillä 0.5 - 4.0. Oletuksena 1.0. Voit vaihtaa nopeutta asettamalla tähän uuden arvon.
volume	number	Lukijan äänenvoimakkuus välillä 0.0 - 1.0. Oletuksena 1.0. Voit vaihtaa äänenvoimakkuutta asettamalla tähän uuden arvon.

Metodit

Metodi	Paluuarvo	Kuvaus
next(playlistId?: string)	Promise<void>	Siirtyy toistamaan seuraavaa lausetta. Promise valmistuu, kun seuraavan lauseen toisto on alkanut.
nextPlaylist()	Promise<void>	Siirtyy toistamaan seuraavaa soittolistaa. Promise valmistuu, kun seuraavan soittolistan toisto on alkanut.
nextPlaylistItem(playlistId?: string)	Promise<void>	Siirtyy toistamaan seuraavaa linkkiä soittolistasta. Promise valmistuu, kun seuraavan linkin toisto on alkanut.
pause()	void	Pysäyttää toiston. Toistoa voi jatkaa kutsumalla play() tai playPause().
play(playlistId?: string)	Promise<void>	Aloittaa toiston tai jatkaa pysäytettyä toistoa. Promise valmistuu, kun toisto on alkanut.
playPause(playlistId?: string)	Promise<void>	Vaihtaa toiston tilaa pysäytyksen ja toiston välillä. Promise valmistuu, kun toisto on alkanut.
previous(playlistId?: string)	Promise<void>	Siirtyy toistamaan edellistä lausetta. Promise valmistuu, kun edellisen lauseen toisto on alkanut.
previousPlaylist()	Promise<void>	Siirtyy toistamaan edellistä soittolistaa. Promise valmistuu, kun edellisen soittolistan toisto on alkanut.
previousPlaylistItem(playlistId?: string)	Promise<void>	Siirtyy toistamaan edellistä linkkiä soittolistasta. Promise valmistuu, kun edellisen linkin toisto on alkanut.
stop()	void	Pysäyttää toiston kokonaan ja poistaa linkkien korostuksen näkyvistä. Toistoa ei voi enää jatkaa samasta kohtaa, vaan ainoastaan aloittaa alusta.

Eventit

Soittolistalukija lähettää joitain eventejä, joita voit kuunnella window.addEventListener-funktion avulla. Eventin nimi on muotoa 'AimPlaylist.<event>', esimerkiksi 'AimPlaylist.loading'. Jos eventin mukana on dataa, löytyy se detail-avaimen alta. Datan mukana lähetetään myös playlistId, jolla voit tunnistaa mihin soittolistaan event liittyy.

Eventin nimi	Data	Kuvaus
'AimPlaylist.duration'	{ durationRemaining: number, playlistId: string, totalDuration: number }	Nykyisen linkin arvioitu kokonaiskesto ja jäljellä oleva kesto sekunteina. Tämä event lähetetään sekunnin välein tai aina, kun jokin kesto muuttuu. Käytetty toistonopeus vaikuttaa audion kestoon.
'AimPlaylist.error'	{ error: string | false, playlistId: string }	Lukijassa tapahtui jokin virhe. Mahdolliset error-arvot: - 'link-parsing-failed' - Linkin tekstisisältöä ei pystytty parsimaan. - 'server-error' - Palvelin ei vastaa normaalisti. - 'no-text-content-found' - Ei löytynyt tekstiä .aim-readable-elementeistä. - 'unknown-error' - Tuntematon virhe. - false - Edellinen virhetilanne on selvitetty.
'AimPlaylist.loading'	{ loading: boolean, playlistId: string }	Lukija alkaa lataamaan tai lopettaa lataamisen.
'AimPlaylist.playback'	{ action: 'play' | 'pause' | 'stop', playlistId: string, playlistItemIndex: number }	Toiston tila muuttui. action kertoo mitä tapahtui. playlistItemIndex kertoo mihin soittolistan linkkiin event liittyy.
'AimPlaylist.ready'	void	Lukijan tarjoama namespace window.AimPlaylist on valmis käyttöön.

Esimerkki

<html>
    <head>
        <!-- Load the playlist reader script -->
        <script src="https://portal.aimater.com/static/reader/playlist/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.js"></script>

        <script>
            /**
             * Enable the custom reader when the `AimPlaylist` namespace is ready.
             */
            function onAimPlaylistReady() {
                // Make your custom reader visible.
                const myCustomReader = document.getElementById('my-custom-playlist-reader');
                myCustomReader?.removeAttribute('hidden');

                // Show a loading icon when the reader is loading.
                const loadingIcon = document.getElementById('loading-icon');
                window.addEventListener(
                    'AimPlaylist.loading',
                    (event) => {
                        if (event.detail.loading) {
                            loadingIcon?.removeAttribute('hidden');
                        } else {
                            loadingIcon?.setAttribute('hidden', '');
                        }
                    },
                );

                // Show an error message if the reader encounters an error.
                const errorMessage = document.getElementById('error-message');
                window.addEventListener(
                    'AimPlaylist.error',
                    (event) => {
                        if (event.detail.error) {
                            errorMessage?.removeAttribute('hidden');
                        } else {
                            errorMessage?.setAttribute('hidden', '');
                        }
                    },
                );

                // Show the remaining duration of the current link.
                const durationElement = document.getElementById('duration');
                window.addEventListener(
                    'AimPlaylist.duration',
                    (event) => {
                        durationElement.innerHTML = `Kesto: ${event.detail.durationRemaining} s`;
                    },
                );

                // Set initial values for volume and speed inputs
                const volumeInput = document.getElementById('volume-input');
                const speedInput = document.getElementById('speed-input');
                if (volumeInput) {
                    volumeInput.value = window.AimPlaylist.volume;
                }
                if (speedInput) {
                    speedInput.value = window.AimPlaylist.speed;
                }
            }

            // Wait for the reader to be ready.
            if (window.AimPlaylist?.ready) {
                onAimPlaylistReady();
            } else {
                window.addEventListener(
                    'AimPlaylist.ready',
                    onAimPlaylistReady,
                    { once: true },
                );
            }
        </script>

        <style>
            /* Hide the default player. */
            .aim-playlist-host {
                display: none !important;
            }
        </style>
    </head>

    <body>
        <aside id="my-custom-playlist-reader" hidden>
            <div id="loading-icon" hidden></div>

            <div id="error-message" hidden>Tapahtui odottamaton virhe.</div>

            <button type="button" onclick="window.AimPlaylist.play()">Toista</button>
            <button type="button" onclick="window.AimPlaylist.pause()">Tauko</button>
            <button type="button" onclick="window.AimPlaylist.stop()">Lopeta</button>
            <button type="button" onclick="window.AimPlaylist.previousPlaylistItem()">Edellinen artikkeli</button>
            <button type="button" onclick="window.AimPlaylist.nextPlaylistItem()">Seuraava artikkeli</button>

            <label for="volume-input">Äänenvoimakkuus</label>
            <input
                id="volume-input" type="range"
                min="0" max="1" step="0.1"
                oninput="window.AimPlaylist.volume = this.value"
            />
            <label for="speed-input">Puhenopeus</label>
            <input
                id="speed-input" type="range"
                min="0.5" max="4" step="0.1"
                oninput="window.AimPlaylist.speed = this.value"
            />

            <div id="duration">Kesto: 0 s</div>
        </aside>

        <div class="aim-playlist">
            <a href="article-1">...</a>
            <a href="article-2">...</a>
            <a href="article-3">...</a>
            <a href="article-4">...</a>
        </div>
    </body>
</html>