Jump to content

확장기능:가젯

From mediawiki.org
This page is a translated version of the page Extension:Gadgets and the translation is 19% complete.
Outdated translations are marked like this.
This extension comes with MediaWiki 1.18 and above. 따라서 다시 다운로드하지 않아도 됩니다. 하지만 여전히 제공되는 별개의 지침을 따라야 합니다.
미디어위키 확장 기능 설명서
Gadgets
출시 상태: 안정
구현 MyWiki , 특수 문서 , API
설명 사용자가 그들의 설정(preferences) 페이지에서 JS 기반 사용자 제공 가젯을 활성화하도록 허용합니다.
만든 이 Daniel Kinzler (Duesentrieb토론)
호환성 정책 스냅샷은 미디어위키와 함께 릴리스됩니다. Master is not backward compatible.
MediaWiki 1.19+
라이선스 GNU General Public License 2.0 or later
다운로드
README
예제 위키미디어 공용 : Gadget overview, user preferences ("Gadgets" 을 클릭합니다; 물론 로그인 상태이어야 합니다)
  • $wgGadgetsRepo
  • $wgSpecialGadgetUsageActiveUsers
Quarterly downloads 139 (Ranked 40th)
Public wikis using 4,529 (Ranked 177th)
Gadgets 확장 기능 번역 (translatewiki.net에서 가능한 경우)
이슈 미해결 작업 · 버그 보고

가젯 확장은 사용자가 다른 위키 사용자가 제공한 자바스크립트 또는 CSS 기반의 "가젯"을 선택할 수 있는 방법을 제공합니다.

가젯은 미디어위키 네임스페이스의 페이지에 있는 자바스크립트 및/또는 CSS 스니펫 으로 구성됩니다. 각 가젯은 MediaWiki:Gadgets-definition에 가젯의 이름과 설명, 사용하는 JS 및 CSS 스니펫 목록을 제공하는 행으로 정의됩니다(아래 사용법 섹션 참조).

가젯은 미디어위키 네임스페이스(가젯을 정의하는 목록과 실제 코드 조각)에 있기 때문에 sysops(1.32의 인터페이스 관리자)만 코드를 편집할 수 있습니다. 이런 방식으로 동작되어야 합니다: JavaScript는 계정을 가로채거나 사람을 염탐하는 데 쉽게 사용될 수 있기 때문에 위키 커뮤니티에서 특별히 신뢰하는 사용자만 다른 사용자가 사용하는 JavaScript 코드를 편집할 수 있어야 합니다.

설치

  • 파일을 다운로드하고 Gadgets 폴더를 extensions/ 디렉토리에 넣어 주세요.
    개발자와 코딩 기여자는 Git을 이용해 확장기능을 다운받는 것이 좋습니다.cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
  • 아래의 코드를 LocalSettings.php 코드의 마지막에 추가합니다.
    wfLoadExtension( 'Gadgets' );
    
  • Yes 완료 – 위키의 ‘Special:Version’에 이동해서, 확장기능이 올바르게 설치된 것을 확인합니다.

사용법

de.wikipedia의 사용자 기본 설정에서 일부 가젯 선택한 이미지

하나 이상의 유효한 가젯으로 생성되면 거기에 정의된 가젯이 Special:Preferences의 "가젯" 섹션에 표시되므로 사용자는 사용하려는 가젯을 선택할 수 있습니다. MediaWiki:Gadgets-definition에 의해 정의된 가젯의 개요는 쉽게 편집할 수 있도록 해당 시스템 메시지에 대한 링크와 함께 Special:Gadgets에도 표시됩니다. 기본이 아닌 가젯 사용에 대한 통계는 Special:GadgetUsage에서 볼 수 있습니다.

형식

하나 이상의 "*" (asterisks) 문자로 시작하는 MediaWiki:Gadgets-definition에 있는 각 라인은 가젯을 정의한다; 다음과 같은 형식을 따라야 한다:

* mygadget [options (생략 가능)] | 페이지 이름

첫 번째 필드(예제에서 "mygadget")는 가젯의 내부 이름이며 Wiki 구문을 사용하여 가젯에 대한 간단한 설명이 포함된 시스템 메시지(예제에서 MediaWiki:Gadget-mygadget)를 참조합니다.

