Pomoc:Personalizacja - porady dla zaawansowanych

Skrypty ładowane domyślnie
Nazwa skórki	Podstrony
Nazwa skórki	JavaScript (.js)	Arkusz stylów (.css)
Globalne (na Meta)	global.js	global.css
Wszystkie skórki (lokalnie)	common.js	common.css
Wybrana skórka (przekierowanie)	skin.js	skin.css
Wektor 2022 (domyślna)	vector-2022.js	vector-2022.css
Wektor 2010	vector.js	vector.css
Minerva (mobilna)	minerva.js	minerva.css
Książka	monobook.js	monobook.css
Timeless	timeless.js	timeless.css

Na stronie Pomoc:Personalizacja opisano jakie możliwości daje oprogramowanie MediaWiki w dostosowywaniu Wikipedii do własnych potrzeb. Jak to wykorzystać? Najprostsze jest przejście na stronę Specjalna:Preferencje i ustawienie tam kilku opcji. Znacznie większe możliwości daje posiadanie własnego arkusza stylów (plik CSS), a przede wszystkim własnego JavaScriptu (plik JS).

Co dają zmiany w CSS? Najprościej może wytłumaczyć na przykładzie. Ten artykuł bez arkusza CSS wyglądałby mniej więcej tak: [1]. Nieco bardziej drastyczne przykłady przemiany można znaleźć na stronie css Zen Garden (ta sama strona bez CSS). Generalnie CSS pozwala na zmianę kolorów, krojów pisma oraz rozmiarów i pozycji różnych elementów (układu strony). Np. bez CSS menu widoczne po prawej znajdowałoby się pod artykułem, podobnie jak widoczne na górze zakładki. Bardziej zaawansowane właściwości pozwalają na dodawanie tekstu przed lub za wybranymi elementami.

A co dają zmiany w JS? Umożliwiają bardzo dużo. Można całkowicie skasować zawartość strony i wpisać dowolny tekst, a także stworzyć dowolne elementy jak np. tabelki czy formularze. Bardziej zaawansowane skrypty mogą też pobierać zawartość stron, których nie ma jeszcze w przeglądarce i przetwarzać ich zawartość (tak działa popups).

Ładowanie skryptów JS i stylów CSS

Własne skrypty najlepiej dzielić na osobne pliki. To znaczy na moduły, które realizują coś ciekawego 🙂. Takie skrypty trzeba będzie ładować osobno, ale w razie czego potem będzie łatwiej zrobić z nich gadżet.

Skrypty możesz ładować w:

Swoim common.css, albo common.js – tu załaduj uniwersalne skrypty, zalecane dla większości skryptów.
Swoim skin.css, albo skin.js – specyficzne dla Twojej skórki.

Linki znajdziesz powyżej. Zwróć uwagę, że linki przekierują cię na twoją stronę. A skin.js/css powinny przekierować na bieżącą skórkę (tą którą teraz masz włączoną).

Ładowanie CSS i JS z JS

Skrypty najlepiej ładować z common.js. Większość skryptów powinna być uniwersalna lub wykrywać której skórki używasz. Jeśli tak nie jest i skrypt jest dla konkretnej skórki (np. ciemny motyw skórki), to użyj zamiast tego skin.js.

Lokalne skrypty możesz ładować za pomocą uproszczonej składni:

// ładowanie CSS (z JS)
importStylesheet('User:Przykład/stylove.css');
importScript('User:Przykład/skryptlove.js');

Możesz też użyć bezpośrednio ładowania plików przez: mw.loader. Składnia wygląda następująco:

// Ładowanie CSS (zmień parametr `title` zależnie od tego jaki styl chcesz załadować).
// Zwróć uwagę, że dla CSS wymagane jest dodanie 'text/css'.
mw.loader.load( '/w/index.php?title=User:Przykład/stylove.css&action=raw&ctype=text/css', 'text/css' );

// Ładowanie JS (zmień parametr `title`, zależnie od tego jaki skrypt chcesz załadować)
mw.loader.load( '/w/index.php?title=User:Przykład/skryptlove.js&action=raw&ctype=text/javascript' );

Główną zaletą ładowania JS i CSS w jednym miejscu jest to, że łatwiej jest włączyć je jednocześnie.

