对迭代指导的补充与吐槽
评分: +53+x

序言

最近有人在英文网站上发了一篇迭代指导。许多作者信任这篇指导并希望学到迭代这种代码魔力,但已经有人在看了隔壁网站的同类指导产生了一些疑惑:为什么这些指导上的内容互有冲突?这篇文章正准备指出英站迭代指导的诸多愚蠢错漏之处,并为中文站作者给出一些正确的指导。

这篇文章引用了Be the worthyBe the worthy对迭代指导的翻译,事实上中译版的本地化做得非常不错,可惜原文水平实在不佳。

何为迭代?

迭代指导的第一小段就令人喷饭。

迭代是一构建在Wikidot的一名为“Listpages”的模块之上的功能。这一功能利用了网站上的一种特殊页面种类,即“段落(fragment)”页面。如果没有直连的链接,段落页对任何人都是不可见的。段落页是另一构建在Wikidot之上的功能,最常见的用法就是迭代,当然也可以用于其他页面里,比如版式(theme)或被include引用。它们不会在首页的“最近新增的页面”之上显示,或者出现于最高评分的页面里。

好吧,这一段的标题是“何为迭代”,但……这段不知所谓的文字根本没有解释清楚迭代是什么,甚至也没有解释清楚段落页是什么。

所以到底啥是迭代?

我们知道,ListPages模块可以用于列出页面的标题、链接和内容等等。迭代的本质就是一个列出页面内容、且列表长度为1的ListPages模块,该模块的列表顺序由链接控制,因此可以做到改变页面链接(加上/offset/数字)、显示的页面内容随之改变的效果。

那么段落页有什么用?

段落页其实完全没有特殊的特性,也并非“构建在Wikidot之上的功能”,它们需要使用fragment分类、加上段落标签、设置父页面都只是出于两个目的:令网站管理方便、令ListPages模块抓取方便。段落页用于放置内容的段落,在迭代的情况下,一个迭代对应建立一个段落页。

如何使用迭代?

好吧,现在你已经知道迭代如何运作了,我们也定义了一些新词汇,于是现在是时候把它们放进你的页面里了。

不好意思,我觉得原文的写法完全没有解释迭代如何运作……而且非常莫名其妙的是,原作者应该认为读者已经知道迭代如何运作了,却又在这句话之后写了一串冗长的比喻来解释迭代如何运作。

那么现在我们来看看迭代指导里的使用方法与相关注释是否正确。

所有你需要为了创建你的父页面去做的就是创建一个标准的页面。举个例子,你现在正处于http://backrooms-wiki-cn.wikidot.com/offset-guide这个页面上。而如果你在沙盒站里的话——那儿有个Wikidot的bug,你需要给页面名前加上“collab:”才能让它管用。举同一个例子,沙盒站里的这篇文的链接得是http://backroomssandboxcn.wikidot.com/collab:offset-guide。对,这同时也代表着其他人也可以编辑父页面了,但这是严重的违规行为。请把你遇到的未经许可的编辑报告给职员,涉事者将被相应处理。

且不说恐怖的加粗链接,这一段还算正确:在沙盒创建迭代时,必须使用合作分类。但虽然Wikidot素有Bugdot的威名,应该说这顶多算是Wikidot用户权限的设计问题:网站成员设置父页面需要相应分类允许所有网站成员编辑,此时的权限与页面创建者无关。

(如果有需要的话,在此插入版式)

[[module css]]
(如果有需要的话,在此插入所有贯穿整个文章的CSS代码)
[[/module css]]

[[>]]
[[module rate]]
[[/>]]

[[module ListPages  category="fragment" parent="." limit="1" order="created_at" offset="@URL|0"]]
%%content%%
[[/module]]

------
[[>]]
[[collapsible show="著作信息" hide="隐藏著作信息"]]
[[*user 你的Wikidot用户名]]

(在此给出使用的图片的图源)

[[/collapsible]]
[[/>]]

这是原文给出的页面模板。应该说,照着这个模板与后续的提示操作应该没什么问题,但操作指南实在是太冗长了,像是往页面上堆豆腐块。让我们把这个模板拆解开来解释一下迭代的原理细节。

实际上,主页面的结构是这样的:

(在迭代部分前面出现的东西)

ListPages模块

(在迭代部分后面出现的东西)

当页面链接改变,只有ListPages模块显示的内容发生改变,模块前后的东西都会保留。因此,如果所有迭代的主题版式、其他CSS样式、评分模块等都保持一致,它们应该被置于主页上。一般来讲著作信息要出现在每个迭代的尾部,那么就把它放在主页面上的ListPages模块之后。

ListPages模块的设置

其实这部分内容隔壁网站的指导细致地介绍过了,Wikidot文档里更是把所有有用的没用的都列出来了,但虽然本文是锐评,没有干货也不好,那就再讲一遍。

这个ListPages模块是迭代的核心,前面提到过,迭代的原理就是通过改变页面链接控制这个模块的内容改变。

[[module ListPages category="fragment" parent="." limit="1" order="created_at" offset="@URL|0"]]
%%content%%
[[/module]]

  • category="fragment":抓取fragment:分类的页面。合规段落页用的都是fragment:分类。
  • parent=".":抓取的页面需要把父页面设为ListPages模块所在的那个页面,简单来说就是只抓子页面。
  • limit="1":一次只显示一个列表项。这是为什么你一次只能看见一个段落页的内容。
  • order="created_at":以创建顺序排列列表项。如果你用的是这样的ListPages模块,那么段落页必须按顺序创建
  • %%content%%:显示列表项的页面内容,也就是让段落页的全部内容显示在主页面上。

