全站通知:

帮助:模板

来自上古卷轴5天际WIKI_BWIKI_哔哩哔哩
(重定向自模板
跳到导航 跳到搜索
Wiki建设
编辑规范、帮助
翻译规范

帮助:模板导航

模板是一段可复用的文字或代码,是编写Wiki的利器。

本文将综述我们的模板,包括使用场景和设计思想,旨在为模板使用者和维护者提供参考。

要了解如何使用模板,请参阅:

本文假设读者掌握模板的基本概念和使用方法。

模板简介

基础模板

被大量页面使用的基础模板

  • 模板:面包屑 : 提供面包屑导航,基础页面操作。几乎每个页面都需要。
  • 模板:施工中 : 标注页面状态,目前Wiki在建设中,施工中页面可以以此标记自己。

显示模板

  • 模板:协议:显示内容/页面来源,标明授权协议。

排版模板

显示整活 文字。

控件模板

资源模板

  • 模板:CSS:为页面引入CSS文件,限制:只允许使用MediaWiki命名空间中的CSS文件。
  • 模板:JS:为页面引入JS文件,限制:只允许使用MediaWiki命名空间中的JS文件。
  • 模板:ResourceLoader:为页面加载资源,使用时应当使用模板CSS或者JS。

文件模板

  • 模板:文件版权: 说明文档来源与游戏或官方Wiki。
  • 模板:协议:部分其他来源,或来自官方Wiki的图需要说明来源链接和协议,需要使用此模板,参见文件上传页面或已有文件。

特殊模板

  • 模板:模板帮助: 所有的模板都应使用此模板,请参考其说明。
  • 模板:导航:提供导航表格
  • 模板:导航行:导航模板的子模版


设计原则

设计模板应至少遵循以下原则。

单一功能原则

每个模板只提供一个功能,即“高内聚低耦合”。

如果一个模板提供多个功能,或者做多个事情,有以下缺点:

  • 增加理解困难:看一个模板=看十个
  • 增加维护困难:难以确定修改的影响。一个地方出错,其他功能也会受影响。
  • 增加测试困难:测试一个功能很简单,测试一堆可能相互影响的功能很困难。

典型的负面例子是BWiki的模板:板块。 它提供了13个模板的功能。

如果修改其中一个子功能时出现了语法错误,导致分配功能的Switch提前结束,可能的异常表现是位于子功能代码后边的所有功能失效。 这会对分析、定位问题带来很大困难。

KISS原则(Keep It Simple Stupid)

设计应当保持简洁、单纯,不加入非必要的复杂性[1]

  • 不复杂化代码
  • 不过度设计
  • 不过早优化
  • 不断重构

KISS原则最后的S并没有任何隐涵开发者是愚蠢的含义,而是恰好相反的要求模板的设计是易使人理解的。

再复杂的模板,其使用者和未来的维护者也是广泛的BWiki用户。我们不能假设所有用户都是MediaWiki的使用专家。

设计和开发模板时,每多使用一个特性,就引入了一个新知识。这会增加对维护者的要求,使用者也更难理解模板的行为和工作原理。 缺少使用和维护的模板会逐渐被抛弃、替换。


以天际线Wiki中导航模板的几度重构为例:

当时的天际线Wiki对导航的需求很少,早期引入的导航盒模板实现比较复杂,修改样式和细节成本较高。我们决定改造Paradox CSL Wiki的Navbox以替代早期引入的导航盒模板,这导致了导航模板的产生。

相比于导航盒模板(一个强大且冗杂的模板),Paradox的Navbox使用了更简单的实现(画几个框),此时导航盒被认为复杂、过度设计

相应的,一些Wiki对导航的需求更多更大。这时Navbox的缺点就暴露出来,此时Navbox被认为缺乏功能、设计不足

这不是说导航盒不好。而是针对简单的导航需求,Navbox使用了更简单的设计和实现,需要更少的知识和理解成本。

这不是说Navbox不好。而是针对复杂的导航需求,导航盒提供了更充分的设计和实现,提供丰富的功能和灵活表现。

需求是变化的,比如早上我想喝咖啡,但现在想来一瓶可乐。未来本Wiki一定会需要不一样的导航,我们永远相信后人的智慧。


管理原则

管理模板应至少遵循以下原则。

开放编辑

作为一个Wiki站点,我们应当尽量开放所有页面的编辑。

因此,即使是

我们应当谨慎的限制模板的编辑,需要给出充分的理由,并给出限制编辑的时间。

充分测试

在编辑模板前,应当尽量充分的测试。

比如利用沙盒模板和用户页面测试。

被广泛使用的模板出错将会影响大量页面。

提供文档

模板应当提供文档,文档应当面向使用者+维护者。

格式规范

模板应当有规范的格式、容易阅读。

比如一些模板缺乏换行(不是所有的换行都会导致生成的页面换行)。复杂的HTML或标签如果缺乏换行将会非常难阅读。

模板帮助页模式

参见Wikipedia:模板文件頁模式

上文节选:

模板文档页模式是一种机制,用来将模板帮助文档从模板源代码中安全地分离成为帮助文档页面。
这能够使得模板本身处于完全保护状态下,而说明部分保持未保护状态,让每个人仍然可以编辑模板帮助文档。
在 noinclude 中的文字会被加算到“展开前的大小 pre-expand include size”,其大小有上限(参见Wikipedia:模板限制)。

本Wiki使用 {{模板帮助}} 来提供这一模式。

我们的模板文档/模板帮助位于帮助命名空间。

命名为“帮助:模板”页的子页面,如“帮助:模板/面包屑

这将模板和帮助文档分开在两个命名空间,从而不会再特殊:模板页面看到大量文档页面。