Importowanie CSS poprzez CSS

Wyżej opisana jest metoda ładowania CSS z JS. Można jednak użyć składni @importów do ładowania CSS poprzez common.css, albo CSS wybranej skórki.

Przykład ładowanie:

/* [[Wikipedysta:Nux/personalizacja.js]] */
@import url("/w/index.php?action=raw&ctype=text/css&title=Wikipedysta:Przykład/stylove.css");

Na ten moment trudno uznać jedną z tych metoda za lepszą. Obie metody powodują, że skrypty skrypty i style ładują się wolniej niż gadżety. Docelowo uniwersalne skrypty powinny stać się gadżetami.

Inne metody wstrzykiwania JS i CSS

Skrypty można ładować również poza mechanizmami wiki. Za pomocą rozszerzeń Mediawiki.

Skrypty JS można załadować za Tampermonkey lub podobnych rozszerzeń, jednak do czasu załadowania strony można nie mieć dostępu do "mw" i innych obiektów. Z tego względu najlepiej użyć konfiguracji skryptu // @run-at document-end (dokumentacja run-at).

CSS z kolei można ładować za pomocą Stylusa lub Stylish (instalowane do przeglądarki). Tego typu style mogą działać nawet lepiej niż w gadżetach, ponieważ nie muszą być ładowane z zewnątrz. Ich wadą jest to, że działają tylko jednym urządzeniu.

Dodawanie linków do górnego paska

Załóżmy, że chcemy dodać sobie kilka linków do górnego paska (tego z linkiem do własnej strony, strony dyskusji, strony preferencji itd.). W tym celu należy dodać odpowiedni skrypt na swojej stronie .JS.

Poniższy skrypt dodaje link do tablic ogłoszeń:

jQuery( document ).ready( function() {
	var elBefore = document.getElementById( 'pt-mytalk' );

	var elNew = document.createElement( 'li' );
	elNew.innerHTML = '<a href="//pl.wiki.x.io/w/index.php?title=Wikipedia:Tablica_og%C5%82osze%C5%84">TO</a>';
	elBefore.parentNode.insertBefore( elNew, elBefore );
} );

Jak to działa? Dla większości osób pewnie wystarczy informacja, że po fragmencie "elNew.innerHTML=" można wpisać prawie dowolny kod HTML, podany w apostrofach i zakończyć średnikiem. Oczywiście należy też dodać następne linie kodu, żeby wszystko działało jak należy. To na co należy zwrócić szczególną uwagę, to kodowanie znaków (%XX%XX). Najlepiej po prostu przejść na daną stronę i skopiować link w całości.

Można też dodawać linki do konkretnych akcji. Na przykład link do historii tablicy ogłoszeń wstawia się tak:

jQuery( document ).ready( function() {
	var elBefore = document.getElementById( 'pt-mytalk' );

	var elNew = document.createElement( 'li' );
	elNew.innerHTML = '<a href="/w/index.php?title=Wikipedia:Tablica_og%C5%82osze%C5%84&action=history">historia TO</a>';
	elBefore.parentNode.insertBefore( elNew, elBefore );
} );

Kolejne linki można dodawać kopiując trzy kolejne linie kodu i je dodając pod spodem:

jQuery( document ).ready( function() {
	var elBefore = document.getElementById( 'pt-mytalk' );

	var elNew = document.createElement( 'li' );
	elNew.innerHTML = '<a href="//pl.wiki.x.io/w/index.php?title=Wikipedia:Tablica_og%C5%82osze%C5%84">TO</a>';
	elBefore.parentNode.insertBefore( elNew, elBefore );

	var elNew = document.createElement( 'li' );
	elNew.innerHTML = '<a href="/w/index.php?title=Wikipedia:Tablica_og%C5%82osze%C5%84&action=history">historia TO</a>';
	elBefore.parentNode.insertBefore( elNew, elBefore );
} );

Można też wpisać jeden po drugim (po spacji, nie po nowej linii!):

jQuery( document ).ready( function() {
	var elBefore = document.getElementById( 'pt-mytalk' );

	var elNew = document.createElement( 'li' );
	elNew.innerHTML = '<a href="//pl.wiki.x.io/w/index.php?title=Wikipedia:Tablica_og%C5%82osze%C5%84">TO</a> <a href="/w/index.php?title=Wikipedia:Tablica_og%C5%82osze%C5%84&action=history">historia TO</a>';
	elBefore.parentNode.insertBefore( elNew, elBefore );
} );