一些细节

注意:每次你编辑段落页时,你都需要空编辑一次父页面以刷新。一个BUG可能会导致整个页面不可逆地停摆,你肯定不想冒这个险对吧。再说一遍,每编辑一次段落页之后都空编辑一次父页面。

别信这个警告。Wikidot甚至不会把空编辑保存为新版本,这只是个没什么用的强制刷新操作。如果有什么Bug导致页面不可逆地停摆,只能说是迭代指导写太差导致读者操作错了。

疑难解答

评分与讨论并未保持一致

一个常见的错误就是用了连向段落页的链接而非这个特殊的链接,如果那样的话,在进入新页面后无法保留评分和讨论,不应该是那样的。你的页面要是出错了,就再检查一遍你用的是这个特殊的链接还是连向段落页的链接。另外,标准的三括号链接不适配迭代链接,也就是说你必须得用单括号链接。

如果你的评分和讨论在下个迭代并未保持一致,首先确保你链接的是下个迭代而非段落页。带你到下个迭代的链接应该是长这样的:http://backrooms-wiki-cn.wikidot.com/offset-guide/offset/1,而非这样的:http://backrooms-wiki-cn.wikidot.com/fragment:offset-guide-1

我猜是因为原文写得太豆腐块了,作者不得不把一样的东西写两遍来吸引注意力。

迭代链接引到了一个空页面

如果迭代链接失效了,首先确认你的链接没打错。迭代链接应当和父页面链接一致,除了结尾的“/offset/1”(或者其他数字,如果有多个迭代的话)。如果链接仍然无效,请确保你的代码是这样的:……

啊,对不起,实际上他写了差不多三回啊三回。后面的东西我就不复制了,因为这几段重复来重复去的啰嗦废话其实含有错误。让我们来看看正确的操作方法,假设你主页面的链接是这个:

http://backrooms-wiki-cn.wikidot.com/pagename

那么,在段落页0放置以下几种链接都可以让主页面里ListPages模块的内容变成段落页1的:

[http://backrooms-wiki-cn.wikidot.com/pagename/offset/1 下一迭代]

[[[http://backrooms-wiki-cn.wikidot.com/pagename/offset/1|下一迭代]]]

[/pagename/offset/1 下一迭代]

如果是完整链接,则单方括号和三方括号形式的链接都可以使用。不过,此处只有单方括号链接支持短链,最前面的斜杠也不能漏。除了这三种链接,你还可以使用[[a]]标签切换页面,[[a]]的工作机制和原生HTML的<a>几乎完全一致,它支持原生<a>的大部分属性。

实际操作中最推荐的用法是单方括号短链,因为使用单方括号短链时,不需要在发布时把那么多backroomssandboxcn修改成backrooms-wiki-cn

迭代顺序混乱

如果你在创建段落页时失手建错顺序了,则会导致迭代顺序混乱。这时可能没必要把所有段落页删了重建或者互换代码,在主页面小改一下代码就行。

  • 如果你的迭代数量<10段落页的链接按数字顺序排列,那么你可以将ListPages模块里的order="created_at"改成order="name"
  • 如果你把所有迭代顺序搞反了,那么把order="created_at"改成order="created_at desc"就行。

小提示和小技巧

迭代指导提供了一些小提示和小技巧,本文将提供一些对原文的小提示和小技巧的吐槽。

切换版式

去掉主页面的版式引用,在迭代页分别引用版式即可。

切换字体

虽然有漂亮的CSS或者HTML可以做到这一点,但和代码作斗争非常而且。真正的大佬都在用迭代。如果你想要使用一种难以阅读的字体,并提供一种更易检阅的代替方案,那是时候使用迭代了!

从这段文字就可以看出原作者水平不咋地了。

制作更易检阅的替代版本时,应该尽可能避免把正文复制一遍,否则当你希望修改文章或者仅仅只是捉个虫时都得改两遍。如果只是改字体,那么你只需要把整个正文放在主页面ListPages以外的部分,把引入字体的CSS模块放进段落页。

密码锁

在迭代指导里头塞完全没有教程的JavaScript部分应该会造成相当一部分读者的迷惑……我的建议是去MDN、w3school这类免费的前端教程网站上学习相关代码。这些东西和迭代无关。

弹出式CSS过渡

莫名其妙,一堆废话。

原作者把CSS动画(animation)称作CSS过渡(transition),还把一张简单的gif图称为视频(video),效果本身更是一言难尽。


总结

恭喜!你已经通过了有关你所需要知道的段落页和迭代的速用课程。迭代是一种高人气且引人注目的小技巧,可以用于许多情境中。希望这篇指导可以移除迭代难如登天,只有CSS大师和代码大佬才能使用的偏见。

这真的是一位技术版主写出来的文章吗?

说真的,建议向隔壁的活跃技术版主泡芙塔CroquemboucheCroquembouche学学,他写的指导比这玩意实用多了。


评分: +53+x

by Dr HormressDr Hormress

除非特别注明,本页内容采用以下授权方式: Creative Commons Attribution-ShareAlike 3.0 License