Wikipedia:Narzędzia/lib-wikiprojects

lib-wikiprojects to biblioteka, która służy do pobierania i przetwarzania listy wikiprojektów, tak aby wszystkie gadżety korzystały z jednolitego parsera, udostępniającego im wymaganą funkcjonalność.

getWikiprojects

Biblioteka udostępnia jedną funkcję: gadget.getWikiprojects(options), której opcjonalny argument pozwala dostosować zwracane projekty. Argument options może być obiektem, którego klucze to nazwy parametrów.

Dostępne opcje

• maxCacheAge – wiek pamięci podręcznej w dniach, powyżej którego zostanie podjęta próba odświeżenia danych (domyślnie: 7)
• skipInactive – czy podczas listowania projektów pominąć nieaktywne (domyślnie: true)
• skipInstitutional – czy podczas listowania projektów pominąć instytucjonalne (domyślnie: false)
• skipSpecial – czy podczas listowania projektów pominąć specjalne (domyślnie: true)
• includeGadgets – lista napisów; jeśli gadżet jest oznaczony dowolnym z tych napisów, zostanie zawarty w wyniku, nawet jeśli inne filtry spowodowałyby odrzucenie go (domyślnie: [])

Typ zwracany

Funkcja wykonywana jest asynchronicznie. Zwraca obiekt typu jQuery.Promise, który rozwiązuje się do obiektu typu WikiprojectsResponse, który zawiera pola ageInDays i wikiprojects. Przechowują one, jak dawno pobrano listę (może przekroczyć maxCacheAge) oraz właściwą listę. Dostępne właściwości obiektu typu Wikiproject można znaleźć u dołu kodu biblioteki. Wszystkie pola opcjonalne są wypełniane wartościami ustalonymi na podstawie innych pól.

Pamięć podręczna

Biblioteka korzysta z pamięci podręcznej (localStorage) przeglądarki, aby ograniczyć ilość danych, wymienianych przez sieć. Dane są przechowywane pod kluczem wikiprojects.list, wraz z datą ich pobrania oraz wersją formatu listy.

Jeśli wiek zapamiętanych danych nie przekracza wartości parametru maxCacheAge, to nie zostanie wykonane zapytanie do serwera, ale bezwarunkowo zwrócona zostanie lista z pamięci podręcznej. W przeciwnym wypadku – kiedy lista zostanie przez skrypt uznana za przeterminowaną – biblioteka próbuje pobrać świeższą kopię danych z serwera. Jeśli się to nie powiedzie, mimo wszystko zwrócona zostanie lista obecna w pamięci podręcznej.

Aby wymusić przeładowanie danych, należy ręcznie usunąć wpis z local storage. Dostępna jest również możliwość unieważnienia zapisanych danych u wszystkich użytkowników, poprzez podniesienie aktualnej wersji formatu listy, tj. stałej WIKIPROJECTS_LIST_VERSION.