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

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

• 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

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

Điều kiệ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.

Tạo trang tài liệu

Để tạo trang tài liệu bản mẫu, có 2 cách để tạo trang

• Nhấn vào liên kết [Tạo] trong hộp tài liệu trống, sẽ tự động tạo tài liệu với một mẫu được nhập sẫn trong đó. Nhập nội dung vào đó sau đó lưu để tạo tài liệu bản mẫu.
• Tạo trang con tài liệu theo cách thủ công, có tên Bản mẫu:X/doc. Xem chi tiết tại {{Documentation subpage}} hoặc bắt đầu trang bằng cách sao chép và dán văn bản wikitext mẫu sau, nhập nội dung vào đó sau đó lưu để tạo tài liệu bản mẫu:

{{Trang con tài liệu}}
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->
== Sử dụng ==


<includeonly>{{sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->

}}</includeonly>

Tạo danh sách tham số và ví dụ đầu ra của tham số đó

Để tạo một mẫu tham số trống, có thể được sao chép từ tài liệu và dán vào một trang khác, hãy sử dụng:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Để tạo một phiên bản ví dụ đầu ra của tham số trong bản mẫu, hãy sử dụng:

{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Thể loại và liên kết liên Wiki

• Để đặt bản mẫu vào một thể loại, thêm [[Thể loại:Tên thể loại]] vào bên trong phần mã <includeonly>...</includeonly> nằm trong trang con doc.
• Để tạo liên kết interwiki cho bản mẫu, truy cập Wikidata và làm theo hướng dẫn để thêm liên kết vào trang.
• Để làm cho bản mẫu tự thêm một bài viết vào một thể loại, thêm [[Thể loại:Tên thể loại]] vào bên trong phần mã <includeonly>...</includeonly> nằm trong trang bản mẫu. Vị trí chính xác trong mã bản mẫu có thể ảnh hưởng đến việc bản mẫu thêm bài viết vào thể loại.

Trực tiếp trên trang bản mẫu

Khi một trang con tài liệu chưa được tạo, có thể dùng tham số |content= trong {{Tài liệu}} để tạo tài liệu trên chính trang bản mẫu, bạn cũng có thể đặt bản mẫu vào một thể loại bằng cách thêm [[Thể loại:Tên thể loại]] bên trong bản mẫu tài liệu, sau nội dung. Ví dụ:

<!--Last line of your template code--><noinclude>
{{Tài liệu
 | content =
<!-- Nội dung tài liệu -->

[[Thể loại:Tên thể loại]]
[[Thể loại:Tên thể loại 2]]
}}</noinclude>

Xem thêm

• {{Tài liệu}} – Giúp nhúng trang tài liệu vào trang bản mẫu
• {{Trang con tài liệu}} – Đặt ở đầu mỗi trang con tài liệu để thông báo rằng đây là một trang tài liệu bản mẫu, và giúp liên kết đến bản mẫu chính
• Đọc về <noinclude> và <includeonly> tại Meta
• {{Chưa có tài liệu}}