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. 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.
 *  – 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 để biết thêm thông tin.
 *  – 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ư  hoặc   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.
 *  – .  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.
 *  – 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.
 *  – 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 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 cần sử dụng nhánh  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ố  của mẫu Extension mà họ tuân theo quy ước.

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. Để thêm phần mở rộng mới của bạn vào Wiki này:



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.

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.

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.

<span id="Help_documentation">

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

<span id="Providing_support_/_collaboration">

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

<span id="See_also">

Xem thêm

 * – 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
 * – a functioning boilerplate extension, useful as a starting point for your own extension
 * Read the Example extension, base your own code on the BoilerPlate extension.
 * cookiecutter-mediawiki-extension – a cookiecutter template which generates a boilerplate extension (with variables etc.)
 * cookiecutter-mediawiki-extension – a cookiecutter template which generates a boilerplate extension (with variables etc.)
 * Allows you to get going quickly with your own extension.
 * Can also generate the BoilerPlate extension.
 * - copy specific code from them
 * – explains how your extension can provide an API to clients
 * Best practices for extensions
 * Best practices for extensions
 * Best practices for extensions