이는 기본 라틴 문자([A-Za-z])로 시작해야 하며 그 뒤에 임의의 수의 문자, 숫자([0-9]), 하이픈(-), 밑줄(_), 콜론($5) 및 마침표(.)가 올 수 있다는 것을 의미합니다. 내부 이름은 양식 필드 이름의 일부로 사용되며 [NAME 속성 값에 대해 정의된 https://www.w3.org/TR/html4/types.html#type-id 규칙]을 따라야 합니다.

옵션 형식:

[ResourceLoader | 옵션1 | 옵션2 | ... 옵션N]

The ResourceLoader flag is required unless the gadget contains only styles. Options that are "flags" only need to have their name written to be turned on. 단일 옵션은 단일 옵션 이름(이 경우 플래그 옵션임)으로 구성되거나 쉼표로 구분된 값 목록을 포함할 수 있습니다: 공백은 생략할 수 있습니다.

[ResourceLoader | myflag | mykey = value1, value2, value3 ]

예시:

* mygadget[ResourceLoader]|mygadget.js|mygadget.css

또는

* mygadget[ResourceLoader|package]| mygadget.js | mygadget-Foo.js | mygadget-data.json | mygadget.css

또는

* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css

가젯 정의 네임스페이스 사용하기
미디어위키 버전:
1.41
$wgGadgetsRepoClass에 따라 가젯을 정의하는 두가지 방법이 있습니다.

'MediaWikiGadgetsDefinitionRepo'(기본값) 이라면, 사용가능한 가젯의 리스트는 MediaWiki:Gadgets-definition로부터 정의됩니다. 또는 $wgGadgetsRepoClass'GadgetDefinitionNamespaceRepo'으로 설정된 경우 가젯 정의 네임스페이스의 페이지에서 가젯 정의가 정의됩니다. (On MediaWiki 1.39+, the value to use instead is '\\MediaWiki\\Extension\\Gadgets\\GadgetDefinitionNamespaceRepo'.)

기존 가젯 정의의 마이그레이션은 아직 지원되지 않으므로 이 옵션을 변경하면 이전에 정의한 가젯을 잃게 됩니다.

Gadget definition:mygadget 페이지를 생성하고 아래에 JSON 코드를 넣으면 mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css와 같은 효과를 냅니다.

{
	"settings": {
		"rights": [ "foo", "bar" ],
		"default": false,
		"package": false,
		"hidden": false,
		"skins": [],
		"actions": [],
		"category": ""
	},
	"module": {
		"scripts": [ "mygadget.js" ],
		"styles": [ "mygadget.css" ],
		"datas": [],
		"peers": [],
		"dependencies": [],
		"messages": [],
		"type": ""
	}
}

위의 예시와 같이 Gadget:Mygadget.jsGadget:mygadget.css 가 사용됩니다.

Options

Options
Name Parameters Description Since
ResourceLoader None Marks gadget's scripts as compatible with ResourceLoader . 1.17 (r76527)
dependencies Comma-separated module names These modules will be loaded before the scripts of this gadget execute. See list of default modules. 1.17 (r76639)
rights Comma-separated privilege names Make the gadget available (and visible in preferences) only to users who have the specified privileges. 1.18 (r85268)
hidden None Hide the gadget from the Preferences page. This can be used in two ways:
  • Enable a gadget by default without the ability to disable (as a modular alternative to Common.js). Note that you need to add both: hidden | default to load a module for all users.
  • Gadgets that are not meant for end-users but rather are meant to be loaded by other gadgets. For example, to allow two gadgets to re-use the same internal code or to register the "core" part of a gadget that only loads on certain pages.
1.28
skins Comma-separated skin names Make the gadget available (and visible in preferences) only to users who use the specified skins. Before MediaWiki 1.32 it was taking into consideration the skin set in preferences for the user, not the current displayed one (like when adding ?useskin=monobook in the URL, 작업 T199478). Since 1.39, the ResourceLoader module is not registered on skins the gadget is unavailable on, so the gadget cannot be loaded on those skins as a dependency or using mw.loader.load() either (작업 T236603).
Use of skins is a last resort, and should be restricted to specialized code. For example code which relies on DOM manipulation in the absence of standardized APIs and that cannot be implemented using Core modules.
1.19 (r100509)
actions Comma-separated action names Make the gadget available only on the specified page actions. E.g. actions = edit, history to load a gadget only while editing and on history pages.
Specifying edit action will also load it on action=submit. Invalid actions effectively disable the gadget since it can't be run anywhere.
1.38 (gerrit:747112)
categories Comma-separated category names Make the gadget available only on the specified categories. E.g. categories = Archived, Maintenance to load a gadget only on pages in the Category:Archived or Category:Maintenance. See also: Template gadgets . 1.42 (gerrit:1005092)
namespaces Comma-separated namespace numbers Make the gadget available only on the specified namespaces. E.g. namespaces = 0, 2 to load a gadget only in mainspace and user namespace. 1.41 (gerrit:624517)
contentModels Comma-separated content models Make the gadget available on pages with the given content models. E.g. contentModels = wikitext to load a gadget only on wikitext pages. 1.41 (gerrit:922062)
default None Enable the gadget by default for everyone (including IPs). Registered users can still disable it in their preferences. 1.18 (r85902)
package None Mark this gadget as packaged. Only the first JavaScript page will be executed in this mode. Other pages can be imported by using the require() function. This mode also enables the use of JSON pages, which cannot be included otherwise. 1.38
type styles (default for CSS-only gadgets) or general (default otherwise) Use styles for modules that only modify styling for elements already on the page (e.g. when customizing the skin, layout, or article content). It will cause the CSS files of the module to be included from the page HTML instead of being loaded via JavaScript. For details, see ResourceLoader/Migration guide (users)#Gadget type.
Using styles will not load in any specified JavaScript files. For gadgets that modify styling for elements through both JavaScript and CSS, two individual gadget definitions are required.
1.28
peers Comma-separated gadget names These CSS-only gadgets will be loaded with this gadget. These gadgets will be loaded before any dependencies, and their styles will be applied even if JavaScript is disabled. For details, see ResourceLoader/Migration guide (users)#Gadget peers. 1.29
supportsUrlLoad None | true | false Make the gadget available to be loaded with the ?withgadget URL query parameter. 1.38
Removed options
Name Parameters Description Since Removed
top None Makes the gadget to be top-loaded. This should be used sparingly, but may be needed for some initialization stuff like registering plugins with VisualEditor. 1.22 (gerrit:75506) 1.29
requiresES6 None Allow use of ES6 syntax (ES2015) in the gadget. Enabling this means server-side syntax validation is skipped for the gadget. Any ES6-requiring gadgets are loaded together in a single web request, which isolates failures due to invalid or unsupported syntax to those gadgets only, without affecting other gadgets and MediaWiki software features. It is recommended to use a tool like ESLint to ensure only valid ES6 syntax is used. Conflicts with default. 1.40 (gerrit:758086) 1.42
targets desktop, mobile or desktop, mobile(default) Set the ResourceLoader target(s) for the gadget.
Do not use targets, instead use skins where absolutely necessary.
1.21 (gerrit:60954) 1.42

You can specify extra dependencies for your gadgets, for example:

* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css

Here, we ask ResourceLoader to load modules jquery.ui and jquery.effects.clip with mygadget. Note that gadgets can't depend on scripts from pages, static files, or external URLs, only on modules already registered in ResourceLoader. To make a script from a page depend on another script from a page, each should be a gadget that registers itself as a module in ResourceLoader, then they can be made to have dependencies using the following syntax:

* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js

To enable a gadget by default, use "default":

* mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css

To make the gadget available only to users with appropriate permissions, set the rights option, for example:

* ImprovedDeletion [rights=delete] | ImprovedDeletion.js

It makes the gadget available only to users who can delete pages.

Note that restrictions are based on permissions, not user groups like administrators or bureaucrats.

Here are some real examples:

* modrollback [ResourceLoader |rights=rollback] |modrollback.js
* geonotice [ResourceLoader |default |rights=viewmywatchlist] |geonotice.js
* Ajax_sysop [ResourceLoader |rights=patrol, rollback, markbotedits, delete]|Ajax_sysop.js


User rights

This extension adds two new user rights, gadgets-edit and gadgets-definition-edit, which by default aren't given to any group.

LocalSettings.php 에 다음을 추가하여 interface-admin 그룹 내에 있는 사용자에게 적절한 권한을 제공할 수 있습니다. 가젯 네임스페이스에서 페이지를 편집하려면 gadgets-edit 권한이 필요하고 가젯 정의 네임스페이스에서 페이지를 편집하려면 gadgets-definition-edit 권한이 필요합니다.

$wgGroupPermissions['interface-admin']['gadgets-edit'] = true;
$wgGroupPermissions['interface-admin']['gadgets-definition-edit'] = true;

Pages

The remaining fields on the definition line refer to the JavaScript, CSS, or JSON source pages that make up the gadget module. These are stored in the MediaWiki namespace as interface messages (MediaWiki:Gadget-mygadget.js and MediaWiki:Gadget-mygadget.css in the example). The page names must end with ".css", ".js", or ".json" respectively.

A gadget can use any number of source pages, e.g.:

 * frobinator[ResourceLoader]|frob.js|frob.css|pretty.css
 * l33t[ResourceLoader]|l33t.js
 * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json

Please note that if your code contains strings that could be interpreted as wiki syntax (e.g., the signature code ~~~~), you may want to enclose your code into ‎<nowiki>...‎</nowiki> and put these tags in JavaScript or CSS comments so they're not interpreted when used.

See the first and last lines of MediaWiki:Gadget-externalsearch-bar.js for an example.

Sections

The list of gadgets in MediaWiki:Gadgets-definition can be broken into sections using lines that start and end with two or more "=" (equals) characters, enclosing the name of a system message that defines the section's name, for example:

 == interface-gadgets ==
 ...
 == editing-gadgets ==
 ...

This would define two new sections, with the titles defined on the pages MediaWiki:Gadget-section-interface-gadgets and MediaWiki:Gadget-section-editing-gadgets.

See meta:Gadgets for gadgets that are popular in Wikimedia communities.

See also