MediaWiki

Thủ công:Dịch phần mở rộng

This page is a translated version of the page Manual:Developing extensions and the translation is 93% complete.
Outdated translations are marked like this.
Languages:
Extensions:
Phần mở rộng MediaWiki

Mỗi mở rộng(extension) bao gồm ba phần:

  1. Cài đặt
  2. Thực thi
  3. Bản địa hóa

Một phần mở rộng tối thiểu sẽ bao gồm cấu trúc sau:

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.

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] (BoilerPlate extension là điểm khởi đầu tốt cho tiện ích mở rộng của bạn.)

Trong khi phát triển, bạn có thể muốn tắt bộ nhớ đệm bằng cách đặt $wgMainCacheType = CACHE_NONE và $wgCacheDirectory = false, nếu không, thông báo hệ thống và các thay đổi khác có thể không hiển thị.

Thiết lập

Mục tiêu của bạn khi viết phần thiết lập là làm cho việc cài đặt tiện ích mở rộng dễ dàng nhất có thể, vì vậy người dùng chỉ cần thêm dòng này vào LocalSettings.php: 

wfLoadExtension( 'MyExtension' );

Nếu bạn muốn tạo ra phần mở rộng của mình do người dùng có thể cấu hình, bạn cần xác định và ghi lại một số tham số cấu hình và thiết lập người dùng của bạn sẽ trông giống như: 

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

Để đạt được sự đơn giản này, tệp thiết lập của bạn cần hoàn thành một số nhiệm vụ (được mô tả chi tiết trong các phần sau):

  • đăng ký bất kỳ trình xử lý phương tiện nào, hàm phân tích cú pháp, trang đặc biệt, tùy chỉnh thẻ XML và biến(variable) được sử dụng bởi phần mở rộng của bạn,
  • xác định và/hoặc xác thực bất kỳ biến cấu hình nào bạn đã xác định cho phần mở rộng của mình.
  • chuẩn bị các lớp(classe) được sử dụng bởi phần mở rộng của bạn để tự động tải
  • xác định phần nào trong thiết lập của bạn nên được thực hiện ngay lập tức và phần nào cần được hoãn lại cho đến khi lõi MediaWiki được khởi tạo và định cấu hình
  • xác định bất kỳ bổ sung móc nối nào mà tiện ích mở rộng của bạn cần
  • tạo hoặc kiểm tra bất kỳ bảng cơ sở dữ liệu mới theo yêu cầu bởi phần mở rộng của bạn.
  • thiết lập bản địa hóa cho tiện ích mở rộng của bạn
Good practice is to add a README file with basic info about how to install and configure the extension. You can use either plain text or Phabricator markup syntax. For 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.

Đăng ký tính năng với MediaWiki

MediaWiki liệt kê tất cả các phần mở rộng đã được cài đặt trên Special:Version trang của trang. Ví dụ: bạn có thể xem tất cả phần mở rộng được cài đặt trên wiki này tại Special:Version.

Phiên bản MediaWiki:
≥ 1.25

Để thực hiện việc này, hãy thêm mở rộng chi tiết vào extension.json . Mục nhập sẽ trông giống như thế này: 

{
	"name": "Example",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:Example",
	"description": "This extension is an example and performs no discernible function",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensionclass",
	"manifest_version": 1
}


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 đó. 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.

Ngoài việc đăng ký ở trên, bạn cũng phải "móc nối" tính năng của mình vào MediaWiki. Ở trên chỉ thiết lập trang Đặc biệt:Phiên bản trang. Cách bạn thực hiện việc này phụ thuộc vào loại tiện ích mở rộng của bạn. Để biết chi tiết, vui lòng xem tài liệu cho từng loại tiện ích mở rộng:

Extensions:

Làm cho phần mở rộng của bạn do người dùng có thể định cấu hình

Nếu bạn muốn người dùng có thể định cấu hình tiện ích mở rộng của mình, thì bạn cần cung cấp một hoặc nhiều biến cấu hình. Bạn nên đặt tên riêng cho các biến đó. Họ cũng nên tuân theo MediaWiki quy ước đặt tên (ví dụ: các biến toàn cục nên bắt đầu bằng $wg).

