Wikipedia:Tài liệu bản mẫu

Bách khoa toàn thư mở Wikipedia
Jump to navigation Jump to search
Viết tắt

Bản mẫu là một tính năng mạnh mẽ của MediaWiki, nhưng cũng là thứ khó hiểu đối với nhiều thành viên. Ngay cả các thành viên có kinh nghiệm đôi khi cũng gặp khó khăn để hiểu được những bản mẫu với cú pháp phức tạp. Vì thế, mỗi bản mẫu thường có một trang tài liệu đi kèm để giải thích thêm, cũng như để hướng dẫn sử dụng.

Tài liệu bản mẫu cần giải thích được mục đích, cách sử dụng của bản mẫu, sao cho để những thành viên không có kiến thức đầy đủ về cú pháp bản mẫu – vốn chiếm số đông thành viên – vẫn có thể sử dụng bản mẫu được đúng cách.

Những nội dung trong tài liệu bản mẫu[sửa mã nguồn]

  • Mục đích của bản mẫu
  • Cách sử dụng, mô tả các tham số
  • Ví dụ sử dụng
  • Dữ liệu bản mẫu
  • Các bản mẫu khác có liên quan, nếu có
  • Các thể loại. Để việc phân loại bản mẫu được đúng, các thể loại cần được kẹp giữa cặp thẻ <noinclude>...</noinclude> nếu chúng nằm tại trang bản mẫu, hoặc giữa cặp thẻ <includeonly>...</includeonly> nếu chúng nằm tại trang con tài liệu.

Các liên kết ngôn ngữ trước đây cũng thuộc tài liệu bản mẫu, nhưng nay đã được lưu trữ tại Wikidata.

Ưu điểm[sửa mã nguồn]

Tài liệu bản mẫu thường được đặt ở trang con của chính bản mẫu đó, sau đó nội dung trang con được nhúng vào và hiển thị ở trang bản mẫu chính. Việc làm này giúp tách rời nội dung hướng dẫn sử dụng ra một trang riêng, rời khỏi mã nguồn của bản mẫu (vốn đã phức tạp). Điều này cho phép các bảo quản viên có thể khoá các bản mẫu khi cần thiết mà vẫn cho phép mọi thành viên cập nhật tài liệu hướng dẫn.

Ngoài ra, cách làm này cũng được các nhà phát triển phần mềm MediaWiki khuyến khích, vì nó giúp cải thiện hiệu năng làm việc của bản mẫu so với cách làm trước đó. Trước đó, phần mã bản mẫu và hướng dẫn sử dụng nằm một chỗ ở ngay trang bản mẫu (với phần văn bản hướng dẫn sử dụng nằm kẹp giữa cặp thẻ <noinclude>...</noinclude>), điều này làm tăng thời gian cần thiết cho phần mềm đọc bản mẫu để hiển thị nó, và không có lợi về mặt kĩ thuật.

Cách tạo trang tài liệu bản mẫu[sửa mã nguồn]

Để duy trình tính thống nhất, tài liệu bản mẫu ở Wikipedia tiếng Việt được tạo ở trang con /doc của bản mẫu mà nó thuyết trình. Nghĩa là nếu tên bản mẫu là Bản mẫu:X, thì trang tài liệu cần được viết ở Bản mẫu:X/doc.

Cùng lúc đó ở trang bản mẫu chính (Bản mẫu:X), ở phần kết thúc bản mẫu cần có dòng mã sau:

[--dòng cuối cùng của mã bản mẫu--]<noinclude>
{{Tài liệu}}
<!--Xin hãy thêm thể loại vào trang con /doc, đừng thêm vào đây!-->
</noinclude>

Đoạn mã này sẽ nhúng trang tài liệu vào bản mẫu, giúp nội dung thuyết trình hiện ra tại trang bản mẫu.

Quan trọng: Cần phải đặt thẻ <noinclude> ngay sau kí tự cuối cùng của mã bản mẫu, đừng xuống dòng hoặc để thừa ra kí tự trắng nào. Nếu không, kí tự trắng hoặc kí tự xuống dòng thừa vô tình sẽ được nhúng vào tất cả các trang có sử dụng bản mẫu – đây là điều không mong muốn.

Xem thêm[sửa mã nguồn]