Extensions :

• Installation and upgrade
• Development
• Registration
• Translation
• All extensions
• Category
• Extensions FAQ

Nếu bạn định triển khai tiện ích mở rộng của mình trên các trang Wikimedia, hãy đọc Writing an extension for deployment

This page is a guide to developing extensions for MediaWiki. Before you start, browse the complete list in: Category:Extensions by category ^{vi[[::Category:Extensions by category| ]]} to see if an extension already exists for your use case.

Extension development consists of these parts:

1. Cài đặt
2. Implementation
3. Bản địa hóa
4. Publication

Thiết lập

MyExtension/extension.json

Lưu trữ cài đặt hướng dẫn. Tên tệp phải là extension.json. (Trước MediaWiki 1.25, hướng dẫn thiết lập nằm trong tệp MyExtension/MyExtension.php được đặt tên theo phần mở rộng. Nhiều tiện ích mở rộng vẫn có phần đệm tương thích ngược trong tệp PHP này.)

MyExtension/includes/ (or MyExtension/src/)

Lưu trữ mã PHP thực thi cho tiện ích mở rộng.

MyExtension/resources/ (or MyExtension/modules/)

Lưu trữ các tài nguyên phía-máy-khách(client-side) như JavaScript, CSS và LESS cho tiện ích mở rộng.

MyExtension/i18n/*.json

Lưu trữ bản địa hóa thông tin cho tiện ích mở rộng.

MyExtension/README.md

Good practice is to add a README file with basic info about how to install and configure the extension. Use either plain text or Markdown. For a plain text example, see the Phabricator Diffusion page for the Extension:Page Forms . If markdown is used, add the file extension .md. For example, see the README.md file for Parsoid on Phabricator Diffusion.

Khi bạn phát triển tiện ích mở rộng, hãy thay MyExtension ở trên bằng tên tiện ích mở rộng của bạn. Sử dụng UpperCamelCase tên cho thư mục và (các) tệp PHP của nó; đây là quy ước chung đặt tên tệp.^[1]

The extension.json file contains the configuration data for the extension. Here is an example of a minimal extension.json:

{
	"name": "MyExtension",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:MyExtension",
	"description": "This extension is an example.",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensiontype",
	"manifest_version": 2
}

Nhiều trường là tùy chọn, nhưng bạn vẫn nên điền vào các trường đó. For a more complete example of extension.json, see the BoilerPlate extension.

manifest_version đề cập đến phiên bản của lược đồ mà tệp extension.json được viết dựa trên đó. Các phiên bản có sẵn là 1 và 2. Xem tại đây để biết tài liệu về tính năng này. Trừ khi bạn cần hỗ trợ phiên bản cũ hơn của MediaWiki, hãy chọn phiên bản mới nhất.

Once you have an extension.json file set up for your extension, the extension will appear on your local Special:Version page.

MediaWiki is an open-source project and users are encouraged to make any MediaWiki extensions under an Open Source Initiative (OSI) approved license compatible with GPL-2.0-or-later (Wikimedia's standard software license).

We recommend adopting one of the following compatible licenses for your projects in Gerrit:

• GNU General Public License, version 2 or later (GPL-2.0-or-later)
• MIT License (MIT)
• BSD License (BSD-3-Clause)
• Apache License 2.0 (Apache-2.0)

For extensions that have a compatible license, you can request developer access to the MediaWiki source repositories for extensions. To specify the licence in code and with "license-name" a key should be used to provide its short name, e.g. "GPL-2.0-or-later" or "MIT" adhering to the list of identifiers at spdx.org.

wfLoadExtension( 'MyExtension' );

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

{
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	}
}

{
	"AutoloadClasses": {
		"MyExtension": "includes/MyExtension.php"
	}
}

Giả sử rằng một tiện ích mở rộng yêu cầu sự hiện diện của một tiện ích mở rộng khác, chẳng hạn vì các chức năng hoặc bảng cơ sở dữ liệu sẽ được sử dụng và cần tránh các thông báo lỗi trong trường hợp không tồn tại.

Ví dụ: phần mở rộng CountingMarker yêu cầu sự hiện diện của phần mở rộng HitCounters cho các chức năng nhất định.

Một cách để chỉ định điều này là sử dụng khóa requires trong extension.json .

	if ( ExtensionRegistry::getInstance()->isLoaded( 'HitCounters', '>=1.1' ) {
		/* do some extra stuff, if extension HitCounters is present in version 1.1 and above */
	}

