1. Podgląd WOMI z repozytorium treści Podgląd WOMI dla deweloperów zdalnych Wymagania dotyczące tworzenia silników przez partnerów...

Transkrypt

1 1. Podgląd WOMI z repozytorium treści Podgląd WOMI dla deweloperów zdalnych Wymagania dotyczące tworzenia silników przez partnerów Opis paczek z zadaniami licenses.json manifest.json metadata.json Opis szkieletu interaktywnych WOMI

2 Podgląd WOMI z repozytorium treści Podgląd WOMI z repozytorium treści jest możliwy za pomocą odpowiednich adresów. Wg tabelki (Znaczenie zmiennych wg Skrócona nomenklatura wykorzystywana w dokumentacji) wzorzec znaczenie przykład w/womi/<subdomain>/<womi-id> załadowanie podglądu WOMI o identyfikatorze <womi-id> z subdomeny <subdomain> gdzie subdomena oznacza nic innego jak adres skąd serwowane są pliki z repozytorium czyli np.: w/womi/preview/5303 Podgląd WOMI dla deweloperów zdalnych Wstęp Dla deweloperów zewnętrznych dostępny jest podgląd WOMI, który potrafi załadować treści z lokalnego serwera Do konfiguracji tego trybu potrzebne są: dostęp do deweloperskich wersji portalu np: beta.epodreczniki.pl osobny serwer hostujący pliki z WOMI do podglądu, może to być np.: nginx, python SimpleHTTPServer Konfiguracja serwera statycznego Na serwerze statycznym należy utworzyć katalog (zaczynając od głównej ścieżki): /content/womi W tym katalogu będą umieszczane odpowiednie foldery identyfikujące poszczególne WOMI np.: /content/womi/1234 katalog z WOMI musi zawierać odpowiednią strukturę WOMI, przede wszystkim minimalny plik manifest.json, np: "engine": "ge_animation", "version": "1.0", "mainfile": "womi.js", "parameters": "object": "heightratio": Konfiguracja pliku "hosts": należy dodać regułę: local_content.beta.epodreczniki.pl przy czym "local_content" możemy zastąpić prawie dowolną nazwą (poza zarezerwowanymi dla epodrecznikowych subdomen) Serwer statyczny musi serwować zasoby z odpowiednimi nagłówkami, co najmniej: 1. Access-Control-Allow-Headers: origin, content-type, accept, x-requested-with 2. Access-Control-Allow-Methods: GET, HEAD, OPTIONS 3. Access-Control-Allow-Origin: * Uruchomienie

3 wzorzec znaczenie przykład w/womi/<subdomain>:<port>/<womi-i d> załadowanie podglądu WOMI o identyfikatorze <womi-id> z subdomeny <subdomain> gdzie subdomena oznacza subdomenę, którą zdefiniowaliśmy powyżej, a <port> zawiera port serwera statycznego dodatkowo: parametr zapytania forces chema pozwala na to by ustawić scheme dla subdomeny na http lub https, przyjmowane wartości: ssl - zawsze ustawi dla subdomeny https plain - zawsze http parametr superscript pozwala załadować dodatkowy skrypt do podglądu przed wczytaniem womi, należy podać ścieżkę na lokalnym serwerze, może być to w głównym katalogu wtedy np:?superscript=skrypt.js ew/womi/local_content:8002/1234 UWAGA Z racji tego, że beta dostępna jest po https, najpewniej należy używać parametru forceschema=plain, a także zezwolić przeglądarce na ładowanie "niebezpiecznego" contentu. Wymagania dotyczące tworzenia silników przez partnerów Opis paczek z zadaniami Opis szkieletu interaktywnych WOMI Silniki WOMI ładowane jako html'e do IFRAME Tworzenie WOMI jako proste strony HTML, ładujące JavaScript i zarządzające DOMem we własny sposób. Wymagania: można używać dowolnych bibliotek, jedynie wymagających konsultacji drobnej z nami, gdyż wszystkie biblioteki będziemy trzymać u nas na serwerze można dowolnie operować dokumentem w ramach iframe, lecz trzeba zapewnić responsywność elementów (czyli dostosowywanie do rozmiarów iframe) jeżeli WOMI ma być animacją/grą/czymś podobnym należy w opisie womi podać wymiary, a właściwie ratio (opisane tu: Obsługa alternatyw i przełączanie pomiędzy wersjami WOMI#Obiektinteraktywny) jeżeli WOMI jest raczej czymś w postaci zadania czyli następujących po sobie tekstów i nie do końca można określić rozmiar, należy wywołać przygotowane przez nas skrypty (uprzednio załączone w tymże htmlu) by zawołać zmianę rozmiaru Przeszkody do rozpatrzenia: zagnieżdżone WOMI (problem z łańcuchowym wołaniem i przetwarzaniem WOMI typu geogebra i inne interaktywne WOMI (mniej problemu z obrazkami, audio i wideo chyba)) mogą wystąpić problemy z komunikacją zagnieżdżonych WOMI z kontekstem

