csswg-wiki/spec/page-view.txt at 2d4f6f77c5742fc1ac1e23bd48ddd63b72182aeb · mwjacksonmsft/csswg-wiki · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
====== Page View ======
"Page view" or "paged view" as a term relates broadly to the kind of presentation where content is laid out in discrete pages and shown to user one page at a time (or several pages at a time).

A wide variety of paged view situations require the same or similar support from the core layout engine -- primarily the ability to flow content into multiple containers, thus producing multiple boxes with fragments of content (see "[[Fragments, Columns, Regions, Pages]]"). Solutions differ in how the fragmentation functionality is invoked.

The problems to be solved in implementing paged views revolve around encoding the design intent and UI behavior, both requiring novel approaches: design intent often derives from experience in print media, which must become adaptive to target multiple devices and resolutions. The UI of navigating pages on screen also doesn’t have an established tradition, although many implementations use similar concepts.

This set of use cases shows some expected uses of paged views.

The uses cases, analysis and proposals found here probably don’t correspond to a single specification. The goal here is to get a holistic view of each case, which will help to compare proposals and understand the relative importance of lower level problems.

====== Use Cases ======

===== Page view in window or element =====

**Goal:** easy declarative way to create paged view, good behavior with default settings and default UI.

<html>
<div style="display:inline-block; width:9em;">

<div style="background:gray; --padding:1em; text-align:justify; vertical-align:middle;">
  <div style="background:white;border:1px solid black; --width:7em; padding:1em; text-align:justify">
    <div>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua</div>
  </div>
  <div style="text-align:justify; padding:0 1em;">
    <div style="display:inline-block; color:lightgray; font-size:1.2em;">&lt;&lt;&lt;</div>
    <div style="display:inline-block; color:lightgray; font-size:1.2em;">&gt;&gt;&gt;</div>
    <div style="display:inline-block; width:6em; height:0; visibility:hidden"></div>
  </div>
</div>
</div>
</html>

**Proposal:**
  * New value for 'overflow property: **"overflow:paged"**

**Example:**
  div.book { overflow:paged }
Element with "overflow:paged" shows one page of content at a time.

All pages are of the same size - the size of content area of the element.

UI is provided by UA, it may be jestures on touch device, or page navigation controls (perhaps similar to controls on <video> element)

**Example:**
  html { width:100%; height:100%; overflow:paged }
This should put the whole document in paged view. If UA is also in full screen mode, this works particularly well on tablet devices as full-screen reading mode

**Example:**
  iframe.magazine { overflow:paged }
Presents content of a separate document in paged view. Can be used to build a page viewer with custom UI.


===== Page view with custom controls =====

**Goal:** Add custom controls to paged view.

Ideally, UA should provide well designed, usable and accessible controls for pagination. There will inevitably be situations however that require custom UI, for style or to provide unique functions. It could look like this:

<html>
<div style="display:inline-block">
<div style="height:2em; background:black; padding:0.5em 1em; font-family:sans-serif; font-weight:bold; text-align:center;">
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">print</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">share</div>
  &nbsp;&nbsp;
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">&lt;</div>
  <div style="display:inline-block; border:1px solid white; background:white; padding:0.25em; font-weight:normal">page #</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">&gt;</div>
  &nbsp;&nbsp;
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">zoom</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">bookmark</div>
  &nbsp;&nbsp;
  <div style="display:inline-block; border:1px solid white; background:white; padding:0.25em 5em 0.25em 0.25em ; font-weight:normal">&nbsp;</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">search</div>
</div>

<div style="background:gray; padding:1em; text-align:center;">
    <div style="display:inline-block;background:white;border:1px solid black; width:7em; padding:1em; text-align:justify">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua</div>
</div>
</div>
</html>

Custom controls will activate custom script, which in some cases will need to access pagination results or modify the view.

Implementation of custom page UI needs some or all of the following:
  * Modify or replace the default pagination UI
  * Know number of pages
  * Show a particular page
  * Know if everything fits (in automatic page layout, there will be alwayse enough pages generated, but there may be unprocessed content due to timing or additional constraints)
  * Determine what content is in a given page (a potentially disjoint range of content)
  * Determine on what page or pages a given range of content is
  * Determine if content of interest didn't fit on any page
  * Find content that intersects with a point or shape, relative to a given page or current page
  * Find exact coordinates and page(s) of laid out content
  * Know when number of pages changes or layout of content on a page changes

