Hopiu/wagtail
1
0
Fork 0
mirror of https://github.com/Hopiu/wagtail.git synced 2026-05-13 17:53:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

snappier intro and link to StreamField blog post

Browse source
This commit is contained in:
Matt Westcott 2015-03-26 11:57:44 +00:00
parent a3379dfbe5
commit 33def64870
1 changed files with 3 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
docs/core_components/pages/streamfield.rst
View file

@ -1,13 +1,12 @@
Freeform page content using StreamField
=======================================
Wagtail's content model encourages thinking about the information on a page in a formal, structured way; for example, a page about an event is not just an assortment of headings, paragraphs and images, but has specific fields for dates, location, a list of speakers and so on. This ensures that the template developer has a known, predictable set of fields to work with, and can present that information consistently throughout the site in the most appropriate arrangement. It also allows the information to be re-used and repurposed, such as displaying an "events near you" listing.
StreamField provides a content editing model suitable for pages that do not follow a fixed structure - such as blog posts or news stories, where the text may be interspersed with subheadings, images, pull quotes and video, and perhaps more specialised content types such as maps and charts (or, for a programming blog, code snippets). In this model, these different content types are represented as a sequence of 'blocks', which can be repeated and arranged in any order.
In some cases, though, we would like to give the page author more flexibility to create freeform content, such as blog posts or news stories where the text may be interspersed with subheadings, images, pull quotes and video, and perhaps more specialised content types such as maps and charts (or, for a programming blog, code snippets). The traditional approach to this would be to use a rich text field for the entire page body, with the different content types implemented using a variety of HTML styles. This approach is not recommended; aside from rich text simply not being a very good interface for editing this kind of complex content, it also means that the content becomes an opaque blob of HTML, and we lose the semantic information that indicates what the different block types actually mean.
For further background on StreamField, and why you would use it instead of a rich text field for the article body, see the blog post `Rich text fields and faster horses <https://torchbox.com/blog/rich-text-fields-and-faster-horses/>`__.
StreamField solves the problem of freeform content by expressing it as a sequence of 'blocks' - headings, images, paragraphs and so on - which can be repeated and arranged in any order. Each block is editable using the most suitable interface for that block type - such as a rich text area for paragraphs, or Wagtail's image chooser (along with dropdowns to specify image format, where appropriate) for images.
StreamField also offers a rich API to define your own block types, ranging from simple collections of sub-blocks (such as a 'person' block consisting of first name, surname and photograph) to completely custom components with their own editing interface. Within the database, the StreamField content is stored as JSON, ensuring that the full informational content of the field is preserved, rather than just an HTML representation of it.
StreamField also provides a rich API to define your own block types, ranging from simple collections of sub-blocks (such as a 'person' block consisting of first name, surname and photograph) to completely custom components with their own editing interface. Within the database, the StreamField content is stored as JSON, ensuring that the complete informational content of the field is preserved, rather than just an HTML representation of it.
Using StreamField
-----------------