4 mogą wystąpić problemy z komunikacją zagnieżdżonych WOMI z kontekstem Silniki WOMI ładowane dynamicznie na stronie czytnika Silniki (JS) implementujące kilka wspólnych metod(interfejs), które zostaną wczytane jako obiekt JS po rozpoznaniu WOMI. Następnie na tym obiekcie zostanie wywołana funkcja startująca z pewnymi parametrami, potrzebnymi silnikowi. Kwestia parametrów do ustalenia, ale w ogólności rozważamy: bezwzględny URL do zasobów WOMI odpowiednie klucze typu: WOMI ID, COLLECTION ID, MODULE ID (do przemyślenia) url do pliku JSON, zawierającego specyficzną konfigurację dla tego silnika (wymagane przetworzenie przez silnik) węzeł DOM jako uchwyt - głównych kontener(div) do którego będzie silnik generował swój kontent Wymagania: tworzone silniki muszą implementować nasz interfejs wykorzystywać niektóre narzucone metody naszego interfejsu wykorzystywać prawie dowolne silniki, ale nie do końca: silniki muszą być u nas na serwerze i być odpowiednio opakowane, leczy tym ostatecznie zajmiemy się my po konsultacjach z partnerem przede wszystkim, jeżeli chodzi o jquery i pluginy, tutaj niektóre mogą być dołączane, a niektóre ładowane razem z czytnikiem będą dostępne w wersjach takich jakie MY mamy ładowanie pluginów, może odbywać się jedynie poprzez nasze api NIE WOLNO modyfikować elementów znajdujących się ponad węzłem, który jest uchwytem Możliwości: zręczne korzystanie z API czytnika możliwość ładowania WOMI w WOMI zbieżność z kompozycją strony Opis paczek z zadaniami WOMI - opis paczki index.html (plik ze struktura WOMI) womi.js (główny plik JavaScript, moduł require.js) (zamiennie index.html z womi.js, zależy od typu przygotowanego WOMI) manifest.json (informacje o WOMI, nazwa i wersja silnika używanego przez WOMI) metadata.json (metadane z AR) main.json (konfiguracja dla silnika WOMI z parametrami inicjalizującymi zadanie) folder: config na pliki konfiguracyjne licenses.json (plik opisujacy licencje obiektow multimedialnych uzytych w paczce) folder: js (źródła JavaScript) dowolnie zaprojektowana struktura katalogów folder: css (pliki ze stylami CSS) dowolnie zaprojektowana struktura katalogów folder: media (pliki multimedialne wykorzystywane przez WOMI) dowolnie zaprojektowana struktura katalogów folder: alternatives (cztery alternatywy dla WOMI ) folder: CLASSIC (obrazek klasyczny) folder: MOBILE (obrazek mobilny) folder: PDF (obrazek pdf) folder: EPUB (obrazek epub) licenses.json

5 licenses.json "filename" : "media/sample.jpg", "title" : "Przykładowy opis pliku sample.jpg", "author" : "Jan Kowalski", "license" : "CC BY 4.0" "filename" : "media/audio/dzwiek.mp3", "title" : "Przykładowy opis pliku dzwiek.mp3", "author" : "Piotr Nowak", "license" : "CC BY SA 2.0" Lista możliwych wartości dla pola "license": CC BY 1.0 CC BY 2.0 CC BY 2.5 CC BY 3.0 CC BY 4.0 CC BY SA 1.0 CC BY SA 2.0 CC BY SA 2.5 CC BY SA 3.0 CC BY SA 4.0 manifest.json "engine": "womi_exercise_engine", "version": "0.1", "mainfile": "main.json", "womiids": [123,456,2222], "parameters": "classic": "heightratio": 0.54, "mobile": "heightratio": 0.51, "pdf":

