Wikiźródła:Narzędzia/gConfig

gConfig to menedżer ustawień dla gadżetów. Koniec z modyfikowaniem common.js!

Dla użytkowników

Ustawienia gadżetów wykorzystujących gConfig można zmienić na nowej stronie specjalnej Specjalna:GadgetPrefs, linkowanej także na górze sekcji Gadżetów w zwykłych Preferencjach oraz pod ikonką koła zębatego przy opisach poszczególnych gadżetów. Wyświetlany jest na niej formularz pozwalający zmienić dowolne ustawienia włączonych gadżetów.

gConfig włącza się automatycznie, gdy wybierzesz jeden z wykorzystujących go gadżetów.

Ustawienia są zapisywane w preferencjach użytkownika (przy użyciu tego samego mechanizmu, z którego korzysta Specjalna:Preferencje) oraz w ciasteczkach.

Przykładowe gadżety wykorzystujące gConfig (lista może być niepełna):

• disFixer

Dla deweloperów

Aby dodać swój gadżet (lub skrypt niebędący gadżetem) do gConfiga:

1. otocz całość skryptu w blok mw.loader.using('ext.gadget.gConfig', function(){ ... }) (aby upewnić się, że gConfig załaduje się, zanim spróbujemy go użyć)
2. na początku kodu (wewnątrz tego bloku, ale poza $(document).ready / addOnloadHook itp.) użyj funkcji gConfig.register, aby zarejestrować listę obsługiwanych ustawień (patrz poniżej)
3. w kodzie za każdym razem, gdy chcesz odczytać ustawienie, użyj gConfig.get (patrz poniżej)

Przykład: zmiany wprowadzone w gadżecie disFixer przystosowujące go do gConfiga.

Poza opisanymi poniżej funkcjami gadżet udostępnia także kilka innych funkcji i zmiennych, które raczej nie będą potrzebne. Są opisane w komentarzach w kodzie gadżetu (po angielsku).

gConfig.register

Pozwala zarejestrować listę obsługiwanych przez dany gadżet ustawień. Przyjmuje trzy argumenty:

• gadget: identyfikator gadżetu, wykorzystywany do rozpoznawania powiązanych ciasteczek i preferencji MediaWiki. Dopuszczalne tylko litery ASCII, cyfry i podkreślnik. Zwykle uproszczona nazwa gadżetu.
• gadgetInfo: obiekt zawierający podstawowe informacje o gadżecie:
  • name [wymagane]: nazwa gadżetu wyświetlana w nagłówku sekcji w preferencjach gadżetów,
  • descriptionPage: nazwa strony z opisem gadżetu (do niej będzie linkować ww. nagłówek).
• settings: lista opcji konfiguracyjnych. Każda z opcji to obiekt o poniższych kluczach:
  • name [wymagane]: identyfikator ustawienia, nie pokazywany w interfejsie
  • desc [wymagane]: opis ustawienia, wyświetlany na stronie preferencji
  • descMode: zawartość opisu: plain / wikitext (domyślnie plain)
  • type [wymagane]: typ wartości: boolean / integer / numeric / string, każdy typ jest inaczej wyświetlany w pref. i walidowany
  • deflt [wymagane]: domyślna wartość
  • validation: sposób walidacji wprowadzonych danych. Jedno z:
    • tablica [min, max]: zakres dopuszczalnych wartości dla typów integer i numeric
    • funkcja function(value){ ... }: funkcja sprawdzająca poprawność wartości. Jako jedyny parametr przekazana zostanie wprowadzona przez użytkownika wartość. Jeśli jest nieprawidłowa, funkcja musi użyć throw, aby zwrócić informację o błędzie, która zostanie wyświetlona obok opisu danego ustawienia. Funkcja musi zwrócić prawidłową wartość dla danego ustawienia (może modyfikować przekazaną jej zmienną).
  • legacy: dla ułatwienia migracji obecnych skryptów na gConfig, pozwala "zaimportować" wartość z ustawień wpisywanych do pliku JS. Jeśli odnajdzie takie ustawienie, na stronie preferencji nie będzie ono modyfikowalne, a użytkownik otrzyma informację, jak zrobić, aby było (usunąć z *.js). Jedno z:
    • tablica [object, property]: wartość zostanie wczytana z wyrażenia object[property], jeśli jest ono zdefiniowane. object to najczęście po prostu window (czyli: operujemy na zmiennej globalnych o nazwie property)
    • obiekt: jak wyżej, wartość dla property będzie taka sama, jak identyfikator ustawienia name

Przydługi przykład:

gConfig.register(
  'lipsum',
  {
    name: 'Lorem ipsum gadget',
    descriptionPage: 'Wikipedia:Lorem ipsum gadget'
  },
  [
    {
      name: 'boolean',
      desc: 'Boolean value.',
      type: 'boolean',
      deflt: true
    }, {
      name: 'integer',
      desc: 'Integral number between 0 and 30.',
      type: 'integer',
      deflt: 20,
      validation: [0, 30]
    }, {
      name: 'float',
      desc: '[[Floating-point number]] between -1 and 1.',
      descMode: 'wikitext',
      type: 'numeric',
      deflt: 0.5,
      validation: [-1, 1]
    }, {
      name: 'string',
      desc: 'Text value.',
      type: 'string',
      deflt: 'test'
    }, {
      name: 'evenonly-passive',
      desc: 'Even numbers only. Will be rounded down if an odd number is given.',
      type: 'integer',
      deflt: 0,
      validation: function(n){ return n%2!=0 ? n-1 : n; }
    }, {
      name: 'evenonly-agressive',
      desc: 'Even numbers only. Will prevent saving if an odd number is given.',
      type: 'integer',
      deflt: 0,
      validation: function(n){ if(n%2!=0){ throw 'Requires an even number!' }; return n; }
    }
  ]
);

gConfig.get

Zwraca wartość dla danego ustawienia danego gadżetu. Przyjmuje dwa argumenty:

• gadget: identyfikator gadżetu, jak w gConfig.register.
• setting: nazwa ustawienia, jak name w gConfig.register.