To achieve that, pages and paged viewer need exposure in styles and OM

====Proposals====

===Control default UI with 'overflow' property (([[http://dev.w3.org/csswg/css3-gcpm/#paged-presentations|GCPM - ED]]))===
  * **overflow-style**:<existing values>|paged-x|paged-y|paged-x-controls|paged-y-controls

**Example**

"paged-x" layout adds overflow pages along X axis. Custom page UI controls which page is displayed in pagination control
<code>
  .pager { overflow:paged-x; }
  <div class="pageview">
    <div class="toolbar">
      <button onclick="prevPage()">previous</button>
      <button onclick="nextPage()">next</button>
      ...
    </div>
    <div class="pager">
      <iframe class="pages" src="content.html"></iframe>
    </div>
  </div>
  <script>
    function nextPage() {
      if (pager.currentPage < pager.pageCount) {
        pager.currentPage++;
      }
    }
  </script>
</code>
====Ideas====
===Paged View DOM===
//Some API as in [[http://dev.opera.com/articles/view/opera-reader-a-new-way-to-read-the-web/|Opera Reader]], other added as it seems needed for completness. Please correct if there are newer proposals//

  * interface **PagedView** -- implemented on HTMLElement (and maybe on HTMLDocument). Alternatively all members are exposed directly on element (that would match scope of scroll API)
  * PagedView Element.**pagedView** -- paged view of element's content. NULL if not applicable
  * int PagedView.**pageCount** -- get number of pages
This should wait synchronously for content pagination to be completed, if needed, following the patter of 'offsetHeight' etc. (which always return correct value, forcing synchronous layout)
  * void PagedView.**showPage**(pageNumber)
  * int[] PagedView.**getPagesFromContentNode**(Node contentNode) -- get page numbers for pages that show any portion of given node
  * Rect[] PagedView.**rectsOnPage**(pageNumber, Node contentnode) -- get bounding rects of content rendering on specific page
  * Range[] PagedView.**getContentRangesOnPage**(pageNumber) -- range(s) of content that falls on that page
  * Node **elementFromPoint**(pageNumber, x, y) -- element under the point, in coordinates of the page
  * event **onpagechange** -- fired when current page changes

===== Page view with custom pages =====

**Goal:** Apply content formatting to specific pages and position pages on screen

<html>
<div style="display:inline-block">
<div style="height:2em; background:black; padding:0.5em 1em; font-family:sans-serif; font-weight:bold; text-align:center;">
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">print</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">share</div>
  &nbsp;&nbsp;
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">&lt;</div>
  <div style="display:inline-block; border:1px solid white; background:white; padding:0.25em; font-weight:normal">page #</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">&gt;</div>
  &nbsp;&nbsp;
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">zoom</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">bookmark</div>
  &nbsp;&nbsp;
  <div style="display:inline-block; border:1px solid white; background:white; padding:0.25em 5em 0.25em 0.25em ; font-weight:normal">&nbsp;</div>
  <div style="display:inline-block; border:1px solid white; color:white; padding:0.25em">search</div>
</div>

<div style="background:gray; padding:1em; text-align:center;">
    <div style="display:inline-block;background:white;border:1px solid black; margin:0.5em">
    <div style="width:6.5em; height:9em; margin:1em; overflow:hidden; text-align:justify; color:green;">
      Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce     </div>
    </div>

    <div style="display:inline-block;background:white;border:1px solid black; margin:0.5em">
    <div style="width:6.5em; height:9em; margin:1em; overflow:hidden; text-align:justify; color:blue;">
posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
    </div>
    </div>
</div>
</div>
</html>
  * left page has green text, right page has blue text
  * even and odd pages are positioned differently to create a two-page view

====Ideas====
**Page selectors**

  #paged { width:6.5in; height:9in; overflow:paged; }
  #paged * { border: 1px solid black; }
  #paged::nth-child(even) { position:relative; left:<page-width> } /**


**Page View DOM**

//There are no formal proposals on DOM for overflow:paged at this time. If it is added, it should be similar what regions expose for same purposes//

In addition to API for page display, DOM for custom paged view needs writable access to page size and position
  * int PagedView.**pageTop**(pageNumber)
  * int PagedView.**pageLeft**(pageNumber)
  * int PagedView.**pageWidth**(pageNumber)
  * int PagedView.**pageHeight**(pageNumber)
  * void PagedView.**setPageTop**(pageNumber)
  * void PagedView.**setPageLeft**(pageNumber)
  * void PagedView.**setPageWidth**(pageNumber)
  * void PagedView.**setPageHeight**(pageNumber)

Content properties can be set by detecting range(s) of content on page, then traversing content and applying properties. Of course care has to be taken as it can't be assumed that modified content will still fit the same page.

**Example:**
  TODO
===== Magazine viewer =====

**Goal:** enable complex page design with multiple content flows and graphics, approaching or exceeding capabilities of print design

A magazine article (pretty simple one) could look like this.

{{:spec:magazine1.png}}

The user reads the magazine in a reader application, {{ :spec:magazine2.png}} with same options for page navigation control as in previous examples of page view.

Each individual page can have unique design and can include content from multiple sources: multiple text streams (main story, side bar, pull quotes) and images (some included in text, some placed directly as related visuals or advertisements).

//Note that at this point we don't make assumptions on how exactly each "page" is constructed. It may be automatically generated with some adaptive mechanism or it may be manually put together by a design team with print design experience. That distinction will be important for next use case, here we are looking at ways to represent the layout//


====Proposals====
===[css3-regions] with script===

The design of the viewer with custom controls is same as in previous examples. Difference is at the lowest level, where navigation to each page has to be implemented by managing a collectoin of elements, pseudo-elements or any other visual capable to represent an individual page. At this time pages as elements is the only available option.

Individual custom page may look like this. It may be read from a separate HTML source, built from script or generated in some other way (see the next section "Adaptive magazine with page templates")

The first page of this sample article has the following design decisions encoded in some way:
  * The page is built on  a 5-column grid
  * Main image is 66% width of the page and whatever height is derived from its aspect ratio. It is place at  top
right of the page
  * Secondary image takes the rest of the page width, it preserves its aspect ratio and placed at bottom left of the page
  * Title may overlap with the main image
  * Main story text wraps around everything else

The design can be implemented like this:

<code>
<style>
  .page { display:grid; grid-columns:(1fr)[5]; grid-rows:(auto)[2] 1fr; }
  .figures { grid-column-span:5; display:flexbox; flex-flow:reverse; z-index:1; }
  .figures > * { wrap-flow:both; }
  .title { grid-row:1; flow-from:title; z-index:2; wrap-through:none;}
  .subtitle { grid-row:2; flow-from:subtitle; z-index:2; wrap-through:none;}
  .sidebar { grid-row:3; grid-column:5; grid-row-align:end; grid-column-align:end; z-index:2;
             flow-from:sidebar; width:8em; wrap-flow:both;}
  .story { grid-row: grid-column-span:4; flow-from:story; z-index:0; }
</style>

<div style="page">
  <div class="figures">
    <img src="imgMain.jpg" style="width:66%;"></div>
    <img src="img1.jpg" style="min-width:200px; grid-row-align:end;"></div>
  </div>
  <div class="title"></div>
  <div class="subtitle"></div>
  <div class="sidebar"></div>
  <div class="story"></div>
</div>
</code>
====Ideas====
//Is it possible to achieve same results with further extensions of 'overflow:paged' and using pseudo-elements?//


===== Adaptive magazine with page templates =====

**Goal:** automatically generate complex pages based on content, encoded design intent and media properties

{{ :spec:magpageportrait.png}}{{ :spec:magpagelandscape.png}}

Online magazine must work on devices on different sizes, resolution and orientation. Just as any other adaptive content using media queries, same magazine will look very different on different devices.

Same content may end up on different pages, order of content may change, and content may change too (different images may be used in different orientation, some images may be dropped, some text may be replaced with links).

<html><div style="clear:both"></div></html>

====Proposals====
===[css3-regions] with script===
Programmatic solution has complete freedom in representation of page templates -- it can generate templates from scratch or load from any format - HTML, XML, JSON etc.

Selection algorithm also have no restrictions. Selection of specific template can be based on resolution, availability of specific content.

[[http://dev.w3.org/csswg/css3-regions/#cssom_view_and_css_regions|Regions OM]] provides
  * **regionOverflow** property to detect if flow in region has more content
  * event **regionLayoutUpdate** to inform about dynamic content change
Which is enough for generating pages this way

===IDPF page templates proposal===
[[http://epub-revision.googlecode.com/svn-history/r3025/trunk/src/proposals/css_page_templates/csspgt-doc.xhtml | IDPF Page Templates Proposal]] adds
  * declarative syntax for specifying page templates (called "page masters")
<code>
@page-master
{
    <propname>: <propvalue>;
    ...
    @region <name> {
    {
        <propname>: <propvalue>;
        ...
    }
}
</code>
  * specific set of rules and page-specific properties for page master selection, such as
    * 'min-page-width' and 'min-page-height' properites -- for template selectoin based on page dimensions
    * 'flow-priority', 'region-placement', 'required-regions', 'conflicting-regions' and other properties - for page master selection and tuning
===== Column breaks and page breaks in regions =====

**Goal:** provide a way to control layout in columns and pages, when columns, pages or both are parts of a template-based paged view

In magazine layout, what user percieves as "columns" can have irregular shape and position (and may be regions rather than boxes of multicol layout) and be placed to "pages" in a custom way.

Content flown throuh such "colums" needs to be able to use column breaks and page breaks, for example to make sure that a new chapter starts at a new page:

<HTML>
  <div id="page1" class="pageFrame" style="float:left; background:white; border:2px solid blue; margin:1em; width:18em; height:22em;">
    <div class="pageContent" style="margin:2em; width:13em; height:18em; position:relative; text-align:left; xoutline:1px solid lime">
      <div class="titleImg" style="background:salmon; width:8.3em; height:50%; float:right;"></div>
      <div class="mainStory">
        <div style="float:left; width:4em; height:18em; overflow:hidden; margin-right:0.5em;outline:2px solid green;">
          <div style="color:red; font-weight:bold">One</div>
          Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa.
          Fusce posuere, magna
        </div>
        <div style="float:left; width:4em; height:8.5em; overflow:hidden; margin:0.5em 0.5em 0;outline:2px solid green;">
pulvinar ultricies, purus lectus malesuada libero, sit amet
        </div>
        <div style="float:left; width:4em; height:8.5em; overflow:hidden; margin:0.5em -1em 0 0.5em;outline:2px solid green;">
        </div>
      </div>
    </div>
  </div>

    <div id="page1" class="pageFrame" style="float:left; background:white; border:2px solid blue; margin:1em; width:18em; height:22em;">
    <div class="pageContent" style="margin:2em; width:13em; height:18em; position:relative; text-align:left; xoutline:1px solid lime">
      <div class="mainStory">
        <div style="float:left; width:4em; height:10em; overflow:hidden; margin-right:0.5em;outline:2px solid green;">
          <div style="color:red; font-weight:bold">Two</div>
          Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
        </div>
        <div style="float:left; width:4em; height:10em; overflow:hidden; margin:4em 0.5em 0;outline:2px solid green;">
Maecenas porttitor congue massa.
          Fusce posuere, magna sed
        </div>
        <div style="float:left; width:4em; height:10em; overflow:hidden; margin:8em -1em 0 0.5em;outline:2px solid green;">
          pulvinar ultricies, purus lectus malesuada libero, sit amet
          commodo
          </div>
      </div>
    </div>
  </div>

<div style="clear:both"></div>

</HTML>

If "page" is an element or pseudo-element generated from template and rendered in a custom page viewer, layout engine may need additional information to know which column is first column of a page.

//Note that this may or may not be an issue, depending on how pages are built.//

**Proposal:**
//TODO. Named breaks have been discussed, add a specific proposal here//

===== Printing generated pages =====
In many of the page view situation, it is reasonable to expect that user would wish to print the content that is already preseneted in paged manner. They may prefer to either print the exact pages that they see on screen, or re-generate adaptive content for print. Either way, they will be printing content of page view, which may not be the root element of HTML document.

Selection of paged content for printing may have to be implemented directly in UA.

Running script before print (to generate a new set of pages for print media) -- may need an event on HTMLDocument (and not sure it is a good idea).

====== Issues ======
  * Paged view doesn't automatically mean "paged media" (which is commonly used as "for printing" and can't be repurposed). Should there be a way to declare that a paginating viewer (e.g. iframe) needs to render the same visuals as what would be printed?
  * Media queries for paged view/columns/regions?