6 "pdf": "resolution": [1440], "heightratio": 0.56, "ebook": "resolution": [800], "heightratio": 0.57, "engine": "custom_womi", "version": "0.1", "mainfile": "womi.js", "womiids": [500,501], "parameters": "classic": "heightratio": 0.54, "mobile": "heightratio": 0.51, "pdf": "resolution": [1440], "heightratio": 0.56, "ebook": "resolution": [800], "heightratio": 0.57, "engine": "swiffy", "version": "6.0", "mainfile": "swiffy.html", "parameters": "object": "heightratio": 0.54 "classic": "heightratio": 0.54,

7 "mobile": "heightratio": 0.51, "pdf": "resolution": [1440], "heightratio": 0.56, "ebook": "resolution": [800], "heightratio": 0.57, "engine": "geogebra", "version": " ", "mainfile": "geogebra.html", "parameters": "object": "heightratio": 0.54 "classic": "heightratio": 0.54, "mobile": "heightratio": 0.51, "pdf": "resolution": [1440], "heightratio": 0.56, "ebook": "resolution": [800], "heightratio": 0.57, "engine": "image", "parameters":

8 "parameters": "classic": "heightratio": 0.54, "mobile": "heightratio": 0.51, "pdf": "resolution": [1440], "heightratio": 0.56, "ebook": "resolution": [800], "heightratio": 0.57, "engine": "icon", "parameters": "classic": "heightratio": 0.54, "mobile": "heightratio": 0.51, "pdf": "heightratio": 0.56, "ebook": "heightratio": 0.57,

9 metadata.json "title": "title from metadata", "author": "author from metadata", "alternativetext": "alternative text fro mmetadata", "license": "cc3", "keywords": [123,456,2222] Opis szkieletu interaktywnych WOMI Przedwstępnie Należy przygotować środowisko wg instrukcji: Podgląd WOMI dla deweloperów zdalnych Wprowadzenie Mając na uwadze różne podejścia partnerów co do tworzenia gier/animacji interaktywnych w technologii JavaScript, chcemy uspójnić interfejs oraz przedstawić szablon tworzenia skryptów. Przyjęcie przez wszystkich naszej konwencji pozwoli na ujednolicenie interfejsu i wyeliminuje problemy związane z ładowaniem dodatkowych bibliotek w różny sposób. Opis paczki Paczka zip zawiera niezbędne, testowe środowisko do uruchomienia skryptów w naszej konwencji. Jest to wycinek naszego czytnika, zapisany poniekąd w sposób statyczny (pliki przegenerowane niewymagające backendu). Opis kluczowych plików/ścieżek znajduje się poniżej. static/3rdparty/epo/custom_lib1/lib1.js - przykładowa biblioteka, element wspólny dla danego partnera, dostarczany przez niego static/repository/content/womi/womi przykładowe WOMI zawierające szkielet interaktywnego WOMI, według którego należy tworzyć przyszłe WOMI inne pliki, nieistotne z punktu widzenia tworzącego aplikację, wymagane jedynie uruchomienie jakiegoś prostego serwera http w katalogu główny (tam gdzie index.html) Paczka zawiera przykładowe womi oraz kilka wymaganych bibliotek, które są odpowiednikiem tych na serwerach (z racji konfiguracji środowiska nie można ich pobierać bezpośrednio z serwera tak jak innych plików). Wprowadzenie do technologi Szkielet aplikacyjny opiera się w głównej mierze na bibliotece require.js. Pozwala ona na bardzo modularne podejście, przede wszystkim, "opakowanie" części kodu w niezależne (lub zależne) moduły, mogą być one w osobnych plikach poprzez odpowiednie mieszczenie ich w funkcji nadrzędnej. System importowania zależności modułów w innym module zapobiega problemom związanym z niezaładowaniem się modułu/biblioteki przed wykorzystaniem. W większości specyficznych ustawień/konfiguracji, partner tworzący moduły nie musi znać tajników biblioteki. Najważniejsze rzeczy zostaną opisane poniżej, niemniej jednak zalecane jest zapoznanie się z podstawami na oficjalnej stronie: js.org/.