Ví dụ: nếu tiện ích mở rộng của bạn có tên là "MyExtension", bạn có thể muốn đặt tên cho tất cả các biến cấu hình của mình để bắt đầu bằng $wgMyExtension. Điều quan trọng là không có lõi MediaWiki bắt đầu các biến của nó theo cách này và bạn đã thực hiện một công việc hợp lý là kiểm tra để thấy rằng không có phần mở rộng nào được xuất bản bắt đầu các biến của chúng theo cách này. Người dùng sẽ không hài lòng khi phải chọn giữa tiện ích mở rộng của bạn và một số tiện ích mở rộng khác vì bạn đã chọn tên biến trùng lặp.

Bạn cũng nên bao gồm tài liệu mở rộng về bất kỳ biến cấu hình nào trong ghi chú cài đặt của mình.

Đây là ví dụ kiểu mẫu có thể được sử dụng để bắt đầu: 

{
	"name": "BoilerPlate",
	"version": "0.0.0",
	"author": [
		"Your Name"
	],
	"url": "https://www.mediawiki.org/wiki/Extension:BoilerPlate",
	"descriptionmsg": "boilerplate-desc",
	"license-name": "GPL-2.0-or-later",
	"type": "other",
	"AutoloadClasses": {
		"BoilerPlateHooks": "includes/BoilerPlateHooks.php",
		"SpecialHelloWorld": "includes/SpecialHelloWorld.php"
	},
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	},
	"callback": "BoilerPlateHooks::onExtensionLoad",
	"ExtensionMessagesFiles": {
		"BoilerPlateAlias": "BoilerPlate.i18n.alias.php"
	},
	"Hooks": {
		"NameOfHook": "BoilerPlateHooks::onNameOfHook"
	},
	"MessagesDirs": {
		"BoilerPlate": [
			"i18n"
		]
	},
	"ResourceModules": {
		"ext.boilerPlate.foo": {
			"scripts": [
				"resources/ext.boilerPlate.js",
				"resources/ext.boilerPlate.foo.js"
			],
			"styles": [
				"resources/ext.boilerPlate.foo.css"
			]
		}
	},
	"ResourceFileModulePaths": {
		"localBasePath": "",
		"remoteExtPath": "BoilerPlate"
	},
	"SpecialPages": {
		"HelloWorld": "SpecialHelloWorld"
	},
	"manifest_version": 2
}

Lưu ý rằng sau khi gọi wfLoadExtension( 'BoilerPlate' ); thì biến toàn cục $wgBoilerPlateEnableFoo không tồn tại. Nếu bạn đặt biến, ví dụ: trong LocalSettings.php thì giá trị mặc định được cung cấp trong extension.json sẽ không được sử dụng. If you set the variable, e.g. in LocalSettings.php then the default value given in extension.json will not be used.

Để biết thêm chi tiết về cách sử dụng biến toàn cục bên trong tiện ích mở rộng tùy chỉnh, vui lòng tham khảo Manual:Configuration for developers .

Chuẩn bị các lớp để tự động tải

Nếu bạn chọn sử dụng các lớp để triển khai tiện ích mở rộng của mình, MediaWiki cung cấp một cơ chế đơn giản hóa để giúp PHP tìm tệp nguồn nơi đặt lớp của bạn. Trong hầu hết các trường hợp, điều này sẽ loại bỏ nhu cầu viết phương thức __autoload($classname) của riêng bạn.

Để sử dụng cơ chế tự động tải của MediaWiki, bạn thêm các mục nhập vào trường AutoloadClasses . Chìa khóa của mỗi mục là tên lớp; giá trị là tệp lưu trữ định nghĩa của lớp. Đối với tiện ích mở rộng một lớp đơn giản, lớp thường được đặt cùng tên với tiện ích mở rộng, vì vậy phần tự động tải của bạn có thể trông như thế này (tiện ích mở rộng có tên MyExtension): 

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

Tên tệp có liên quan đến thư mục chứa tệp extension.json.

Đối với các tiện ích mở rộng phức tạp hơn, không gian tên nên được xem xét. Xem Manual:Extension.json/Schema#AutoloadNamespaces để biết chi tiết.

Xác định móc bổ sung

Xem Manual:Hooks .

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.

Cài đặt bản địa hóa

Xem:

Thêm nhật ký

Trên MediaWiki, tất cả các hành động của người dùng trên wiki đều được theo dõi để đảm bảo tính minh bạch và cộng tác. Xem Manual:Logging to Special:Log để biết cách thực hiện.

