` 标签进行存储的。
88 | """
89 |
90 | feature_name = 'help-text'
91 | type_ = 'help-text'
92 |
93 | control = {
94 | 'type': type_,
95 | 'label': '?',
96 | 'description': '帮助文本',
97 | # 可选的，这里可以告诉Draftail在编辑器中显示这些块时，使用何种元素
98 | 'element': 'div',
99 | }
100 |
101 | features.register_editor_plugin(
102 | 'draftail', feature_name, draftail_features.BlockFeature(control, css={'all': ['help-text.css']})
103 | )
104 |
105 | features.register_converter_rule('contentstate', feature_name, {
106 | 'from_database_format': {'div.help-text': BlockElementHandler(type_)},
107 | 'to_database_format': {'block_map': {type_: {'element': 'div', 'props': {'class': 'help-text'}}}},
108 | })
109 | ```
110 |
111 | 以下时主要的不同：
112 |
113 | + 这里可配置一个`element`，来告诉Draftail如何在编辑器中渲染这些块。
114 | + 这里使用的是`BlockFeature`来注册插件。
115 | + 这里使用了`BlockElementHandler`与`block_map`来设置转换。
116 |
117 |
118 | 作为可选项，也可使用CSS类`Draftail-block--help-text`（`Draftail-block--
`），来定义块的样式。
119 |
120 | 就是这样了！其余的复杂性，就在于需要编写CSS来赋予编辑器中块的样式了。
121 |
122 |
123 | ## 新实体的创建
124 |
125 | > __警告__ 这是一项高级特性。请再三考虑是否真的需要此特性。
126 |
127 | 实体就不再简单地是一些工具栏中的格式化按钮了。他们通常需要多得多的技能，需要与APIs进行通信或请求更多的用户输入（they(entities) usually need to be much more versatile, communicating to APIs or requesting further user input）。如此等等，
128 |
129 | + 有极大可能需要编写大量的JavaScript代码，其中一些还需要React（you will most likely need to wirte a __hefty dose of JavaScript__, some of it with React）。
130 | + API是非常底层的。因此有极大可能需要一些 Draft.js 的知识（the API is very __low-level__. You will most likely need some __Draftail.js knowledge__）。
131 | + 对富文本中的UIs进行定制非常艰难。要做好在不同浏览器中进行测试而花大量时间的准备（custom UIs in rich text can be brittle. Be ready to spend time __testing in multiple browsers__）。
132 |
133 | 好消息是有了这样的底层API后，就令到第三方Wagtail插件可以在富文本功能上进行创新，带来新的体验种类。但与此同时，请考虑经由 `StreamField` 特性来实现UI，因为对于Django开发者来说，他有着经历了实战考验的API。
134 |
135 | 以下为创建新实体特性的一些主要要求：
136 |
137 | + 与内联样式及块一样，要注册一个编辑器插件。
138 | + 编辑器插件必须注册一个`source`：一个负责在编辑器中创建新实体实例的、使用Draft.js API 的React组件。
139 | + 编辑器插件还需要一个`decorator`（用于内联实体）或`block`（用于块实体）：一个负责在编辑器中显示出实体实例的React组件。
140 | + 与内联样式与块类似，要设置好到数据库及从数据的转换。
141 | + 该转换占了更大比重，因为实体包含了需要被序列化为HTML的数据。
142 |
143 | 关于React组件的编写，Wagtail将其自带的React、Draft.js与Draftail的依赖，作为全局变量加以暴露。有关此方面的详细信息，请参阅 [对客户端组件进行扩展](amdin_templates.md#extending-clientside-components)。而更深入的讨论，则请移步 [Draftail文档](https://www.draftail.org/docs/formatting-options) 以及 [Draftail导出器文档](https://www.draftail.org/docs/formatting-options)。
144 |
145 | 下面是一个详细示例，用来演示这些工具在Wagtail环境下的使用方式。为此示例目的，这里可设想某份金融报刊的新闻团队的情形。他们打算撰写有关股票市场的报道，在他们内容的任意位置对特定股票进行引用（比如在某个句子中引用 "$TSLA"），随后他们的报道中将自动完善该股票的信息（链接、数字、迷你图表等）。
146 |
147 | 编辑器工具栏将包含一个显示了可选股票清单的“股票选择器”，最后将用户的选择作为一个文本式代币进行插入。比如下面将仅随机选取一支股票：
148 |
149 | 
150 |
151 | 在发布时，这些代币将保存在富文本中。而在网站上该新闻报道被显示出来时，则将会把来自某个API的实时的市场数据，插入到各个代币旁边：
152 |
153 | 
154 |
155 | 为了实现此特性，就要像内联样式与块那样，首先对此富文本特性进行注册：
156 |
157 | ```python
158 | @hooks.register('register_rich_text_features')
159 | def register_stock_feature(features):
160 | features.default_features.append('stock')
161 |
162 | """
163 | 对该 `stock` 功能进行注册，这里使用了 `STOCK` 的 Draft.js 实体类型，同时
164 | 是以一个 ``的标签，作为HTML进行存储的。
165 | """
166 |
167 | feature_name = 'stock'
168 | type_ = 'STOKC'
169 |
170 | control = {
171 | 'type': type_,
172 | 'lable': '$',
173 | 'description': '股票',
174 | }
175 |
176 | features.register_editor_plugin(
177 | 'draftail', feature_name, draftail_features.EntityFeature(
178 | control,
179 | js=['stock.js'],
180 | css={'all': ['stock.css']}
181 | )
182 | )
183 |
184 | features.register_converter_rule('contentstate', feature_name, {
185 | # 这里请注意，数据库转换要比内联样式及块更为复杂。
186 | 'from_database_format': {'span[data-stock]': StockEntityElementHandler(type_)},
187 | 'to_database_format': {'entity_decorators': {type_, stock_entity_decorator}},
188 | })
189 | ```
190 |
191 | `EntityFeature`上的 `js` 与 `css` 关键字，可用于指定额外的、于此功能出于活动状态时进行加载的JS与CSS文件。二者都是可选的。他们的值被添加到一个`Media`对象，有关这些对象的更多文档，在 [Django表单资源文档](https://docs.djangoproject.com/en/stable/topics/forms/media/) 中可以找到。
192 |
193 | 因为实体保有数据，因此到数据库及从数据库的转换格式，就要更为复杂。这里就必须创建这两个转换处理器：
194 |
195 | ```python
196 | from draftjs_exporter.dom import DOM
197 | from wagtail.admin.rich_text.converters.html_to_contentstate import InlineEntityElementHandler
198 |
199 | def stock_entity_decorator(props):
200 | """
201 | Draft.js 的 ContentState 格式到数据库的HTML。
202 | 将 STOCK 实体，转换为一个 span 标签。
203 | """
204 |
205 | return DOM.create_elment('span', {
206 | 'data-stock': props['stock'],
207 | }, props['children'])
208 |
209 |
210 | class StockEntityElementHandler(InlineEntityElementHandler):
211 | """
212 | 数据库的HTML到Draft.js的ContentState格式。
213 | 将该 span 标签，以正确的数据，转换为一个 STOCK 实体。
214 | """
215 |
216 | mutability = 'IMMUTABLE'
217 |
218 | def get_attribute_data(self, attrs):
219 | """
220 | 从 "data-stock" HTML属性取得 `'stock'` 的值。
221 | """
222 |
223 | return {
224 | 'stock': attrs['data-stock'],
225 | }
226 | ```
227 |
228 | 注意这里他们是如何完成类似的转换，使用的却是不同的APIs. `to_database_format`是使用 [Draft.js 的导出器](https://github.com/springload/draftjs_exporter) 组件的 API 构建的，而 `from_database_format` 则使用了一个 Wagtail 的 API.
229 |
230 | 下一步就是将 JavaScript 进行添加，来定义出创建实体的方式（也就是 `source`）与其显示的方式（`decorator`）。在 `stock.js` 中，定义了数据源组件：
231 |
232 | ```javascript
233 | const React = window.React;
234 | const Modifier = window.DraftJS.Modifier;
235 | const EditorState = window.DraftJS.EditorState;
236 |
237 | const DEMO_STOCKS = ['AMD', 'AAPL', 'TWTR', 'TSLA', 'BTC'];
238 |
239 | // 这并非一个真正的 React 组件 -- 在实体被渲染时，尽可能快地创建出实体。
240 | class StockSorce extends React.Component {
241 | componentDidMount() {
242 | const { editorState, entityType, onComplete } = this.props;
243 |
244 | const content = editorState.getCurrentContent();
245 | const selection = editorState.getSelection();
246 |
247 | const randomStock = DEMO_STOCKS[Math.floor(Math.random() * DEMO_STOCKS.length)];
248 |
249 | // 使用 Draft.js 的API、以正确的数据来创建一个新的实体。
250 | const contentWithEntity = content.createEntity(entityType.type, 'IMMUTABLE', {
251 | stock: randomStock,
252 | });
253 | const entityKey = contentWithEntity.getLastCreatedEntityKey();
254 |
255 | // 这里还要添加一些将要激活的实体的一些文本。
256 | const text = `${randomStock}`;
257 |
258 | const newContent = Modifier.replaceText(content, selection, text, null, entityKey);
259 | const nextState = EditorState.push(editorState, newContent, 'insert-characters');
260 |
261 | onComplete(nextState);
262 | }
263 |
264 | render() {
265 | return null;
266 | }
267 | }
268 | ```
269 |
270 | 此源数据组件，使用了由 [Draftail](https://www.draftail.org/docs/api) 所提供的数据与回调。其还使用了来自全局变量的依赖 -- 请参阅 [对客户端组件进行扩展](admin_templates.md#extending-clientside-components)。
271 |
272 | 随后创建出装饰器组件：
273 |
274 | ```javascript
275 | const Stock = (props) => {
276 | const { entityKey, contentState } = props;
277 | const data = contentState.getEntity(entityKey).getData();
278 |
279 | return React.createElement('a', {
280 | role: 'button',
281 | onMouseUp: () => {
282 | window.open(`https://finance.yahoo.com/quote/${data.stock}`);
283 | },
284 | }, props.children);
285 | };
286 | ```
287 |
288 | 这是一直白的 React 组件了。其并未使用 JSX, 因为这里不打算非得要为这些JavaScript代码而使用一个构建步骤。其使用了 ES6 的语法 -- 在Internet Explorer 11 中无法运行，除非使用一个构建步骤转换到 ES5 的语法。
289 |
290 | 最后将这些 JS组件注册到插件：
291 |
292 | ```javascript
293 | window.draftail.registerPlugin({
294 | type: 'STOCK',
295 | source: StockSource,
296 | decorator: Stock,
297 | });
298 | ```
299 |
300 | 就是这样了！该项设置的所有代码，将在站点前端上最终生成以下的HTML：
301 |
302 | ```html
303 |
304 | Anyone following Elon Mask's $TSLA should also look into $BTC.
305 |
306 | ```
307 |
308 | 为了最终完成该示例，这里可将一点 JavaScript 代码加入到前端，从而给这些代币装饰上一些链接与迷你图表：
309 |
310 | ```javascript
311 | [].slice.call(document.querySelectionAll('data-stock')).forEach((elt) => {
312 | const link = document.createElement('a');
313 | link.ref = `https://finance.yahoo.com/quote${elt.dataset.stock}`;
314 | link.innerHTML = `${elt.innerHTML}`;
315 |
316 | elt.innerHTML = '';
317 | elt.appendChild(link);
318 | });
319 | ```
320 |
321 | 也可以创建定制块（请参阅单独的 [Draftail 文档](https://www.draftail.org/docs/blocks)），但关于定制块的创建，这里不再赘述，因为在 Wagtail 中， [StreamField](https://wagtail.xfoss.com/topics/streamfield.html#streamfield) 是创建块级别富文本的最佳方式。
322 |
323 |
324 | ## Draftail小部件的集成
325 |
326 | 为更进一步对 Draftail 小部件集成到UI的方式加以定制，有着以下的 CSS与JS的额外扩展点：
327 |
328 | + 在 JavaScript中，使用 `[data-draftail-input]` 属性选择器，来选定带有数据的输入，并使用对封装了编辑器的元素，使用 `[data-draftail-editor-wrapper]` 属性（in JavaScript, use the `[data-dratail-input]` attributes selector to target the input which contains the data, and `[data-dratail-editor-wrapper]` for the element which wraps the editor）。
329 | + 编辑器实例是绑定在某个必将访问的输入字段上的。使用`document.querySelector('[data-draftail-input]').draftailEditor`（the editor instance is bound on the input field for imperative access. Use `document.querySelector('[data-draftail-input]').draftailEditor`）。
330 | + 在 CSS中，使用以`Draftail-`作为前缀的类（in CSS, use the classes prefixed with `Draftail-`）。
331 |
--------------------------------------------------------------------------------
/topics/pages.md:
--------------------------------------------------------------------------------
1 | # 页面模型
2 |
3 | **Page models**
4 |
5 | Wagtail中的每种页面类型（又名“内容类型”），都是由一个Django的模型所表示的（each page type(a.k.a. content type) in Wagtail is represented by a Django model）。所有页面模型，都必须从`wagtail.core.models.Page`类继承。
6 |
7 | > **注** Django模型，就是一个类的数据结构，对应着数据库中的一个表。Python类与数据库之间存在一个对象关系模型的抽象，对页面的修改，经由 migrate 命令，最终反映到数据库中。
8 |
9 | 因为所有页面类型都是Django模型，那么就可以使用Django所提供的所有字段类型。请参阅[模型字段参考](https://docs.djangoproject.com/en/stable/ref/models/fields/)，了解所有可用字段清单。此外，Wagtail还提供了一个`RichTextField`字段，该字段提供了一个可用于编辑富文本内容的所见即所得的编辑器。
10 |
11 | **关于Django的模型**
12 |
13 | 如对Django模型尚不熟悉，那么请快速浏览以下链接，以获得基本的掌握：
14 |
15 | + [创建模型](https://docs.djangoproject.com/en/stable/intro/tutorial02/#creating-models)
16 | + [模型的语法](https://docs.djangoproject.com/en/stable/topics/db/models/)
17 |
18 |
19 | ## Wagtail页面模型示例
20 |
21 | 下面的示例表示一个典型的博客文章：
22 |
23 | ```python
24 | from django.db import models
25 |
26 | from modelcluster.fields import ParentalKey
27 |
28 | from wagtail.core.models import Page, Orderable
29 | from wagtail.core.fields import RichTextField
30 | from wagtail.admin.edit_handlers import FieldPanel, MultiFieldPanel, InlinePanel
31 | from wagtail.images.edit_handlers import ImageChooserPanel
32 | from wagtail.search import index
33 |
34 | class BlogPost(Page):
35 |
36 | # 数据库字段
37 |
38 | body = RichTextField()
39 | date = models.DateField("发布日期")
40 | feed_image = models.ForeignKey(
41 | 'wagtailimages.Image',
42 | null=True,
43 | blank=True,
44 | on_delete=models.SET_NULL,
45 | related_name="+"
46 | )
47 |
48 | # 搜索功能索引的配置
49 |
50 | search_fields = Page.search_fields + [
51 | index.SearchField('body'),
52 | index.FilterField('date'),
53 | ]
54 |
55 | # 编辑器面板的配置
56 |
57 | content_panels = Page.content_panels + [
58 | FieldPanel('date'),
59 | FieldPanel('body', classname="full"),
60 | InlinePanel('related_links', label="相关链接"),
61 | ]
62 |
63 | promote_panels = [
64 | MultiFieldPanel(Page.promote_panels, "一般性页面配置"),
65 | ImageChooserPanel('feed_image'),
66 | ]
67 |
68 | # 父页面/子页面类型规则
69 |
70 | parent_page_types = ['blog.BlogIndex']
71 | subpage_types = []
72 |
73 | class BlogPageRelatedLink(Orderable):
74 | page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name='related_links')
75 | name = models.CharField(max_length=255)
76 | url = models.URLField()
77 |
78 | panels = [
79 | FieldPanel('name'),
80 | FieldPanel('url'),
81 | ]
82 | ```
83 |
84 | > **要点** 请确保字段名称与类的名称保持不同。那会因为Django处理对象关系的机制（[了解更多有关此方面的信息](https://github.com/wagtail/wagtail/issues/503)），而导致出错。在上面的示例中已经通过将`Page`追加到各个模型名称之后，避免了这个问题。
85 |
86 |
87 | ## 编写页面模型
88 |
89 | 这里将对上面的实力中的各个部分进行逐一讲解，以帮助建立自己的页面模型。
90 |
91 |
92 | ### 数据库字段
93 |
94 | 每种Wagtail页面类型，都是一个Django模型，在数据库中表现为单个表。
95 |
96 | 每个页面类型，都可以有他自己的一套字段。比如一篇新闻报道可能具有文章主题文本与发布日期，而某项活动则可能需要单独的活动地点及开始/结束时间字段。
97 |
98 | 在Wagtail中，可以使用所有的Django字段类。同时由第三方应用所提供的绝大多数字段类同样可以工作。
99 |
100 | Wagtail还提供了一些他自身的字段类：
101 |
102 | + `RichTextField` -- 用于富文本内容
103 | + `StreamField` -- 一种基于块的内容字段（参见：[使用`StreamField`的自由格式页面内容](topics/streamfield.md)）
104 |
105 | 对于标签化特性，Wagtail完全支持[django-taggit](https://django-taggit.readthedocs.org/en/latest/)，因此建议使用该现成的库。
106 |
107 |
108 | ## 搜索功能
109 |
110 | 页面模型中的`search_fields`属性，定义了哪些字段要被加入到搜索索引，以及他们如何被索引。
111 |
112 | 该属性影视一个`SearchField`与`FilterField`对象的清单。其中`SearchField`将某个字段加入到全文搜索。`FilterField`则是将某个字段加入到结果过滤中（`FilterField` adds a field for filtering the results）。字段可被`SearchField`与`FilterField`同时索引（但只能每个索引只能有一个实例）。
113 |
114 | 在上面的示例中，将`body`字段进行了全文搜索索引，将`date`字段做了过滤索引。
115 |
116 | 这些字段类型所接受的参数，在[对额外字段进行索引](topics/search/indexing.md#wagtailsearch-indexing-fields)中进行了文档说明。
117 |
118 | ### 编辑器面板
119 |
120 | 对于页面的这些字段如何在页面编辑器界面的安排，有着几个属性：
121 |
122 | + `content_panels` -- 用于内容，比如文章主题文本
123 | + `promote_panels` -- 用于元数据，比如标签、缩略图及搜索引擎优化的标题等
124 | + `settings_panels` -- 用于相关设置，比如发布日期等
125 |
126 | 每个这些属性，都被设置为了一个`EditHandler`对象的清单，该清单定义了哪些字段将出现在哪个分页上，以及这些字段在各个分页上的结构方式。
127 |
128 | 下面是这些Wagtail自带的`EditHandler`类的简介。请参阅[可用的面板类型](reference/pages/panels.md)，了解他们的完整介绍。
129 |
130 | ### 基本面板（Basic）
131 |
132 | 基本面板实现模型字段的编辑。`FieldPanel`类会基于字段类型，来选择适当的小部件，而`StreamField`字段则就需要使用特殊面板类。
133 |
134 | + `FieldPanel`
135 | + `StreamFieldPanel`
136 |
137 | ### 结构化面板（Structural）
138 |
139 | 这类面板用于对界面中的字段进行结构组织。
140 |
141 | + `MultiFieldPanel` -- 用于将相似字段分组到一起
142 | + `InlinePanel` -- 用于将子模型置于行内化（For inlining child models）
143 | + `FieldRowPanel` -- 用于将多个字段组织为单个的行
144 |
145 | ### 选择器面板（Chooser）
146 |
147 | 到某些确切模型的`ForeignKey`字段，可以使用以下的那些 `ChooserPanel` 类之一。这些面板把美观的模态选择器对话框界面加入进来，同时图片/文档选择器还允许在不离开页面编辑器的情况下，进行新文件的上传。
148 |
149 | + `PageChooserPanel`
150 | + `ImageChooserPanel`
151 | + `DocumentChooserPanel`
152 | + `SinippetChooserPanel`
153 |
154 | > **注意** 要使用这些选择器，字段所链接到的模型，就必须是某个页面、图片、文档或内容块。
155 | > 对于链接到其他模型类型的情况，就应使用`FieldPanel`了，这时将创建出一个下拉选择框。
156 |
157 | ## 对页面编辑器界面进行定制
158 |
159 | 页面编辑器可被深度定制，请参阅 [定制编辑接口](advanced_topics/customisation/page_editing_interface.md)。
160 |
161 |
162 | ## 父页面/子页面的类型规则
163 |
164 | **Parent page / subpage type rules**
165 |
166 | 下面的两个属性，可实现在站点中何处使用何种页面类型的控制。允许定义出如同“博客条目只能创建于博客首页下”这样的规则。
167 |
168 | 两条属性都取的是模型类或模型名称的清单。模型名称的格式为 `app_label.ModelName`。在省略了 `app_label`时，假定就是同样的应用。
169 |
170 | + `parent_page_types` 限制本类型可在哪些页面类型之下创建
171 | + `subpage_types` 限制在本类型下可以创建哪些页面类型
172 |
173 | 默认情况下，在所有页面类型之下，可以创建任意的页面类型，而如果要的就是这种效果的话，就没有必要设置这些属性。
174 |
175 | 将`parent_page_types`设置为空的清单，是一种阻止在编辑器界面创建出某个特定页面类型的好做法。
176 |
177 |
178 | ## 页面模型的URL模式的定制
179 |
180 | 通常不会直接调用`Page.get_url_parts(request)`，但为了给某个给定的页面模型定义定制的URL路由，是可以覆写该方法的（the `Page.get_url_parts(request)` method will not typically be called directly, but may be overridden to define custion URL routing for a given page model）。该方法会返回一个`(site_id, root_url, page_path)`的元组，该元组为`get_url`与`get_full_url`（下面可以看到）用来构造他和给定的页面URL类型。
181 |
182 | 在覆写`get_url_parts()`方法时，需接受`*args, **kwargs`:
183 |
184 | ```python
185 | def get_url_parts(self, *args, **kwargs):
186 | ```
187 |
188 | 并在调用`super`（如有 `super`）上的`get_url_parts`方法处，将`*args, **kwargs`传递过去，比如：
189 |
190 | ```python
191 | super().get_url_parts(*args, **kwargs)
192 | ```
193 |
194 | 虽然可以只传递`request`关键字参数，但将所有这些参数按原样进行传递，可确保在以后这些方法签名发生改变时保持兼容性。
195 |
196 | 有关更多此方面的信息，请参阅 [`wagtail.core.models.Page.get_url_parts()`](reference/pages/model_reference.md#wagtail.core.models.Page.get_url_parts)。
197 |
198 | ### 获取页面实例的URLs
199 |
200 | 在需要某个页面的URL时，可调用`Page.get_url(request)`方法。在该方法能够探测到页面位于当前站点（通过 `request.site`）的情况下，其默认返回的是本地URLs（不包含协议或域名）；否则将返回一个包含了协议与域名的完整URL。为了开启站点级别的URL信息的每次请求缓存，以及为了实现本地URLs的生成，应尽可能将可选参数`request`包含进去（whenever possible, the optional `request` argument should be included to enable per-request caching of site-level URL information and facilitate the generation of local URLs）。
201 |
202 | `get_url(request)`的一个常见用例，就是在项目中包含了用于生成导航菜单的所有定制模板标签中。在编写这样的定制模板标签时，要确保这些标签包含有`takes_context=True`，及确保他们都用到了`context.get('request')`，从而安全地传递上请求，或在上下文中不存在请求时，要传递`None`（A common use case for `get_url(request)` is in any custom template tag your project may include for generating navigation menus. When writing such a custom template tag, ensure that it includes `takes_context=True` and use `context.get('request')` to safely pass the request or `None` if no request exists in the context）。
203 |
204 | 有关此方面的更多信息，请参阅[wagtail.core.models.Page.get_url()](reference/pages/model_reference.md#wagtail.core.models.Page.get_url)。
205 |
206 | 在需要完整的URL（包含协议与域名）时，可使用`Page.get_full_url(request)`方法。同样应尽可能包含`request`参数，为的是启用站点级别的URL信息的历次请求的缓存。有关此方面的更多信息，请参阅[wagtail.core.models.Page.get_full_url()](reference/pages/model_reference.md#wagta il.core.models.Page.get_full_url)
207 |
208 | ## 模板的渲染
209 |
210 | 可以给予每个页面模型一个HTML的模板，在用户浏览到站点前端的某个页面时，模板将被渲染出来。这就是将Wagtail内容给到终端用户的最简单也是最常见方式（这不是唯一的方式哦）。
211 |
212 | ### 将某个页面模型的模板添加进来
213 |
214 | Wagtail将基于应用级别与模型类的名称，自动选择模板的名称。
215 |
216 | 格式为：`/.html`
217 |
218 | > **注** 蛇形字母写法，snake cased，参见[Snake case, wikipedia](https://en.wikipedia.org/wiki/Snake_case)
219 |
220 | 比如上面的博客页面的模板将是： `blog/blog_page.html`
221 |
222 | 只需在某个可以此名称访问到的地方，创建一个模板即可。
223 |
224 | ### 模板上下文
225 |
226 | **Template context**
227 |
228 | Wagtail 将以绑定到正在渲染的页面实力上的`page`变量，来进行模板的渲染。使用该变量来访问页面的内容。比如要获得当前页面的标题，就使用`{{ page.title }}`。所有由 [上下文处理器](https://docs.djangoproject.com/en/stable/ref/templates/api/#subclassing-context-requestcontext) 提供的变量，也都是可用的。
229 |
230 | ** 模板上下文的定制 **
231 |
232 | 所有页面都有一个`get_context()`方法，在渲染模板时，都会调用到该方法，其返回值为绑定到模板变量的一个字典。
233 |
234 | 可通过覆写该方法，来讲更多变量加入到模板上下文：
235 |
236 | ```python
237 | class BlogIndexPage(Page):
238 | ...
239 |
240 | def get_context(self, request):
241 | context = super().get_context(request)
242 |
243 | # 加入额外变量，并返回更新后的上下文
244 | context['blog_entries'] = BlogPage.objects.child_of(self).live()
245 | # 注意上面就是一个 QuerySet
246 | return context
247 | ```
248 |
249 | 此时这些变量就可以在模板中加以使用了：
250 |
251 | ```python
252 | {{ page.title }}
253 |
254 | {% for enry in blog_entries %}
255 | {{ entry.titlte }}
256 | {% endfor %}
257 | ```
258 |
259 | ### 修改模板
260 |
261 | 通过在类上设置 `template` 属性，来使用一个不同的模板文件：
262 |
263 | ```python
264 | class BlogPage(Page):
265 | ...
266 |
267 | template = 'other_tempalte.html'
268 | ```
269 |
270 | **动态地选择模板**
271 |
272 | 通过在页面类上定义`get_template()`方法，可以给每个实例指定不同的模板。在每次页面被渲染时，都会调用该方法：
273 |
274 | ```python
275 | class BlogPage(Page):
276 | ...
277 |
278 | use_other_template = models.BooleanField()
279 |
280 | def get_template(self, request):
281 | if self.use_other_template:
282 | return 'blog/other_blog_page.html'
283 |
284 | return 'blog/blog_page.html'
285 | ```
286 |
287 | 在本示例中，那些设置了`use_other_template`字段的页面，将使用`blog/other_blog_page.html`模板。所有其他页面都将使用默认的`blog/blog_page.html`。
288 |
289 | ### 在页面渲染上的更多控制
290 |
291 | 所有页面类，都有一个`serve()`方法，该方法内部调用了`get_context`与`get_template`方法，进而对模板进行渲染。此方法与Django的视图函数类似，取的是一个Django `Request` 对象，返回的是一个 Django `Response` 对象。
292 |
293 | 为实现对页面渲染的完全掌控，此方法可被重写。
294 |
295 | 比如下面就是一种让页面以一个表示其自身的JSON方式进行响应的方法：
296 |
297 | ```python
298 | from django.http import JsonResponse
299 |
300 | class BlogPage(Page):
301 | ...
302 |
303 | def serve(self, request):
304 | return JsonResponse({
305 | 'title': self.title,
306 | 'body': self.body,
307 | 'date': self.date,
308 |
309 | # 将图片缩放到宽度为 300px 并取得到图片的URL
310 | 'feed_image': self.feed_image.get_rendition('width-200').url,
311 | })
312 | ```
313 |
314 | ## 内联模型
315 |
316 | **Inline models**
317 |
318 | Wagtail可在页面中嵌套其他模型的内容。对于创建那些诸如相关链接，或要以旋转木马方式显示的重复字段，此特性是有用的。内联模型的内容，与其他页面内容一样，保存在版本变更中。
319 |
320 | 每个内联模型，都有以下要求：
321 |
322 | + 必须继承自`wagtail.core.models.Orderable`
323 | + 必须要有一个到父模型的`ParentalKey`
324 |
325 | > **注意** `django-modelcluster`与`ParentalKey`的区别
326 | > 模型的内联特性，是由[`django-modelcluster`](https://github.com/torchbox/django-modelcluster)所提供的，同时必须要从这里将`ParentalKey`字段类型导入进来：
327 | > `from modelcluster.fields import ParentalKey`
328 | > `ParentalKey` 是 Django 的`ForeignKey`的一个子类，并取的是同样的参数。
329 |
330 |
331 | 比如下面的内联模型就可用于将相关链接（一个名称-url对的的列表）加入到`BlogPage`模型：
332 |
333 | ```python
334 | from django.db import models
335 | from modelcluster.fields import ParentalKey
336 | from wagtail.core.models import Orderable
337 |
338 | class BlogPageRelatedLink(Orderable):
339 | page = ParentalKey(BlogPage, on_delete=models.CASCADE, realted_name='related_links')
340 | name = models.CharField(max_length=250)
341 | url = models.URLField()
342 |
343 | panels = [
344 | FieldPanel('name'),
345 | FieldPanel('url'),
346 | ]
347 | ```
348 |
349 | 接着使用`InlinePanel`编辑面板类，将其加入到管理界面：
350 |
351 | ```python
352 | content_panels = [
353 | ...
354 |
355 | InlinePanel('related_links', label="相关链接"),
356 | ]
357 | ```
358 |
359 | `InlinePanel`类构造函数的第一个参数，必须与`ParentalKey`的`related_name`属性一致。
360 |
361 | ## 处理多个页面
362 |
363 | **Working with pages**
364 |
365 | Wagtail使用了Django的 [多表继承](https://docs.djangoproject.com/en/stable/topics/db/models/#multi-table-inheritance) 特性，来实现在相同的树中使用多个页面模型。
366 |
367 | 每个页面都会被同时加入到Wagtail内建的`Page`模型，以及其用户定义的模型（比如早先所创建的`BlogPage`模型）。
368 |
369 | 相应地，页面可以两种形式的Python代码存在，`Page`基类的示例，或页面模型的示例。
370 |
371 | 在一并处理多个页面类型时，通常使用的是Wagtail的 `Page` 模型，其不会给予到对特定于这些页面类型的那些字段的访问。
372 |
373 | ```bash
374 | # 获取数据库中的所有页面
375 | >>> from wagtail.core.models import Page
376 | >>> Page.objects.all()
377 | [, , , , ]
378 | ```
379 |
380 | > **注** 通过 `python manage.py shell` 即可进入到上面的命令行界面
381 |
382 | 在处理单个的页面类型时，就可以对用户定义的模型实例进行处理了。这样的模型实例，给予到对`Page`中所有可用字段的访问，以及对该特定类型的用户定义字段的访问。
383 |
384 | ```bash
385 | # 获取数据库中所有的博客条目
386 | >>> from blog.models import BlogPage
387 | >>> BlogPage.objects.all()
388 | [, ]
389 | ```
390 |
391 | 使用`.specfific`属性，就可以将某个`Page`对象，转换为其更为具体的用户定义的等价实体。然而这会引发一次额外的数据库查询。
392 |
393 | ```bash
394 | >>> page = Page.objects.get(title='A Blog Post')
395 | >>> page
396 |
397 |
398 | # 注意：该博客文章是 Page 的一个实例，因此不能访问到文章主体、日期或首页图片
399 |
400 | >>> page.specific
401 |
402 | ```
403 |
404 | ## 技巧
405 |
406 | ### 友好的模型名称
407 |
408 | 运用带有 `verbose_name` 属性的Django的内部`Meta`类，可令到模型名称对用户更为友好，比如：
409 |
410 | ```python
411 | class HomePage(Page):
412 |
413 | ...
414 |
415 | class Meta:
416 | verbose_name = "homepage"
417 | ```
418 |
419 | 默认情况下，在用户选择创建要创建的页面时，页面类型清单是通过将模型名称按照大写字符拆分，而生成的。那么`HomePage`模型就将被命名为“Home Page”，显然这个名字有点笨拙。在如同上面的示例中那样定义了 `verbose_name`后，就会将名称修改为“Homepage”，这样就更为习以为常一点。
420 |
421 | > verbose: 详细
422 |
423 | ### 页面QuerySet的排序
424 |
425 | 由基类`Page`所派生的模型，是 *无法* 通过使用标准的加入 `ordering` 属性到模型内部的`Meta`类上，这种标准的Django 方法，而赋予给他一种默认排序的。
426 |
427 | ```python
428 | Class NewsItemPage(Page):
429 |
430 | publication_date = models.DateField()
431 | ...
432 |
433 | class Meta:
434 | ordering = ('-publication_date', ) # 不会生效
435 | ```
436 |
437 | 这是因为`Page`是强制以路径对QuerySet进行排序的。 因此在构造一个QuerySet时，就必须显示地进行排序：
438 |
439 | ```python
440 | news_items = NewsItemPage.objects.live().order_by('-publication_date')
441 | ```
442 |
443 | ### 对页面管理器进行定制
444 |
445 | 可将定制的`Manager`类，添加到`Page`类。所有定制管理器，都应继承自`wagtail.core.models.PageManager`：
446 |
447 | ```python
448 | from django.db import models
449 |
450 | from wagtail.core.models import Page, PageManager
451 |
452 | class EventPageManager(PageManager):
453 | """ 活动页面的定制管理器 """
454 |
455 | class EventPage(Page):
456 |
457 | start_date = models.DateField()
458 |
459 | objects = EventPageManager()
460 | ```
461 |
462 | 而在仅需加入额外的 `QuerySet` 方法时，还可以从`wagtail.core.models.PageQuerySet` 继承， 并调用`from_queryset()`来构建一个定制的 `Manager` 类：
463 |
464 | ```python
465 | from django.db import models
466 | from django.utils import timezone
467 |
468 | from wagtail.core.models import Page, PageManager, PageQuerySet
469 |
470 | class EventPageQuerySet(PageQuerySet):
471 |
472 | def future(self):
473 | today = timezone.localtime(timezone.now()).date()
474 | return self.filter(start_date__gte=today)
475 |
476 | EventPageManager = PageManager.from_queryset(EventPageQuerySet)
477 |
478 | class EventPage(Page):
479 |
480 | start_date = models.DateField()
481 |
482 | objects = EventPageManager()
483 | ```
484 |
--------------------------------------------------------------------------------
/getting_started/tutorial.md:
--------------------------------------------------------------------------------
1 | # 第一个Wagtail站点
2 |
3 | > **注意** 此教程讲的是有关建立一个全新Wagtail项目的内容。如要将Wagtail加入到某个既有Django项目，请参考[将Wagtail集成到Django项目](integrating_into_django.html)。
4 |
5 | 1. 安装 Wagtail 与其依赖：
6 |
7 | ```sh
8 | $ pip install wagtail
9 | ```
10 |
11 | 2. 开始你的站点：
12 |
13 | ```sh
14 | $ wagtail start mysite
15 | $ cd mysite
16 | ```
17 |
18 | Wagtail提供了与`django-admin.py startproject` 类似的 `start` 命令。在项目中运行 `wagtail start mysite`将生成一个新的、有着几个特定于 Wagtail 的附加文件的 `mysite` 文件夹，这些文件包括了：
19 |
20 | + 所需的项目设置
21 | + 一个有着空白的 `HomePage` 模型的“主页”应用
22 | + 一些基础模板
23 | + 一个简单的“搜索”应用。
24 |
25 | 3. 安装项目依赖
26 |
27 | ```sh
28 | $ pip install -r requirements.txt
29 | ```
30 |
31 | 此步骤确保刚创建的项目具有相关版本的Django
32 |
33 | 4. 创建数据库
34 |
35 | ```sh
36 | $ ./manage.py migrate
37 | ```
38 |
39 | 在没有更新项目设置时，数据库将是项目目录中的一个 SQLite 数据库文件。
40 |
41 | 5. 创建出一个管理员用户
42 |
43 | ```sh
44 | $ ./manage.py createsuperuser
45 | ```
46 |
47 | 6. 启动服务器
48 |
49 | ```sh
50 | $ ./manage.py runserver
51 | ```
52 |
53 | 如没有什么错误的话，访问 [http://127.0.0.1:8000]() 就可以看到一个欢迎页面了：
54 |
55 | 
56 |
57 | 可在 [http://127.0.0.1:8000/admin]() 处访问到管理区
58 |
59 | 
60 |
61 | ## 对`HomePage`模块进行扩展
62 |
63 | 在此开箱即用的情况下，“主页”应用在`models.py`文件中，定义了一个空白的`HomePage`模型，以及与该空白模型一起的数据库迁移，由他们二者一起，创建出了一个主页，并将Wagtail配置为使用该主页。
64 |
65 | 按照下面这样对`home/models.py`进行编辑，将一个`body`字段加入到该模型中：
66 |
67 | ```python
68 | from django.db import models
69 |
70 | from wagtail.core.models import Page
71 | from wagtail.core.fields import RichTextField
72 | from wagtail.admin.edit_handlers import FieldPanel
73 |
74 | class HomePage(Page):
75 | body = RichTextField(blank=True)
76 |
77 | content_panels = Page.content_panels + [
78 | FieldPanel('body', classname="full"),
79 | ]
80 | ```
81 |
82 | `body` 被定义为 `RichTextField`，一种特殊的 Wagtail 字段。当然也可以使用任意的 [Django 核心字段](https://docs.djangoproject.com/en/stable/ref/models/fields/)。`content_panels` 定义了功能及编辑接口的布局（`content_panels` define the capatibilities and the layout of the editing interface）。请参考更多有关 [创建页面模型](topics/pages.html)。
83 |
84 | 此时运行 `./manage.py makemigrations`，接着 `./manage.py migrate` 命令，来用模型改变对数据库作出更新。在每次修改了模型定义时，都 **必须** 运行这两个命令。
85 |
86 | 现在就可以在 Wagtail 管理区（前往 “页面”、“主页”，然后点击“编辑”）对该主页进行编辑了。在`body`字段输入一些文字，并发布该页面。
87 |
88 | 现在就需要将对应的页面模板加以更新，以反映对模型作出的改变。Wagtail使用一般Django模块，来渲染各种页面类型。默认他将查找一个由应用与模型名称组成、以下划线表示大写字母分开的模板文件名（比如，“主页”应用中的`HomePage`模型，就成为了`home/home_page.html`）。该模板文件可存在于由 [Django的模板规则](https://docs.djangoproject.com/en/stable/intro/tutorial03/#write-views-that-actually-do-something) 所识别的任何位置；通常他是放在一个应用内的 `templates`文件夹下的。
89 |
90 | > **注** 可以看出 Wagtail, 以至其基础Django，采用的是 “模型-视图” 编程模型。
91 |
92 | 将 `home/templates/home/home_page.html`编辑为包含以下内容：
93 |
94 | ```html
95 | {% extends "base.html" %}
96 |
97 | {% load wagtailcore_tags %}
98 |
99 | {% block body_class %}template-homepage{% endblock %}
100 |
101 | {% block content %}
102 | {{ page.body|richtext }}
103 | {% endblock %}
104 | ```
105 |
106 | 
107 |
108 |
109 | ## 关于 Wagtail 模板的标签
110 |
111 | **Wagtail template tags**
112 |
113 | Wagtail提供了一些 [模板标签与过滤器](topics/writing_templates.html#template_tags_and_filters)，通过在模板文件顶部包含 `{% load wagtailcore_tags %}`，装入这些标签与过滤器。
114 |
115 | 在本教程中，将用到 `richtext` 过滤器，来将某个 `RichTextField` 字段中的内容进行转写与打印出来（to escape and print the contents of a `RichTextField`）。
116 |
117 | ```html
118 | {% load wagtailcore_tags %}
119 | {{ page.body|richtext }}
120 | ```
121 |
122 | 这段代码将产生出：
123 |
124 | ```html
125 |
126 |
127 | Welcome to our new site!
128 |
129 |
{{ page.title }}
172 | {{ page.intro|richtext }}
173 |
174 | {% for post in page.get_children %}
175 |
176 | {{ post.specific.intro }}
177 | {{ post.specific.body|richtext }}
178 | {% endfor %}
179 | {% endblock %}
180 | ```
181 |
182 | 该模板中大部分都是熟悉的，但稍后要对`get_children`做一下解释。请注意`pageurl`这个标签，那与Django的`url`表情类似，不过`pageurl`带有一个Wagtail页面对象作为参数。
183 |
184 | 在Wagtail管理界面，创建一个`BlogIndexPage`，作为主页的子页面，并确保其在`效果提升（Promote）`分页中有着“blog”的一个slug。那么现在就应该可以在站点上访问到`/blog`这个URL了（请 **留意** 该`Promote`分页上的 slug `blog` 是如何定义页面URL的）。
185 |
186 | 现在需要一个博客文章的模型与模板了。在文件`blog/models.py`中：
187 |
188 | ```python
189 | from django.db import models
190 |
191 | from wagtail.core.models import Page
192 | from wagtail.core.fields import RichTextField
193 | from wagtail.admin.edit_handlers import FieldPanel
194 | from wagtail.search import index
195 |
196 | class BlogIndexPage(Page):
197 | intro = RichTextField(blank=True)
198 |
199 | content_panels = Page.content_panels + [
200 | FieldPanel('intro', classname="full")
201 | ]
202 |
203 | # 保留 BlogIndexPage的定义，并加入：
204 |
205 | class BlogPage(Page):
206 | date = models.DateField("发布日期")
207 | intro = models.CharField(max_length=250)
208 | body = RichTextField(blank=True)
209 |
210 | search_fields = Page.search_fields + [
211 | index.SearchField('intro'),
212 | index.SearchField('body'),
213 | ]
214 |
215 | content_panels = Page.content_panels + [
216 | FieldPanel('date'),
217 | FieldPanel('intro'),
218 | FieldPanel('body', classname="full"),
219 | ]
220 | ```
221 |
222 | 现在运行 `python manage.py makemigrations`与`python manage.py migrate`命令。
223 |
224 | 在 `blog/templates/blog/blog_page.html`创建一个模板：
225 |
226 | ```html
227 | {% extents "base.html" %}
228 |
229 | {% load wagtailcore_tags %}
230 |
231 | {% block body_class %}template-blogpage{% endblock %}
232 |
233 | {% block content %}
234 | {{ page.title }}
235 | {{ page.date }}
236 | {{ page.intro }}
237 |
238 | {{ page.body|richtext }}
239 |
240 | 返回博客首页
241 | {% endblock %}
242 | ```
243 |
244 | 请注意这里使用了Wagtail的内建`get_parent()`方法，来获取此文章所对应博客首页的URL。
245 |
246 | 现在创建一些作为`BlogIndexPage`的子页面的博客文章出来。在建立这些博客文章是一定要选择`Blog Page`类型。
247 |
248 | 
249 |
250 |
251 | 
252 |
253 | Wagtail将给予你对不同父内容类型下，可建立何种内容的完全掌控的能力（Wagtail gives you full control over what kinds of content can be created under various parent content types）。默认所有页面类型，都可以是任意其他页面类型的子页面。
254 |
255 | 
256 |
257 | 此时就有了一个可初步工作的博客系统了。在`/blog`URL处访问该博客，将看到如下页面：
258 |
259 | 
260 |
261 | 文章标题应是链接到文章页面的，同时在每个文章页面的底部，都应有一个返回到博客主页的链接。
262 |
263 | ## 关于父页面与子页面
264 |
265 | **Parents and Children**
266 |
267 | 在Wagtail中进行的大部分工作，都是围绕由众多节点与叶子所构成的“树”结构的层次概念开展的（参见[理论](reference/pages/theory.html)，Much of the work you'll be doing in Wagtail revolves around the concept of hierarchical "tree" structures consisting of nodes and leaves）。在本例中，`BlogIndexPage`是一个“节点”，同时单个的`BlogPage`实例，就是“叶子”了。
268 |
269 | 这里再来从另一个角度看看`blog_index_page.html`的代码：
270 |
271 | ```html
272 | {% for post in page.get_children %}
273 |
274 | {{ post.specific.intro }}
275 | {{ post.specific.body|richtext }}
276 | {% endfor %}
277 | ```
278 |
279 | 在Wagtail中的每个“页面”，都可以从他在这个层次体系中的位置，呼出他的父页面或所有子页面（Every "page" in Wagtail can call out to its parent or children from its own position in the hierarchy）。但这里又为何要指定`post.specific.into`，而不是`post.intro`呢？这就必须要从定义模型的方式说起了：
280 |
281 | ```python
282 | class BlogPage(Page):
283 | ```
284 |
285 | 方法`get_children()`给出了一个`Page`基类的实例清单。而在打算引用这些继承了该基类的实例属性时，Wagtail提供了`specific`方法，来获取到真实的`BlogPage`记录（the `get_children()` method gets us a list of instances of the `Page` base class. When we want ot reference properties of the instances that inherit from the base class, Wagtail provides the `specific` method that retrieves the actual `BlogPage` record）。尽管`title`字段在基类`Page`模块上是存在的，但`intro`字段却只存在与`BlogPage`模型上，因此就需要`.specific`方法，来访问该字段。
286 |
287 | 这里可使用Django的`with`标签，来讲模板代码加以优化：
288 |
289 | ```html
290 | {% for post in page.get_children %}
291 | {% with post=post.specific %}
292 |
293 | {{ post.intro }}
294 | {{ post.body|richtext }}
295 | {% endwith %}
296 | {% endfor %}
297 | ```
298 |
299 | 在后期编写更为定制化的Wagtail代码时，将发现一整套的`QuerySet`修饰符（a whole set of QuerySet modifiers），来帮助对层次结构进行导航。
300 |
301 | ```python
302 | # 给定一个页面对象`somepage`:
303 | MyModel.objects.descendant_of(somepage)
304 | child_of(somepage) / not_child_of(somepage)
305 | ancestor_of(somepage) / not_ancestor_of(somepage)
306 | parent_of(somepage) / not_parent_of(somepage)
307 | sibling_of(somepage) / not_sibling_of(somepage)
308 |
309 | # ... and ...
310 | somepage.get_children()
311 | somepage.get_ancestors()
312 | somepage.get_descenants()
313 | somepage.get_siblings()
314 | ```
315 |
316 | 有关此方面的更多信息，请参阅：[页面的QuerySet参考](reference/pages/queryset_reference.html)
317 |
318 |
319 | ## 覆写上下文
320 |
321 | **Overriding Context**
322 |
323 | 在上面的博客首页视图中存在一些问题：
324 |
325 | 1. 博客应该以 *相反* 的时间顺序显示的
326 | 2. 要确保只显示那些已发布的内容
327 |
328 | 要实现这两个目的，就要不光是在模板中抓取博客目录页面的子页面了。而要对模型定义中的`QuerySet`进行修改。Wagtail通过覆写`get_context()`方法，而令到这一点成为可能。像下面这样修改`BlogIndexPage`模型：
329 |
330 | ```python
331 | class BlogIndexPage(Page):
332 | intro = RichTextField(blank=True)
333 |
334 | def get_context(self, request):
335 | # 将上下文更新为仅包含发布了的博客文章，并以 时间逆序 进行排序
336 | context = super().get_context(request)
337 | blogpages = self.get_children().live().order_by('-first_publised_at')
338 | context['blogpages'] = blogpages
339 | return context
340 | ```
341 |
342 | 这里所完成的所有工作，就是先获取原始上下文，然后创建一个定制的`QuerySet`，将其加入到获取的上下文中，最后将修改后的上下文返回给视图。为此还需要对`blog_index_page.html`模板稍作改变。做以下修改：
343 |
344 | 将 `{% for post in page.get_children %}` 修改为：`{% for post in blogpages %}`
345 |
346 | 现在尝试加入一篇未发布的文章 -- 他将不会在博客目录页面出现。同时原有的文章将一最近发布在前的方式进行排序了。
347 |
348 | ## 图片
349 |
350 | 下面将把图片集附加到博客文章这一功能加入进来。尽管可以通过简单地将图片插入到`body`富文本字段中，但通过将图片集作为一种新的专用对象类型，在数据库中建立出来，然后有诸多优势 -- 以这种方式的话，就可以完全控制到这些图片在模板中的布局与样式，而不是必须在富文本字段中以特定方式对他们进行布置了。同时这样做也可以在独立于博客文本的其他地方，比如在博客目录页面显示一个缩略图的方式，使用这些图片。
351 |
352 | 将一个新的`BlogPageGalleryImage`模型，加入到`models.py`文件中：
353 |
354 | ```python
355 | from django.db import models
356 |
357 | # 新加入了 ParentalKey、Orderable、InlinePanel与ImageChooserPanel 的导入
358 | from modelcluster.fields import ParentalKey
359 |
360 | from wagtail.core.models import Page, Orderable
361 | from wagtail.core.fields import RichTextField
362 | from wagtail.admin.edit_handlers import FieldPanel, InlinePanel
363 | from wagtail.images.edit_handlers import ImageChooserPanel
364 | from wagtail.search import index
365 |
366 | class BlogIndexPage(Page):
367 | intro = RichTextField(blank=True)
368 |
369 | def get_context(self, request):
370 | # 将上下文更新为仅包含发布了的博客文章，并以 时间逆序 进行排序
371 | context = super().get_context(request)
372 | blogpages = self.get_children().live().order_by('-first_published_at')
373 | context['blogpages'] = blogpages
374 | return context
375 |
376 | content_panels = Page.content_panels + [
377 | FieldPanel('intro', classname="full")
378 | ]
379 |
380 | # 保留 BlogIndexPage的定义，并加入：
381 |
382 | class BlogPage(Page):
383 | date = models.DateField("发布日期")
384 | intro = models.CharField(max_length=250)
385 | body = RichTextField(blank=True)
386 |
387 | search_fields = Page.search_fields + [
388 | index.SearchField('intro'),
389 | index.SearchField('body'),
390 | ]
391 |
392 | content_panels = Page.content_panels + [
393 | FieldPanel('date'),
394 | FieldPanel('intro'),
395 | FieldPanel('body', classname="full"),
396 | InlinePanel('gallery_images', label="图片"),
397 | ]
398 |
399 | class BlogPageGalleryImage(Orderable):
400 | page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name="gallery_images")
401 | image = models.ForeignKey(
402 | 'wagtailimages.Image', on_delete=models.CASCADE, related_name="+"
403 | )
404 | caption = models.CharField(blank=True, max_length=250)
405 |
406 | panels = [
407 | ImageChooserPanel('image'),
408 | FieldPanel('caption'),
409 | ]
410 | ```
411 |
412 | 此时运行 `python manage.py makemigrations` 与 `python manage.py migratte`。
413 |
414 | 上面的代码中涉及到一些新的概念，下面就一起来看看他们：
415 |
416 | `BlogPageGalleryImage`模型继承自`Orderable`，从而将字段`sort_order`加入到模型中了，以对图片集中的图片顺序进行跟踪。
417 |
418 | 到`BlogPage`模型的`ParentalKey`，则是将这些图片附加到某个特定页面。`ParentalKey`的工作方式与`ForeignKey`类似，不过同时将`BlogPageGalleryImage`定义为`BlogPage`模型的“子”模型，因此他就成为了页面的一个基础部分，可以对其进行修改提交与修订历史追踪等操作（A `ParentalKey` works similarly to a `ForeignKey`, but also defines `BlogPageGalleryImage` as a "child" of the `BlogPage` model, so that it's treated as a fundamental part of the page in operations like submitting for moderation, and tracking revision history）。
419 |
420 | `image`是到Wagtail内建的`Image`模型的一个`FoerignKey`, 图片本身是在`Image`模型中存储的。同时`Image`模型有着自己的专用面板类型（a dedicated panel type），`ImageChooserPanel`，该面板类型提供了一个用于选取某个既有图片或上传一个新图片的弹出界面。依此方式，就允许某个图片可以存在于多个图片集中 -- 从而有效地创建了一直页面与图片之间的多对多关系。
421 |
422 | 在该外键上指定`on_delete=models.CASCADE`，就意味着当某个图片从系统中删除时，其所在图片集也会被删除。（但在某些情况下，可能让该条目留存下来更好 -- 比如在某个“our staff”页面包含了一个有着头像的人员清单，而其中一张头像被删除了，那么就宁愿将那个人在没有头像图片的情况下保留下来。在次情况下，就要把此外键设置为`blank=True, null=True, on_delete=models.SET_NULL`）。
423 |
424 | 最后，将`InlinePanel`加入到`BlogPage.content_panels`中，从而领导该图片集在`BlogPage`的编辑界面上可用。
425 |
426 | 对博客页面进行调整，以包含这些图片：
427 |
428 | ```html
429 | {% extends "base.html" %}
430 |
431 | {% load wagtailcore_tags wagtailimages_tags %}
432 |
433 | {% block body_class %}template-blogpage{% endblock %}
434 |
435 | {% block content %}
436 | {{ page.title }}
437 | {{ page.date }}
438 |
439 | {{ page.intro }}
440 |
441 | {{ page.body|richtext }}
442 |
443 |
444 | {% for item in page.gallery_images.all %}
445 |
446 | {% image item.image fill-320x240 %}
447 |
{{ item.caption }}
448 |
返回博客首页
453 | {% endblock %}
454 | ```
455 |
456 | 这里使用 `{% image %}` 标签（此标签存在于`wagtailimages_tags`库中，在该模板顶部有导入该库），来将某个`![]()
`元素，以`file-320x240`为参数而表明该图片需要缩放及裁剪，以填充到一个`320x240`的矩形中，而进行插入。有关在模板中图片的使用的更多信息，请参阅[文档](topics/images.html)。
457 |
458 | 
459 |
460 | 因为这里的图片集图片，都是有着其自身地位的数据库对象，所以可以对其进行查询以及独立于博客文章主体的重复使用（since our gallery images are database objects in their own right, we can query and re-use them independently of the blog post body）。下面定义了一个`main_image`方法，将返回图片集的第一个条目（或在没有没有图片集时返回`None`）：
461 |
462 | ```python
463 | class BlogPage(Page):
464 | date = models.DateField("发布日期")
465 | intro = models.CharField(max_length=250)
466 | body = RichTextField(blank=True)
467 |
468 | def main_image(self):
469 | gallery_item = self.gallery_images.first()
470 | if gallery_item:
471 | return gallery_item.image
472 | else:
473 | return None
474 |
475 | search_fields = Page.search_fields + [
476 | index.SearchField('intro'),
477 | index.SearchField('body'),
478 | ]
479 |
480 | content_panels = Page.content_panels + [
481 | FieldPanel('date'),
482 | FieldPanel('intro'),
483 | FieldPanel('body', classname="full"),
484 | InlinePanel('gallery_images', label="图片"),
485 | ]
486 | ```
487 |
488 | 此方法现在已对模板可用了。现在对`blog_index_page.html`进行更新，以将博客文章主图作为每篇文章旁边的一个缩略图，而包含进来：
489 |
490 | ```html
491 | {% extends "base.html" %}
492 |
493 | {% load wagtailcore_tags wagtailimages_tags %}
494 |
495 | {% block body_class %}template-blogindexpage{% endblock %}
496 |
497 | {% block content %}
498 | {{ page.title }}
499 | {{ page.intro|richtext }}
500 |
501 | {% for post in blogpages %}
502 | {% with post=post.specific %}
503 |
504 |
505 | {% with post.main_image as main_image %}
506 | {% if main_image %}
507 | {% image main_image fill-160x100 %}
508 | {% endif %}
509 | {% endwith %}
510 |
511 | {{ post.intro }}
512 | {% endwith %}
513 | {% endfor %}
514 | {% endblock %}
515 | ```
516 |
517 | ## 将文章打上标签
518 |
519 | **Tagging Posts**
520 |
521 | 现在要加入一项可以让文章编辑给他们的文章“打上标签”的功能，如此读者就可以查看到比如“自行车”相关的所有内容。要实现次特性，就需要调用与Wagtail打包在一起的标签系统（the tagging system bundled with Wagtail），将该标签系统附加到模型`BlogPage`与内容面板，并在博客文章模板上渲染出带有链接的标签。不言而喻，这里同样需要一个能用的特定于标签URL视图（Of course, we'll need a working tag-specific URL view as well）。
522 |
523 | 首先，再一次对`models.py`进行修改：
524 |
525 | ```python
526 | from django.db import models
527 |
528 | # 新加入了 ParentalKey、Orderable、InlinePanel与ImageChooserPanel 的导入
529 | # 新加入了 ClusterTaggableManager、TaggedItemBase与MultiFieldPanel
530 | from modelcluster.fields import ParentalKey
531 | from modelcluster.contrib.taggit import ClusterTaggableManager
532 | from taggit.models import TaggedItemBase
533 |
534 | from wagtail.core.models import Page, Orderable
535 | from wagtail.core.fields import RichTextField
536 | from wagtail.admin.edit_handlers import FieldPanel, InlinePanel, MultiFieldPanel
537 | from wagtail.images.edit_handlers import ImageChooserPanel
538 | from wagtail.search import index
539 |
540 | # ...(保持BlogIndexPage的定义不变)
541 | class BlogIndexPage(Page):
542 | intro = RichTextField(blank=True)
543 |
544 | def get_context(self, request):
545 | # 将上下文更新为仅包含发布了的博客文章，并以 时间逆序 进行排序
546 | context = super().get_context(request)
547 | blogpages = self.get_children().live().order_by('-first_published_at')
548 | context['blogpages'] = blogpages
549 | return context
550 |
551 | content_panels = Page.content_panels + [
552 | FieldPanel('intro', classname="full")
553 | ]
554 |
555 | class BlogPageTag(TaggedItemBase):
556 | content_object = ParentalKey(
557 | 'BlogPage',
558 | related_name = 'tagged_items',
559 | on_delete = models.CASCADE
560 | )
561 |
562 | # 保留 BlogIndexPage的定义，并加入：
563 |
564 | class BlogPage(Page):
565 | date = models.DateField("发布日期")
566 | intro = models.CharField(max_length=250)
567 | body = RichTextField(blank=True)
568 | tags = ClusterTaggableManager(through=BlogPageTag, blank=True)
569 |
570 | # ... （保留 main_image 与 search_fields 的定义）
571 | def main_image(self):
572 | gallery_item = self.gallery_images.first()
573 | if gallery_item:
574 | return gallery_item.image
575 | else:
576 | return None
577 |
578 | search_fields = Page.search_fields + [
579 | index.SearchField('intro'),
580 | index.SearchField('body'),
581 | ]
582 |
583 | content_panels = Page.content_panels + [
584 | MultiFieldPanel([
585 | FieldPanel('date'),
586 | FieldPanel('tags'),
587 | ], heading="文章信息"),
588 | FieldPanel('intro'),
589 | FieldPanel('body', classname="full"),
590 | InlinePanel('gallery_images', label="图片"),
591 | ]
592 |
593 | class BlogPageGalleryImage(Orderable):
594 | page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name="gallery_images")
595 | image = models.ForeignKey(
596 | 'wagtailimages.Image', on_delete=models.CASCADE, related_name="+"
597 | )
598 | caption = models.CharField(blank=True, max_length=250)
599 |
600 | panels = [
601 | ImageChooserPanel('image'),
602 | FieldPanel('caption'),
603 | ]
604 | ```
605 |
606 | 此时运行 `python manage.py makemigrations` 与 `python manage.py migrate`。
607 |
608 | 请注意这里新的`modelcluster`与`taggit`导入，及新的`BlogPageTag`模型的加入，以及在`BlogPage`模型上加入的`tags`字段。这里还利用了`BlogPage`模型上`conent_panels`中的`MultiFieldPanel`，来把日期与标签字段放在一起，从而提升了可读性。
609 |
610 | 对`BlogPage`实例之一进行编辑，那么现在就可以对文章打标签了：
611 |
612 | 
613 |
614 | 而要在`BlogPage`上渲染出标签，就要将下面的代码加入到`blog_page.html`：
615 |
616 | ```html
617 |
618 | {% if page.tags.all.count %}
619 |
625 | {% endif %}
626 |
627 | ```
628 |
629 | 请注意这里所链接到的页面，使用的是内建的`slugurl`而非早先使用的`pageurl`。二者的区别在于，`slugurl`取的是某个页面的别名（slug，来自“Promote”分页）作为参数。而`pageurl`则更为常用，因为他更为明确，且避免了额外的数据库查询。但在该循环的具体情况下，页面对象并不是已可用的，因此这里倒退使用了更少用到的 `slugurl` 标签（the Page object isn't readily available, so we fall back on the less-preferred `slugurl` tag）。
630 |
631 | 现在访问某个带有标签词的博客文章，就会看到在页面底部有了一些带有链接的按钮了 -- 每个按钮对应了一个标签词。但在点击某个按钮是将给出 `404` 错误，这是因为尚未定义一个“tags”视图的原因。将下面的代码加入到 `models.py`：
632 |
633 | ```python
634 | class BlogTagIndexPage(Page):
635 |
636 | def get_context(self, request):
637 |
638 | # 以标签词进行过滤
639 | tag = request.GET.get('tag')
640 | blogpages = BlogPage.objects.filter(tags__name=tag)
641 |
642 | # 更新模板上下文
643 | context = super().get_context(request)
644 | context['blogpages'] = blogpages
645 | return context
646 | ```
647 |
648 | 请注意此基于页面的模型，并没有定义他自身的字段。就算没有字段，其对`Page`基类的子类化，也令到其成为Wagtail生态的一部分了。因此就可以在管理界面给他一个标题与URL，同时也就可以通过从其`get_context()`方法返回一个`QuerySet`，而对其内容进行操作（note that this Page-based model defines no fields of its own. Even without fields, subclassing `Page` makes it a part of the Wagtail ecosystem, so that you can give it a title and URL in the admin, and so that you can manipulate its contents by returning a QuerySet from its `get_context()` method）。
649 |
650 | 将此改变提交到数据库，然后在管理界面创建一个新的`BlogTagIndexPage`。差不多要将此新的页面/试图，作为站点主页的一个子页面，而与博客首页并排进行创建。在`Promote`分栏给他一个`tags`的别名（slug）。
651 |
652 | 现在去访问`/tags`的话，Django就会告诉你自己已然知道的东西：你需要创建一个`blog/blog_tag_index_page.html`的模板：
653 |
654 | > **注** 实际仍然要放在 `blog/templates/blog/`目录下。
655 |
656 | ```txt
657 | TemplateDoesNotExist at /tags/
658 | blog/blog_tag_index_page.html
659 | Request Method: GET
660 | Request URL: http://localhost:8000/tags/
661 | Django Version: 2.1.8
662 | Exception Type: TemplateDoesNotExist
663 | Exception Value: blog/blog_tag_index_page.html
664 | Exception Location: /home/peng/.venv/lib/python3.6/site-packages/django/template/loader.py in get_template, line 19
665 | Python Executable: /home/peng/.venv/bin/python
666 | Python Version: 3.6.7
667 | Python Path: ['/home/peng/wagtail-demo/demo',
668 | '/usr/lib/python36.zip',
669 | '/usr/lib/python3.6',
670 | '/usr/lib/python3.6/lib-dynload',
671 | '/home/peng/.venv/lib/python3.6/site-packages']
672 | Server time: Wed, 10 Apr 2019 00:43:10 +0000
673 | ```
674 |
675 | ```html
676 | {% extends "base.html" %}
677 | {% load wagtailcore_tags %}
678 |
679 | {% block content %}
680 | {% if request.GET.tag|length %}
681 | 显示标签为 “{{ request.GET.tag }}” 页面
682 | {% endif %}
683 |
684 | {% for blogpage in blogpages %}
685 |
686 | {{ blogpage.title }}
687 | 修订于：{{ blogpage.latest_revision_created_at }}
688 | {% if blogpage.author %}
689 |
作者： {{ blogpage.author.profile }}
690 | {% endif %}
691 |
692 |
693 | {% empty %}
694 | 未发现带有该标签词的文章。
695 | {% endfor %}
696 | {% endblock %}
697 | ```
698 |
699 | > **注** 管理界面创建的页面 `BlogTagIndexPage` 为什么不是一个新的、如同`blog`一样的应用？为什么`BlogTagIndexPage`对应的模板仍然要放在 `blog/templates/blog`目录下？这是因为 `BlogTagIndexPage`是定义在 `blog/models.py`中的，因此只能将其视为应用`blog`的一部分，而非一个新的应用，同时其模板/视图也应位于 `blog/templates/blog`目录下。
700 |
701 | 这里调用了`Page`模型上内建的 `latest_revision_created_at` 字段 -- 要知道这总是可用的。
702 |
703 | 目前尚未给`BlogPage`模型加上`author`字段，也还没有博客文章作者的个人资料模型 -- 这些将留给读者作为练习。
704 |
705 | 现在点击某个博客文章底部的标签词按钮，就能够渲染出类似于下面的页面了：
706 |
707 | 
708 |
709 | ## 分类
710 |
711 | **Categories**
712 |
713 | 下面类给这里的博客加上分类系统（a category system）。与标签特性中某篇文章的作者可以简单地通过在页面上使用某个标签词，而将该标签词引入到页面既有标签词中有所不同，分类特性将会是一个由站点所有者经由管理界面的某个单独区域管理的固定清单（categories will be a fixed list, managed by the site owner through a separate area of the admin interface）。
714 |
715 | 那么首先就要定义一个 `BlogCategory` 模型。某个类别不是有着自身地位的页面，因此要将其定义为标准的Django `models.Model`，而非从`Page`基类加以继承。Wagtail引入了“内容片（Snippets）”这一概念，专门用于那些需要通过管理界面进行管理，但又并不是作为页面树本身的组成部分而存在的，可重用小块内容；那么这类模型就可以通过`@register_snippet`装饰器，而作为内容片进行注册。到目前位置在页面上用到的所有字段类型，都可以用在内容片上 -- 下面将给予每个类别一个图标和名称。将下面的代码加入到 `blog/models.py`：
716 |
717 | ```python
718 | # 新加入 Wagtail 的 @register_snippet 装饰器，有关 Python 装饰器的更多信息，请
719 | # 参考：[使用装饰器](https://github.com/gnu4cn/python-advance-book/blob/master/01-effective-and-fine-python-code.md#%E4%BD%BF%E7%94%A8%E8%A3%85%E9%A5%B0%E5%99%A8)
720 |
721 | from wagtail.snippets.models import register_snippet
722 |
723 | @register_snippet
724 | class BlogCategory(model.Models):
725 | name = models.CharField(max_length=250)
726 | icon = models.ForeignKey(
727 | 'wagtailimages.Image', null=True, blank=True,
728 | on_delete=models.SET_NULL, related_name="+"
729 | )
730 |
731 | panels = [
732 | FieldPanel('name'),
733 | ImageChooserPanel('icon'),
734 | ]
735 |
736 | def __str__(self):
737 | return self.name
738 |
739 | class Meta:
740 | verbose_name_plural = '博客类别'
741 | ```
742 |
743 | > **注意** 请注意这里使用了`panels`而非`content_panels` -- 因为内容块一般不需要诸如别名（slug）或发布日期这类字段，所以他们的编辑界面就不会划分为标准的单独 `conent` / `promote` / `settings` 这样的分页了，且因此就不需要区分`content panels` 与 `promote panels`了
744 |
745 | 将此修改提交到数据库，并经由已经在管理菜单的“Snippets(内容块)”区，创建一些分类。
746 |
747 | 现在就可以将类别作为一个多对多关系字段，加入到 `BlogPage` 模型了。在此字段上使用的字段类型，就是`ParentalManyToManyField` -- 该字段类型，是标准的 Django `ManyToManyField` 字段类型的一个变种，Django的`ManyToManyField`确保所选的对象，与修订历史中的页面记录相对，已在数据库中正确存储，这与一对多关系中使用`ParentalKey`替换`ForeignKey`很类似。
748 |
749 | ```python
750 | # 新加入了 `forms` 与 `ParentalManyToManyField`
751 | from django.db import models
752 | from django import forms
753 |
754 | # 新加入了 ParentalKey、Orderable、InlinePanel与ImageChooserPanel 的导入
755 | # 新加入了 ClusterTaggableManager、TaggedItemBase与MultiFieldPanel
756 | from modelcluster.fields import ParentalKey, ParentalManyToManyField
757 | from modelcluster.contrib.taggit import ClusterTaggableManager
758 | from taggit.models import TaggedItemBase
759 |
760 | # ...
761 |
762 | class BlogPage(Page):
763 | date = models.DateField("发布日期")
764 | intro = models.CharField(max_length=250)
765 | body = RichTextField(blank=True)
766 | tags = ClusterTaggableManager(through=BlogPageTag, blank=True)
767 | categories = ParentalManyToManyField('blog.BlogCategory', blank=True)
768 |
769 | # ... （保留 main_image 与 search_fields 的定义）
770 | def main_image(self):
771 | gallery_item = self.gallery_images.first()
772 | if gallery_item:
773 | return gallery_item.image
774 | else:
775 | return None
776 |
777 | search_fields = Page.search_fields + [
778 | index.SearchField('intro'),
779 | index.SearchField('body'),
780 | ]
781 |
782 | content_panels = Page.content_panels + [
783 | MultiFieldPanel([
784 | FieldPanel('date'),
785 | FieldPanel('tags'),
786 | FieldPanel('categories', widget=forms.CheckboxSelectMultiple),
787 | ], heading="文章信息"),
788 | FieldPanel('intro'),
789 | FieldPanel('body', classname="full"),
790 | InlinePanel('gallery_images', label="图片"),
791 | ]
792 | ```
793 |
794 | 这里在`FieldPanel` 定义上利用了 `widget` 关键字，用来指定一个基于复选框的小部件，而不是默认的多选框，因为小部件通常被认为更为用户友好。
795 |
796 | 最后，对`blog_page.html`模板加以更新，让他显示出类别：
797 |
798 | ```html
799 | {% with categories=page.categories.all %}
800 | {% if categories %}
801 | 发表在：
802 |
803 | {% for category in categories %}
804 | -
805 | {% image category.icon fill-32x32 style="vertical-align: middle" %}
806 | {{ category.name }}
807 |
808 | {% endfor %}
809 |
810 | {% endif %}
811 | {% endwith %}
812 | ```
813 |
814 | 
815 |
816 | ## 下一步
817 |
818 | + 阅读Wagtail [使用手册](topics/index.html) 以及 [参考](reference/index.html) 文档
819 | + 学习如何使用 [StreamField](topics/streamfield.html) 来创建自由格式的页面内容
820 | + 浏览 [高级特性](advanced_topics/index.html) 部分并阅读 [第三方教程](advanced_topics/third-party_tutorials.html)
821 |
--------------------------------------------------------------------------------
35 | {% endblock %}
36 |
37 | {% endraw %}
38 |
39 | 该徽标也出现在管理的 `404` 错误页面上；要在那里对其进行替换，就要创建一个对`branding_logo`块加以覆写的`dashboard/templates/wagtailadmin/404.html`的模板文件。
40 |
41 | + `branding_favicon`
42 |
43 | 要替换在查看管理页面时所显示的站点图标（the favicon），就要创建一个对`branding_favicon`块进行覆写的 `dashboard/templates/wagtailadmin/admin_base.html`的模板文件：
44 |
45 | {% raw %}
46 |
47 | {% extends "wagtailadmin/admin_base.html" %}
48 | {% load static %}
49 |
50 | {% block branding_favicon %}
51 |
52 | {% endblock %}
53 | {% endraw %}
54 |
55 |
56 | + `branding_login`
57 |
58 | 要替换登录消息，就要创建一个用于对`branding_login`块进行覆写的 `dashboard/templates/wagtailadmin/login.html`的模板文件：
59 |
60 | {% raw %}
61 |
62 | {% extends "wagtailadmin/login.html" %}
63 | {% block branding_login %}登入科服斯网站{% endblock %}
64 | {% endraw %}
65 |
66 |
67 | + `branding_welcome`
68 |
69 | 要替换站点仪表盘上的欢迎消息，就要创建一个对 `branding_welcome`块进行覆写的模板文件 `dashboard/templates/wagtailadmin/home.html`：
70 |
71 | {% raw %}
72 |
73 | {% extends "wagtailadmin/home.html" %}
74 |
75 | {% block branding_welcome %}
76 | 欢迎来到科服斯管理后台！
77 | {% endblock %}
78 | {% endraw %}
79 |
80 | ## 在站点品牌中指定一个站点或页面
81 |
82 | 管理界面有着一些对渲染器上下文可用的变量，他们可用于对管理页面中的品牌进行定制。在对多租户的Wagtail安装进行定制时，这些变量将是有用的：
83 |
84 | + `root_page`
85 |
86 | 返回的是对于当前登入用户来说最高的可浏览页面对象。在用户没有浏览权限时，这将默认为 `None`。
87 |
88 | + `root_site`
89 |
90 | 返回上述根页面的站点记录上的名称。
91 |
92 | + `site_name`
93 |
94 | 在计算出 `root_site` 的值不是 `None` 时，返回其值。在`root_site`的值为`None`时，将返回 `settings.WAGTAIL_SITE_NAME`的值。
95 |
96 | 要使用这些变量，就如同之前对仪表盘中的那些模板块的覆写一样，要创建一个`dashboard/templates/wagtailadmin/home.html`的模板文件，并像使用其他Django的模板变量一样，对这些变量进行使用：
97 |
98 | {% raw %}
99 |
100 | {% extends "wagtailadmin/home.html" %}
101 | {% block branding_welcome %}
102 | 欢迎来到 {{ root_site }} 的管理首页
103 | {% endblock %}
104 | {% endraw %}
105 |
106 | 
45 | ```
46 |
47 | 再次，这里的`embedtype`属性表示了重写该标签所用的规则。除了``与``之外的所有其他标签，在转换后的HTML中都将保持不变。
48 |
49 | 有着一些应用到``与``的约束，他们的作用是实现经由字符串替换，而有效地完成转换：
50 |
51 | + 标签名称与属性必须是小写的
52 | + 属性值必须用双引号括起来
53 | + `embed`元素必须使用XML的自闭标签语法（XML self-closing tag syntax, 也就是以`/>`，而非``结束）
54 | + 属性值中仅允许这些HTML实体符号：`<`、`>`、`&`与`"`
55 |
56 | ## 功能注册
57 |
58 | 项目中的所有应用，都可定义对Wagtail的富文本处理过程的扩展，比如新的`linktype`与`embedtype`规则。名为 _功能注册_ 的对象，是作为有关富文本应如何运作的核心事实来源而加以提供的（An object known as the _feature registry_ serves as a central source of truth about how rich text should behave）。该对象可通过`register_rich_text_features`钩子进行访问，而该钩子是在启动时进行调用的，调用时会收集与富文本有关的所有定义：
59 |
60 | ```python
61 | # my_app/wagtail_hooks.py
62 |
63 | from wagtail.core import hooks
64 |
65 | @hooks.register('register_rich_text_features')
66 | def register_my_feature(features):
67 | # 这里将新的定义，添加到 “features”
68 | ```
69 |
70 | ## 关于重写处理器
71 |
72 | 重写处理器，是一些知道如何将富文本标签的内容，诸如``与``，转换为前端HTML的类。比如`PageLinkHandler`类，就知道怎样将富文本标签``，转换为HTML标签``。
73 |
74 | 重写处理器还能提供到其他一些有关富文本标签的信息。比如对于一个给定的适当标签，`PageLinkHandler`就可用于提取出将引用哪个页面的信息。这对于可能需要那些富文本中所引用对象信息的下游代码，将是有用的。
75 |
76 | 可创建对之前定制的新`linktype`与`embedtype`进行支持的重写处理器。新的处理器必须是继承自`wagtail.core.richtext.LinkHandler`或`wagtail.core.richtext.EmbedHandler`的Python类。新的类应至少对下面的部分方法进行重写（这里列出的时`LinkHandler`的方法，不过`EmbedHandler`的这些方法也有着相同的签名）：
77 |
78 | [`class LinkHandler`](#LinkHandler)
79 |
80 | + `identifier`
81 |
82 | 必需的。`identifier`属性是一个表示哪个富文本标签应由该处理器进行处理的字符串。
83 | 比如`PageLinkHandler.get_identifier`返回的字符串就是`"page"`，表明所有有着``的富文本标签，都将由其加以处理。
84 |
85 | + `expand_db_attributes(attrs)`
86 |
87 | 必需的。方法`expand_db_attributes`期望从某个数据库的富文本``标签（对于`EmbedHandler`就是`