Manual:Developing extensions/vi



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

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``:

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ư:

Để đạ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



Đă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  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.

Để 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:

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 đó. đề cập đến phiên bản của lược đồ mà tệp đượ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:



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. Đ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:

Lưu ý rằng sau khi gọi  thì biến toàn cục   không tồn tại. Nếu bạn đặt biến, ví dụ: trong  thì giá trị mặc định được cung cấp trong extension.json sẽ không được sử dụng.

Để 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.



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  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. 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):

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.



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.

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). 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:
 * Bản địa hóa (tóm tắt)



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 để 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 yêu cầu sự hiện diện của phần mở rộng  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  trong extension.json.

Mặt khác, một số ý tưởng để tìm ra điều này:

Điều này sẽ hoạt động ít nhất từ ​​1,23 đến 1,35.

Bản địa hóa
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 &lt;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



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:



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/):



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. Trong các lớp triển khai (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  để thay thế. Ví dụ:



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



Các kiểu mở rộng
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:
 *  – Các lớp con của lớp đượ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ị.
 *  – 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.
 *  – 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ó.
 *  – XML thẻ kiểu được liên kết với hàm php xuất mã HTML. You do not need to limit yourself to formatting the text inside the tags. You don't even need to display it. Many tag extensions use the text as parameters that guide the generation of HTML that embeds Google objects, data entry forms, RSS feeds, excerpts from selected wiki articles.
 *  – A technique for mapping a variety of wiki text string to a single id that is associated with a function. Both variables and parser functions use this technique. All text mapped to that id will be replaced with the return value of the function. The mapping between the text strings and the id is stored in the array $magicWords. The interpretation of the id is a somewhat complex process – see  for more information.
 *  – Variables are something of a misnomer. They are bits of wikitext that look like templates but have no parameters and have been assigned hard-coded values. Standard wiki markup such as  or   are examples of variables. They get their name from the source of their value: a php variable or something that could be assigned to a variable, e.g. a string, a number, an expression, or a function return value.
 *  – .  Similar to tag extensions, parser functions process arguments and returns a value. Unlike tag extensions, the result of parser functions is wikitext.
 *  – you can add custom modules to MediaWiki's action API, that can be invoked by JavaScript, bots or third-party clients.
 *  – If you need to store data in formats other than wikitext, JSON, etc. then you can create a new.

Support other core versions
There are two widespread conventions for supporting older versions of MediaWiki core:


 * Master: the master branch of the extension is compatible with as many old versions of core as possible. This results in a maintenance burden (backwards-compatibility hacks need to be kept around for a long time, and changes to the extension need to be tested with several versions of MediaWiki), but sites running old MediaWiki versions benefit from functionality recently added to the extension.
 * Release branches: release branches of the extension are compatible with matching branches of core, e.g. sites using MediaWiki need to use the  branch of the extension. (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.

Extension maintainers should declare with the  parameter of the Extension template which convention they follow.

Publishing
To autocategorize and standardize the documentation of your existing extension, please see. To add your new extension to this Wiki:

Deploying and registering
If you intend to have your extension deployed on Wikimedia sites (including possibly Wikipedia), additional scrutiny is warranted in terms of performance and security. Consult.

If your extension adds namespaces, you may wish to register its default namespaces; likewise, if it adds database tables or fields, you may want to register those at.

Please be aware that review and deployment of new extensions on Wikimedia sites can be extremely slow, and in some cases has taken more than two years.

Help documentation
You should provide public domain help documentation for features provided by your extension. is a good example. You should give users a link to the documentation via the function.

Providing support / collaboration
Extension developers should open an account on Wikimedia's, and request a new project for the extension. This provides a public venue where users can submit issues and suggestions, and you can collaborate with users and other developers to triage bugs and plan features of your extension.