Xử lý các phụ thuộc

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 yêu cầu trong extension.json.

Another option is using ExtensionRegistry (available since MW 1.25): 

	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' ) {
    ...
	}

Bản địa hóa

Trong khi phát triển, bạn có thể muốn tắt cả hai bộ nhớ đệm bằng cách đặt $wgMainCacheType = CACHE_NONE và $wgCacheDirectory = false, nếu không các thay đổi thông báo hệ thống của bạn có thể không hiển thị.

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.

Lưu trữ tin nhắn trong <language-key>.json

Lưu trữ các định nghĩa thông báo trong tệp JSON bản địa hóa, một tệp cho mỗi khóa ngôn ngữ mà tiện ích mở rộng của bạn được dịch sang. Các tin nhắn được lưu bằng khóa tin nhắn và chính tin nhắn đó sử dụng định dạng JSON tiêu chuẩn. Mỗi thông điệp id phải là chữ thường và có thể không chứa dấu cách. Mỗi khóa phải bắt đầu bằng tên mở rộng viết thường. Một ví dụ bạn có thể tìm thấy trong phần mở rộng GiaodiệnMobile (MobileFrontend) . Đây là một ví dụ về tệp JSON tối thiểu (trong trường hợp này là en.json):

en.json 

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

Lưu trữ tài liệu tin nhắn trong qqq.json

Tài liệu về khóa thông báo có thể được lưu trữ trong tệp JSON dành cho ngôn ngữ giả có mã qqq. Một tài liệu của ví dụ trên có thể là:

qqq.json: 

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

Tải tệp bản địa hóa

Trong extension.json của bạn, hãy xác định vị trí của các tệp tin nhắn của bạn (ví dụ: trong thư mục i18n/): 

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

Sử dụng wfMessage trong PHP

Trong mã triển khai và thiết lập của bạn, hãy thay thế từng cách sử dụng thông báo theo nghĩa đen bằng lệnh gọi wfMessage( $msgID, $param1, $param2, ... ). Trong các lớp triển khai IContextSource (cũng như một số lớp khác, chẳng hạn như các lớp con của Trang đặc biệt), bạn có thể sử dụng $this->msg( $msgID, $param1, $param2, ... ) để thay thế. Ví dụ: 

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

Sử dụng mw.message trong JavaScript

Cũng có thể sử dụng các hàm i18n trong JavaScript. Xem tại Manual:Messages API để biết chi tiết.

Các kiểu mở rộng

Extensions:

Các phần mở rộng có thể được phân loại dựa trên các kỹ thuật lập trình được sử dụng để đạt được hiệu quả của chúng. Hầu hết các tiện ích mở rộng phức tạp sẽ sử dụng nhiều hơn một trong các kỹ thuật sau:

  • Phân lớp: MediaWiki mong đợi một số loại tiện ích mở rộng nhất định sẽ được triển khai dưới dạng các lớp con của lớp cơ sở do MediaWiki cung cấp:
    • Special pages – Các lớp con của lớp SpecialPage được sử dụng để xây dựng các trang có nội dung được tạo động bằng cách sử dụng kết hợp trạng thái hệ thống hiện tại, tham số đầu vào của người dùng và truy vấn cơ sở dữ liệu. Có thể tạo cả báo cáo và biểu mẫu nhập dữ liệu. Chúng được sử dụng cho cả mục đích báo cáo và quản trị.
    • Hướng dẫn sử dụng:Giao diện – Giao diện thay đổi giao diện của MediaWiki bằng cách thay đổi mã xuất ra các trang bằng cách phân lớp con lớp MediaWiki SkinTemplate .
  • Hooks – Một kỹ thuật để đưa mã PHP tùy chỉnh vào các điểm chính trong quá trình xử lý MediaWiki. Chúng được sử dụng rộng rãi bởi trình phân tích cú pháp của MediaWiki, công cụ bản địa hóa, hệ thống quản lý tiện ích mở rộng và hệ thống bảo trì trang của nó.
    • Liên kết chức năng thẻ – XML thẻ kiểu được liên kết với hàm php xuất mã HTML. Bạn không cần phải giới hạn bản thân trong việc định dạng văn bản bên trong các thẻ. Bạn thậm chí không cần phải hiển thị nó. Nhiều tiện ích mở rộng thẻ sử dụng văn bản làm tham số hướng dẫn việc tạo HTML nhúng các đối tượng Google, biểu mẫu nhập dữ liệu, nguồn cấp RSS, đoạn trích từ các bài viết wiki được chọn.
  • Hướng dẫn:Từ ma thuật – Một kỹ thuật để ánh xạ nhiều chuỗi văn bản wiki thành một id duy nhất được liên kết với một hàm. Cả biến(variables) và hàm phân tích cú pháp đều sử dụng kỹ thuật này. Tất cả văn bản được ánh xạ tới id đó sẽ được thay thế bằng giá trị trả về của hàm. Ánh xạ giữa các chuỗi văn bản và id được lưu trữ trong mảng $magicWords. Việc diễn giải id là một quá trình hơi phức tạp – xem Hướng dẫn:Từ ma thuật để biết thêm thông tin.
    • Variable – Các biến là một cái gì đó của một cách gọi sai. Chúng là các phần của wikitext trông giống như các mẫu nhưng không có tham số và đã được gán giá trị mã hóa cứng. Đánh dấu wiki tiêu chuẩn như {{PAGENAME}} hoặc {{SITENAME}} là những ví dụ về biến. Họ lấy tên từ nguồn giá trị của họ: biến php hoặc thứ gì đó có thể được gán cho biến, ví dụ: một chuỗi, một số, một biểu thức hoặc một giá trị trả về của hàm.
    • Hướng dẫn:Hàm phân tích cú pháp – {{functionname: argument 1 | argument 2 | argument 3...}}. Tương tự như phần mở rộng thẻ, các hàm trình phân tích cú pháp xử lý các đối số và trả về một giá trị. Không giống như phần mở rộng thẻ, kết quả của các hàm phân tích cú pháp là wikitext.
  • API modules – bạn có thể thêm các mô-đun tùy chỉnh vào API hành động của MediaWiki, mô-đun này có thể được gọi bằng JavaScript, bot hoặc ứng dụng khách bên thứ ba.
  • Page content models – Nếu bạn cần lưu trữ dữ liệu ở các định dạng khác ngoài wikitext, JSON, v.v. thì bạn có thể tạo ContentHandler mới.

Hỗ trợ các phiên bản cốt lõi khác

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 Template:Số nhánh ổn định MW cần sử dụng nhánh Template:MW nhánh ổn định git 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.

(For extensions hosted on gerrit, these branches are automatically created when new versions of MediaWiki are released.) This results in cleaner code and faster development but users on old core versions do not benefit from bugfixes and new features unless they are backported manually.

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 {{Bản mẫu:Phần mở rộng }} mà họ tuân theo quy ước.

Giấy phép

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:

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 it's short name, e.g. "GPL-2.0-or-later" or "MIT" adhering to the list of identifiers at spdx.org.


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.

Triển khai và đăng ký

Nếu bạn có ý định triển khai tiện ích mở rộng của mình trên các trang Wikimedia (bao gồm cả Wikipedia), thì cần phải xem xét kỹ lưỡng hơn về mặt hiệu suất và bảo mật. Tham khảo Writing an extension for deployment .

Nếu tiện ích mở rộng của bạn thêm không gian tên, bạn có thể muốn đăng ký không gian tên mặc định của nó; tương tự như vậy, nếu nó thêm các bảng hoặc trường cơ sở dữ liệu, bạn có thể muốn đăng ký chúng tại database field prefixes .

Xin lưu ý rằng việc xem xét và triển khai các tiện ích mở rộng mới trên các trang Wikimedia có thể cực kỳ chậm và trong một số trường hợp phải mất hơn hai năm.[4]

Hỗ trợ tài liệu

Bạn nên cung cấp nơi có hỗ trợ tài liệu cho các tính năng do phần mở rộng của bạn cung cấp. Help:CirrusSearch là một ví dụ điển hình. Bạn nên cung cấp cho người dùng một liên kết đến tài liệu thông qua chức năng addHelpLink() .

Cung cấp hỗ trợ/hợp tá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

Learn by example


Tham khảo

  1. ↑ mailarchive:wikitech-l/2011-August/054839.html
  2. ↑ https://www.mediawiki.org/wiki/Topic:Xyjw7nhfzaas5r5z
  3. ↑ https://phabricator.wikimedia.org/T356596
  4. ↑ phabricator:T148848
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Developing_extensions/vi&oldid=6349632"