10 Struktura głównego pliku JavaScript dla WOMI Plik ten jest napisany w konwencji requirejs i zawiera: nadrzędne wywołanie funkcji define, która rejestruje to co zwraca funkcja podana w drugim parametrze jako moduł pierwszy parametr funkcji jest to lista zależnych modułów, bibliotek, które mają zostać załadowane przed wykonaniem tego modułu parametry funkcji przekazywane jako drugi parametr define, są to kolejne uchwyty do załadowanych bibliotek (wg kolejności, podania ich w zależnościach), mogą być one użyte dalej w ciele funkcji (modułu) atrybuty nowo utworzonego modułu: isavatar: aby WOMI stało się avatarem, musi być dołączone jako przypinka, a klasa główna musi mieć właściwość isavatar o wartości true enablemaximize: aby womi uruchomiło się w kontenerze na całym ekranie (po kliknięciu w obraz zastępczy), wartość tego parametru musi być ustawiona na true moduł (czyli ta funkcja) powinna zwracać istotne dla nas (czytnika) informacje czyli "klasę" zawierającą metodę start metoda start: zawiera parametry: placeholder, będzie do niego przekazany główny węzeł DOM, do którego będzie można dopisywać nowe elementy wg uznania options, obiekt posiadający opcje z którymi zostaje odpalony moduł: width height methods: gdy moduł nie posiada zdefiniowanego parametru enablemaximize lub false, dostępne są metody: openfullscreen() i closefullscreen() gdy enablemaximize == true, zdefiniowana jest tylko jedna metoda: closewomi(), która zamyka całe womi i wraca do stanu pierwotnego isfullscreen: parametr mówiący o tym czy womi zostało odpalone w opcji pełnoekranowej, (zawsze false przy enablemaximize) metoda clean: OPCJONALNA metoda zwalniająca zasoby itp metoda sizechange: OPCJONALNA metoda, która dostaje jako parametry: width i height kontenera nadrzędnego, może słuzyć do podpięcia się na zdarzenie zmiany rozmiaru (metoda zostanie wywołana przed uruchomieniem metody start, a później za każdym razem gdy dojdzie do zmiany rozmiaru kontenera należy pamiętać by zwracać prototyp funkcji (w paradygmacie obiektowym - klasę), który może być później zinstancjonowany biblioteka declare.js ( ) pomaga w tworzeniu klas, ale można to zrobić także tradycyjnymi sposobami Wyjaśnienie zaimportowanych modłów 'jquery' - pozwala używać jquery wewnątrz modułu 'declare' - opisana wyżej biblioteka 'epo.custom_lib1.lib1' - nazwa przykładowej biblioteki/modułu, dostarczonego przez partnera i odpowiednio zmapowanego (nazwanego) przez nas 'reader.api' - moduł zawierający API czytnika, pozwalające wykonywać niezbędne zadania podczas ładowania i przetwarzania własnych modułów './js/costam.js' - moduł JavaScript znajdujący się wewnątrz folderu z WOMI, przykład pokazuje, że nie trzeba wszystkiego trzymać w jednym pliku 'require' - załadowanie instancji biblioteki require w kontekście bieżącego modułu (zastosowanie opisane dalej) Opis 'reader.api' API ma na celu dostarczyć funkcjonalność pozwalającą na integrację gier/aplikacji z platformą. Zestaw funkcjonalności będzie rozszerzany sukcesywnie razem z wymaganiami. By zainicjować nowy obiekt API w kontekście danego modułu, należy wykonać var readerapi = new api(require); następnie można używać poniższych metod (relatywna ścieżka zaczyna sie od./):

11 następnie można używać poniższych metod (relatywna ścieżka zaczyna sie od./): metoda parametry opis getfullpath path metoda przyjmuje relatywną ścieżkę względem aktualnego modułu (pliku js) z katalogu WOMI, i zwraca pełną ścieżkę loadcss path metoda ładuje plik CSS z relatywnej ścieżki setuservar varname, value ustawienie zmiennej wykorzystywanej przez aplikację (w kontekście użytkownika, kolekcji, modułu i womi) (zapisuje do bazy danych)#aktualnie to co local getuservar varname pobranie zmiennej ustawionej powyższą metodą (zapisuje do bazy danych)#aktualnie to co local setlocaluservar varname, value ustawienie zmiennej wykorzystywanej przez aplikację (w kontekście użytkownika, kolekcji, modułu i womi) (zapisuje do localstarage) getlocaluservar varname pobranie zmiennej ustawionej powyższą metodą (zapisuje do localstorage) getcontext zwraca obiekt z parametrami: variant: wariant podręcznika isteacher: czy użytkownik jest nauczycielem metody do ustawiania zmiennych jak na razie są jedynie makietami i nie zapisują ich w faktycznym kontekście w bazie danych. Można ich używać do testowania bo są zapisywane w w zmiennych javascript. By używać API w kontekście okna w iframe, należy do pliku html dodać następujący skrypt: <script src="/global/libraries/epo/frame_script.js"></script> Opis 'reader.avatar.api' Api pozwalające na komunikację womi z awatarem. Api opiera się na modelu zdarzeniowym. metoda parametry opis trigger eventname, value wysyła powiadomienie do awatara o zajściu zdarzenia, parametr 'value' może być obiektem listen eventname, callback do implementacji w womi awatar, odbiera zdarzenie, przetwarzanie przez funkcję 'callback', która dostaje jako parametr 'value' z metody trigger Aby WOMI stało się avatarem, musi być dołączone jako przypinka, a klasa główna musi mieć właściwość isavatar o wartości tru e.

12 WAŻNE Awatar ma wielkość kwadratu o boku 25% wysokości strony. Opis 'reader.communication.api' Api pozwalające na komunikację womi z innymi womi. Api opiera się na modelu zdarzeniowym. metoda parametry opis trigger eventname, value wysyła powiadomienie do pozostałych womi o zajściu zdarzenia, parametr 'value' może być obiektem listen eventname, callback odbiera zdarzenie, przetwarzanie przez funkcję 'callback', która dostaje jako parametr 'value' z metody trigger nazwa zdarzenia jest kluczem do tego by dwa konkretne womi skomunikowały się Dostępne biblioteki w ramach dostarczonej paczki dostępne są biblioteki do użytku: 'jquery' - bibliteka jquery 'jqueryui' - dodatek do biblioteki jquery - mechanizmy interfejsu użytkownika 'declare' - biblitoeka declarejs 'underscore' - biblioteka underscore.js 'backbone' - biblioteka Backbone.js 'domready' - plugin require.js do wywoływania zdarzeń po załadowaniu DOM 'text' - plugin require.js do importowania tekstu biblioteki createjs: zgodnie z oczekiwaniami partnerów udostępniamy spakowane wersje bibliotek, są to spakowane źródła createjs i movieclip w odpowiednich wersjach wg: code.createjs.com/ poniżej przedstawiono listę mapowań requirejs dla tych bibliotek, należy używać konkretnego movieclip tylko z konkretną biblioteką createjs (jeśli potrzebne): 'epo.createjs ' oraz 'epo.createjs.movieclip.0.6.0' 'epo.createjs ' oraz 'epo.createjs.movieclip.0.6.1' 'epo.createjs ' oraz 'epo.createjs.movieclip.0.7.0' 'epo.createjs ' oraz 'epo.createjs.movieclip.0.7.1' Używanie bibliotek partnerskich w htmlach, załączanych przez iframe w womi By używać własnych bibliotek w osobnych htmlach, należy paczkę z odpowiednią strukturą przesłać do PCSS, z nazwą kluczową dla partnera jako główny folder. dostęp do nich będzie następujący: /global/libraries/<nazwa>/<ścieżka> np dla pliku, który dla twórcy jest pod ścieżką relatywną: js/script.js i nazwą partnera: partner1

13 <script src="/global/libraries/partner1/js/script.js"></script> Pliki konfiguracyjne WOMI Dla poprawnego działania WOMI w podglądzie, należy przygotować pliki: manifest.json oraz metadata.json Manifest powinien być skonfigurowany tak by zapewniał możliwość odpalenia womi wg określonych potrzeb (silnik, rozmiar), plik metadata natomiast możę być zaczerpnięty z przykładowej paczki, nie ma znaczenia co się w nim znajduje (oczywiście powinien być wg szablonu), ale nie może być wrzucony do repozytorium tresci. Szablon pliku manifest.json "engine": "custom_womi", "mainfile": "womi.js", "version": "1.0", "parameters": "object": "heightratio": 0.54 Szablon pliku metadata.json "author": "test", "title": "Testy funkcjonalności", "keywords": "brak", "license": "test", "alternativetext": "Testowanie funkcjonalności" Lista dostępnych silników: edge_animation: dla animacji ze środowiska Adobe Edge createjs_animation: animacje CreateJS ge_animation: animacje Grupy Edukacyjnej custom_womi: szablonowe generyczne womi, opisywane wyżej custom_logic_exercise_womi: podobne do custom_womi, pozwala tworzyć womi, które nie mają rozmiaru, mogą też ładować same z siebie inne womi i tworzyć fragmenty treści, w większości api opisano tutaj: ~jaftowicz/dokumentacja/epo.api.placeholderapi.html ace_editor: silnik dla edytora Ace svg_editor: silnik dla edytora SVG Edit geogebra: womi typu geogebra swiffy: womi typu swiffy

14 Link do paczki paczkav5.zip