Currently (as of February 2024, MediaWiki 1.41.0) the name of the extension-to-be-checked needs to exactly match the name in their extension.json.^[2][3]

Example: if you want to check the load status of extension OpenIDConnect, you have to use it with a space

	if ( ExtensionRegistry::getInstance()->isLoaded( 'OpenID Connect' ) {
    ...
	}

MediaWiki core provides several ways for extensions to change the behavior, functionality, and appearance of a wiki. Most extensions use more than one of these extension points. For a complete list of extension points supported in extension.json, see the schema reference .

• Hooks : Inject custom code at key points in MediaWiki core code, such as when a user logs in or saves a page. Extensions can also define new hooks.
• Domain events : React to changes to the wiki's state, such as when a page is edited. Extensions can also define their own events. 1.44
• API modules : Define API modules based on the Action API or REST API . These modules can be called by bots or clients.
• Jobs : Add jobs to MediaWiki's JobQueue to perform process-intensive tasks asynchronously, such as sending notification emails.

• Display a special page : Special pages provide dynamically generated content, often based on system state, database queries, and user inputs.
• Perform a page action : The action URL parameter generates a custom page based on the current page, usually to provide information (such as page history) or to perform an action (such as edit the page). In addition to the default actions provided by MediaWiki core, extensions can define a new page action.
• Add a tracking category : Help users find pages with similar characteristics by automatically adding pages to custom categories.

• Extend wiki markup : Extensions can add custom functionality to MediaWiki's wikitext markup using template syntax ({{...}}) or tags (‎<example />). These customizations are used to generate content and to interact with MediaWiki during page rendering.
• Support a content model : By default, wiki pages can be stored using a few standard content models, such as wikitext and JSON. Extensions can provide support for new content models by adding a content handler.
• Support a media type : Extensions can add to the default set of supported media file types by adding a media handler.

• Log a user or system action : On wiki, actions are tracked for transparency and collaboration. To support this feature, extensions can add custom entries and functionality to Special:Log.
• Add a recent-changes flag : Extensions can add custom flags to the following special pages to help moderators track page changes: Special:RecentChanges, Special:Watchlist, Special:RecentChangesLinked
• Add a revision tag : Extensions can add annotations associated with a revision or log entry, such as for edits made using the VisualEditor extension.

• Add a provider : Extensions can add support for new login mechanisms and session management methods.

Thêm bảng cơ sở dữ liệu

Đảm bảo tiện ích mở rộng không sửa đổi các bảng cơ sở dữ liệu cốt lõi. Thay vào đó, tiện ích mở rộng sẽ tạo các bảng mới có khóa ngoại cho các bảng MW có liên quan.

Cảnh báo:

Nếu tiện ích mở rộng của bạn được sử dụng trên bất kỳ wiki sản xuất nào do WMF lưu trữ, vui lòng làm theo [hướng dẫn thay đổi lược đồ https://wikitech.wikimedia.org/wiki/Schema_changes].

Nếu tiện ích mở rộng của bạn cần thêm các bảng cơ sở dữ liệu riêng, hãy sử dụng móc nối(hook) LoadExtensionSchemaUpdates . Xem trang hướng dẫn để biết thêm thông tin về cách sử dụng.

Bản địa hóa

Localisation – thảo luận về công cụ bản địa hóa MediaWiki, đặc biệt, có một danh sách các tính năng có thể được bản địa hóa và một số đánh giá về các lớp mã nguồn MediaWiki liên quan đến bản địa hóa. Tạo tin nhắn mới Localization checks – thảo luận về các sự cố thường gặp với thông báo được bản địa hóa Chỗ đặt tên

Nếu bạn muốn phần mở rộng của mình được sử dụng trên wiki có lượng độc giả đa ngôn ngữ, bạn sẽ cần thêm hỗ trợ bản địa hóa cho phần mở rộng của mình.

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

Xuất bản

Để tự động phân loại và chuẩn hóa tài liệu của tiện ích mở rộng hiện tại của bạn, vui lòng xem Bản mẫu:Phần mở rộng . Để thêm phần mở rộng mới của bạn vào Wiki này:

A developer sharing their code in the MediaWiki code repository should expect:

Feedback / Criticism / Code reviews

Review and comments by other developers on things like framework use, security, efficiency and usability.

Developer tweaking

Other developers modifying your submission to improve or clean-up your code to meet new framework classes and methods, coding conventions and translations.

Improved access for wiki sysadmins

If you do decide to put your code on the wiki, another developer may decide to move it to the MediaWiki code repository for easier maintenance. You may then create a developer account to continue maintaining it.

Future versions by other developers

New branches of your code being created automatically as new versions of MediaWiki are released. You should backport to these branches if you want to support older versions.

Incorporation of your code into other extensions with duplicate or similar purposes — incorporating the best features from each extension.

Credit

Credit for your work being preserved in future versions — including any merged extensions.

Similarly, you should credit the developers of any extensions whose code you borrow from — especially when performing a merger.

Any developer who is uncomfortable with any of these actions occurring should not host in the code repository. You are still encouraged to create a summary page for your extension on the wiki to let people know about the extension, and where to download it.

Có hai quy ước phổ biến để hỗ trợ các phiên bản lõi MediaWiki cũ hơn:

• Master: nhánh chính của tiện ích mở rộng tương thích với càng nhiều phiên bản lõi cũ càng tốt. Điều này dẫn đến gánh nặng bảo trì (các bản hack tương thích ngược cần được duy trì trong một thời gian dài và các thay đổi đối với tiện ích mở rộng cần được thử nghiệm với một số phiên bản MediaWiki), nhưng các trang web chạy phiên bản MediaWiki cũ được hưởng lợi từ chức năng được thêm gần đây vào sự mở rộng.
• Release branches: các nhánh phát hành của tiện ích mở rộng tương thích với các nhánh phù hợp của lõi, ví dụ: các trang web sử dụng MediaWiki 1.43 cần sử dụng nhánh REL1_43 của tiện ích mở rộng. (Đối với các tiện ích mở rộng được lưu trữ trên gerrit, các nhánh này được tạo tự động khi các phiên bản MediaWiki mới được phát hành.) Điều này dẫn đến mã sạch hơn và phát triển nhanh hơn nhưng người dùng trên các phiên bản cốt lõi cũ không được hưởng lợi từ các bản sửa lỗi và tính năng mới trừ khi chúng đã nhập ngược theo cách thủ công.

Người bảo trì tiện ích mở rộng nên khai báo với tham số compatibility policy của mẫu {{Phần mở rộng }} mà họ tuân theo quy ước.

Các nhà phát triển phần mở rộng nên mở một tài khoản trên {Phabricator của Wikimedia, và yêu cầu một dự án mới cho phần mở rộng. Điều này cung cấp một địa điểm công cộng nơi người dùng có thể gửi các vấn đề và đề xuất, đồng thời bạn có thể cộng tác với người dùng và các nhà phát triển khác để phân loại lỗi và lập kế hoạch cho các tính năng của tiện ích mở rộng của bạn.

Xem thêm

• Manual:Extension registration – provides further developer documentation on how to register extensions and skins.
• API:Extensions – giải thích cách phần mở rộng của bạn có thể cung cấp API cho khách hàng
• Manual:Extending wiki markup
• Manual:Coding conventions
• Các phương pháp hay nhất dành cho phần mở rộng
• ResourceLoader

• Extension:Examples – thực hiện một số tính năng ví dụ với tài liệu nội tuyến mở rộng
  • ví dụ git repo với mã ví dụ này và mã ví dụ khác
• Extension:BoilerPlate – một tiện ích mở rộng soạn sẵn đang hoạt động, hữu ích như một điểm khởi đầu cho tiện ích mở rộng của riêng bạn (git repo).
  • Đọc Ví dụ mở rộng, dựa trên mã của riêng bạn phần mở rộng BoilerPlate.
• cookiecutter-mediawiki-extension – cookiecutter mẫu tạo phần mở rộng soạn sẵn (với các biến, v.v.)
  • Cho phép bạn bắt đầu nhanh chóng với phần mở rộng của riêng mình.
  • Cũng có thể tạo phần mở rộng BoilerPlate.
• List of simple extensions – sao chép mã cụ thể từ họ

Tham khảo