Tworzenie własnych narzędzi

Tworzenie własnych narzędzi zależy wyłącznie od własnej fantazji i czasu. Można wstawić sobie jakiś element, który będzie kontrolował jakieś zachowania – chowanie któregoś z elementów, tworzenie/pokazywanie jakiegoś formularza itp.

Dobry styl programowania

Główne zasady:

Wszystkie zmienne powinny zostać zadeklarowane przy użyciu słowa kluczowego var.
Wszystkie funkcje powinny zwracać wartość, jeśli w ogóle zwracają ją w jakimś miejscu.

Przykład 1

źle

el = document.getElementById( 'pt-mytalk' );

dobrze

var el = document.getElementById( 'pt-mytalk' );

Przykład 2

źle

function waliduj() {
	if ( document.getElementById( 'form_field' ).value == '' ) {
		alert( 'Pole puste' );
		return false;
	}
}

prawie dobrze

function waliduj() {
	if ( document.getElementById( 'form_field' ).value == '' ) {
		alert( 'Pole puste' );
		return false;
	}
	return true;
}

Dlaczego „prawie dobrze”? Bo powyższy kod będzie błędny, jeśli zostanie wykonany, gdy element o id „form_field” nie będzie istniał. Dlatego lepiej byłoby użyć czegoś takiego:

function waliduj() {
	var el = document.getElementById( 'form_field' );
	if ( el && el.value == '' ) {
		alert( 'Pole puste' );
		return false;
	}
	return true;
}

Z drugiej strony zależy to od sytuacji – jeśli sprawdzamy konkretny formularz, który zawsze zawiera to pole, to pole zawsze będzie istniało. W takiej sytuacji w funkcji inicjującej wystarczy sprawdzić, czy istnieje ten formularz.

Hooks czyli punkty zaczepienia

Istnieją pewne gotowe zmienne i funkcje w MediaWiki, które nieco ułatwiają tworzenie skryptów. Podstawową funkcją jest tutaj: jQuery(document).ready(), przyjmująca jako parametr nazwę funkcji, która ma być wywołana po załadowaniu całej strony. To jeden z istotnych punktów zaczepienia skryptów. Definiujesz swoją funkcję i uruchamiasz ją strona jest gotowa. To działa w przypadku stałych elementów znajdujących się na stronie od razu. Może np. dodać tak linki do górnego paska (opisane wyżej).

Innym przypadkiem jest oczekiwanie na załadowanie jakiegoś komponentu. Np. edytora wizualnego (ang. VE), który ładuje się jeszcze chwilę po załadowaniu strony lub w ogóle dopiero po kliknięciu przycisku przez użytkownika. Oczekiwanie na inny komponent ułatwi obiekt mw.hook (ang. hook – „zaczep”)^[1]. Przykład wykonania kodu po załadowaniu VE:

mw.hook('ve.activationComplete').add(function () {
	// VE się załadował, uruchom mój skrypt (np. dodaj przyciski)
	initMojegoSkryptu();
});

Dużo przykładów rozszerzania funkcji VE znajdziesz na mw:VisualEditor/Gadgets#Code snippets.

Warto zauważyć, że hooki wykonują się nawet gdy dane zdarzenie już się wydarzyło. To znaczy jeśli VE jest już załadowany i wykonasz powyższy kod, to on się wykona. To bardzo dobre, bo dzięki temu nie musisz się przejmować kiedy załaduje się twój kod^[1].

Własne hooki

Oprócz hooków wbudowanych już w oprogramowanie Wikipedii możesz dodać własne punkty zaczepienia. Dzięki temu może pozwolić użytkownikom wprowadzenie mniejszych i większych modyfikacji. Przykład praktyczny znajdziesz w Wikipedia:Narzędzia/veAutocorrect#Własne sekwencje, albo: Wikiprojekt:Sprzątanie kodu#Własny skrypt. Zasadniczo sprowadza się to wykonania mw.hook('…nazwa…').fire(…parametry…); w twoim kodzie. Istnieje konwencja by nazwy zaczepów gadżetów zaczynały się od „userjs.” np.:

// przed inicjowaniem możesz dodać hook, żeby użytkownicy mogli dostosować opcje
mw.hook('userjs.mojskrypt.preinit').fire();
// gdy skrypt jest w pełni gotowy to możesz np. przekazać cały obiekt do użycia:
mw.hook('userjs.mojskrypt.ready').fire(mojskrypt);
// albo możesz przekazać konkretną funkcję, czy jakąś zmienną, która normalnie nie jest widoczna
mw.hook('userjs.mojskrypt.ready').fire(mojskrypt.mojaFunkcja, mojaZmienna);

Jeśli używałaś(-eś) Node.js to .fire(parametr) jest poniekąd odpowiednikiem eksportowania zmiennych z modułów.

Konfiguracja MW

Ważnym aspektem jest odczyt konfiguracji MediaWiki. Dzięki temu można sprawdzić nazwę użytkownika, skórkę itp. Odczyt konfiguracji może pozwolić by skrypt był bardziej uniwersalny.

Podstawowa konfiguracja dostępna przez MediaWiki:

// pobieranie wartości:
mw.config.get(key)
// np. to zwróci "/w"
mw.config.get('wgScriptPath')

// różne wartości:
{
	'skin': "monobook",
	'stylepath': "/skins-1.5",
	'wgArticlePath': "/wiki/$1",
	'wgScriptPath': "/w",
	'wgServer': "//pl.wiki.x.io",
	'wgCanonicalNamespace': "User", // nazwa przestrzeni nazw, zawsze po angielsku
	'wgCanonicalSpecialPageName': false,
	'wgNamespaceNumber': 2, // numer przestrzeni nazw
	'wgPageName': "Wikipedysta:Nux/pomysły",
	'wgTitle': "Nux/pomysły",
	'wgArticleId': "494711",
	'wgAction': "view", // akcja dla bieżącej strony (edit, submit, history itp)
	'wgUserName': "Nux",
	'wgUserGroups': ["sysop", "*", "user", "autoconfirmed", "emailconfirmed"], // null jeśli niezalogowany
	'wgUserLanguage': "pl",      // język wybrany przez zalogowaną osobę
	'wgContentLanguage': "pl",   // ogólne dla serwisu (en.wiki=en, de.wiki=de)
	'wgCurRevisionId': "6868099",
}

Wszystkie dostępne wartości dla danej strony możesz sprawdzić w konsoli JS:

console.log(mw.config.values)

Jak testować skrypty?

Najprościej skorzystać DevTools wbudowanych w przeglądarkę^[2]^[3]. DevToolsy umożliwiają wszechstronne testowanie skryptów JS oraz arkuszy stylów. Firefox posiada też konsolę JS, którą można rozwinąć (na początku jest jednolinijkowa) i wpisać praktycznie dowolną ilość kodu i uruchomić. Można też edytować wybrane fragmenty kodu HTML oraz CSS.

Ostatecznym sprawdzianem powinno być zawsze zainstalowanie skryptu w swoim JS-ie (np. przy użyciu {{JS}}) i przetestowanie w przynajmniej w Firefox oraz w Chrome (lub innej przeglądarce opartej na Chromium). Potem wystarczy tylko stworzyć choćby krótką instrukcję na podstronie Wikipedia:Narzędzia i dopisać się do tabelki.

Zobacz też

Wikipedia:Narzędzia#Tworzenie gadżetów – narzędzia dla twórców gadżetów, programistek i programistów JS itp.
Pomoc:Personalizacja – ogólniejsze porady.
meta:Help:User style – informacje o tworzeniu własnego CSS i przykłady rozszerzeń użytkowników.
Esej o pisaniu rozszerzeń, Nux, 2023.

Przypisy

↑ ^a ^b mw.hook, [w:] ResourceLoader/Core modules - MediaWiki, www.mediawiki.org [dostęp 2023-01-06] (ang.).
↑ Chrome DevTools
↑ Firefox DevTools

Linki zewnętrzne

[:0-1] mw.hook, [w:] ResourceLoader/Core modules - MediaWiki, www.mediawiki.org [dostęp 2023-01-06] (ang.).

[2] Chrome DevTools

[3] Firefox DevTools

[1]

[2]

[3]