Pagination of cms-loop - Githubissues

pandaulait commented 1 year ago

Is your feature request related to a problem? Please describe.

I would like best practices in creating pagination with pagination like below

The current spear only has the next button and the previous button, and even if you try to implement a page number button, it is difficult to know the total number of contents unless you use the API.

Pattern

[prev] [next]

[prev] [1] [2] ... [5] [6] [7] ... [12] [13] [next]

 [1] [2] ... [5] [6] [7] ... [12] [13]

Describe the solution you'd like

Describe alternatives you've considered

Additional context

mantaroh commented 1 year ago

@pandaulait

Thank you for filing this issue!
We have forget this feature completely.

As your proposal, we should implement this feature. But we need to consider the specification for it. 🤔

yoannes commented 1 year ago

Something like this would be nice.

<ul>
  <li cms-loop cms-content-type="feedback">
    <h1>{%= feedback_[フィールドID1] %}</h1>
    <p>{%= feedback_[フィールドID2] %}</p>
    <img data-src="{%= feedback_[フィールドID3] %}">

    <!-- Add here some kind of pagination -->
    <!-- Using component and maybe auto inject the data, it might be useful to create custom pagination -->
    <Pagination></Pagination>
  </li>
</ul>

<!-- The <Pagination> component -->
<ul>
  <li cms-pagination-loop>
    {%= #pagination_no %}
    {%= #pagination_total %}
    {%= #pagination_link %}
    {%= #pagination_current %}
  </li>
</ul>

mantaroh commented 1 year ago

@pandaulait @yoannes

How about looping over tags as well as looping over reference fields?

Something like this would be nice.

It's nice. In this case, I concern about generated HTML.

For example, we have a content which has category tag.

Contents: |- content A (technology tag) |- content B (keyboard tag) |- content C (technology tag)

If we allow sub loop for tags, generated List page might have all of pages grouping by tags.
I guess this feature is not attractive for SSG Tool.

Spear is SSG, so I guess we had better to provide tags routing feature.

Tag Routing

Tag routing feature will generate each content grouping by tags.

If [tags]/[alias].html has a element which has cms-item attribute only:

Spear will generate html into [tags]/ directory. Example:

<div cms-item content-type="blog">
  <p>{%= blog_title %}</p>
</div>

Generate File Result: /[tags]/content-a.html /[tags]/content-b.html /[tags]/content-c.html

Rendered Result:

<div>
  <p>Content A Title</p>
</div>

If [tags]/[alias].html has a cms-item's attribute element and cms-tag-loop's attribute element:

Spear will generate html into each tag directory. Example:

<div cms-tag-loop content-type="blog" cms-field="tags">
  <div cms-item content-type="blog">
    <p>{%= blog_title %}</p>
  </div>
</div>

Generate File Result: /technology/content-a.html /keyboard/content-b.html /technology/content-c.html

Rendered Result:

<div>
  <p>Content A Title</p>
</div>

If [tags]/index.html (mean simple list page) has a element which has cms-tag-loop attribute:

Spear generate List page into each tag directory. Example:

<div cms-tag-loop content-type="blog" cms-field="tags">
  <div cms-loop content-type="blog">
    <p>{%= blog_title %}</p>
    <a href="{%= blog_#alias %}">[Link]</a>
  </div>
</div>

Generate File Result: /technology/index.html /keyboard/index.html

Rendered Result(technology tag):

<div>
  <p>Content A Title</p>
  <a href="content-a">[Link]</a>
  <p>Content C Title</p>
  <a href="content-c">[Link]</a>
</div>

If index.html(mean simple list page) has a element which has cms-tag-loop attribute:

Spear generate List page into same directory. Example:

<div cms-tag-loop content-type="blog" cms-field="tags">
    <p>{%= blog_#tag%}</p>
    <a href="{%= blog_#tag %}/index.html">[Link]</a>
  </div>
</div>

Generate File Result: /index.html

Rendered Result(technology tag):

<div>
  <p>technology</p>
  <a href="technology/index.html">[Link]</a>
  <p>Content C Title</p>
  <a href="keyboard/index.html">[Link]</a>
</div>

(Japanese)

@pandaulait @yoannes

How about looping over tags as well as looping over reference fields?

Something like this would be nice.

とても良い提案です！1点出力されるHTMLが気になります。

例えば、以下のようなコンテンツとカテゴリを持ってるとします。

Contents: |- content A (technology tag) |- content B (keyboard tag) |- content C (technology tag)

もしネストされたループが行われた場合、タグでグループ化されたリストページが生成されることになります。これだけだと静的サイトジェネレーターの持つ意味が感じられないと考えます。

Spear は SSG ツールなので、タグのようなネストされたルーティングもサポートしたほうが良いと考えます。

タグルーティング

タグルーティング機能はタグごとにグループされたコンテンツをそれぞれ生成します。

もし[tags]/[alias].htmlという cms-item 属性だけを持つ要素を持ったページがある場合

Spear は [tags]/ ディレクトリに HTML を生成します。

例：

<div cms-item content-type="blog">
  <p>{%= blog_title %}</p>
</div>

生成されたページ： /[tags]/content-a.html /[tags]/content-b.html /[tags]/content-c.html

レンダリング結果：

<div>
  <p>Content A Title</p>
</div>

もしcms-item 属性を持つ要素と、cms-tag-loop 属性を持つ要素の両方を持つ [tags]/[alias].htmlがある場合

Spearは各タグのディレクトリに HTML を生成します。

例：

<div cms-tag-loop content-type="blog" cms-field="tags">
  <div cms-item content-type="blog">
    <p>{%= blog_title %}</p>
  </div>
</div>

生成されたページ： /technology/content-a.html /keyboard/content-b.html /technology/content-c.html

レンダリング結果：

<div>
  <p>Content A Title</p>
</div>

cms-tag-loop 属性を持つ要素だけを持つ [tags]/index.html ページ(つまり単純なリストページ)がある場合

Spaer は各タグのディレクトリにリストページを生成します。例：

<div cms-tag-loop content-type="blog" cms-field="tags">
  <div cms-loop content-type="blog">
    <p>{%= blog_title %}</p>
    <a href="{%= blog_#alias %}">[Link]</a>
  </div>
</div>

生成されたページ： /technology/index.html /keyboard/index.html

レンダリング結果( technology タグ)：

<div>
  <p>Content A Title</p>
  <a href="content-a">[Link]</a>
  <p>Content C Title</p>
  <a href="content-c">[Link]</a>
</div>

cms-tag-loop 属性を持つ要素だけが index.html ページ(つまり単純なリストページ)にある場合

Spear はソースファイルと同じディレクトリにリストページを生成します。例：

<div cms-tag-loop content-type="blog" cms-field="tags">
    <p>{%= blog_#tag%}</p>
    <a href="{%= blog_#tag %}/index.html">[Link]</a>
  </div>
</div>

生成されたページ： /index.html

レンダリング結果：

<div>
  <p>technology</p>
  <a href="technology/index.html">[Link]</a>
  <p>Content C Title</p>
  <a href="keyboard/index.html">[Link]</a>
</div>

mantaroh commented 1 year ago

Sorry It's my mistake. I write the wrong spec here.

an above comment is #123.

qst-exe commented 1 year ago

Not a suggestion, but a question. How do I specify the Pagination Size(10, 30, 50)? 🤔

mantaroh commented 1 year ago

Not a suggestion, but a question. How do I specify the Pagination Size(10, 30, 50)? 🤔

Thanks @qst-exe .

It's nice question. In above specification, there are not exist for specifying the pagination size.

How do we have the cms-pagination-size or cms-pagination-perpage like:

<li cms-pagination-loop cms-pagination-size="10">

qst-exe commented 1 year ago

Looks great! I agree to you! 👌

yoannes commented 1 year ago

as reference

https://vuetifyjs.com/en/components/paginations/#usage https://www.antdv.com/components/pagination

oxo-yuta commented 1 year ago

Don't we need the id for loop?? Since I thought, Pagination will be outside of the loop, like

<ul>
  <li cms-loop cms-content-type="feedback">
    <h1>{%= feedback_[フィールドID1] %}</h1>
    <p>{%= feedback_[フィールドID2] %}</p>
    <img data-src="{%= feedback_[フィールドID3] %}">

  </li>
</ul>

<Pagination></Pagination>

=========

<!-- The <Pagination> component -->
<ul>
  <li cms-pagination-loop>
    {%= #pagination_no %}
    {%= #pagination_total %}
    {%= #pagination_link %}
    {%= #pagination_current %}
  </li>
</ul>

I think we need id thing to connect Paginnation and Loop 🤔

mantaroh commented 12 months ago

Spec Draft

Spear supports built-in pagination for large contents that need to be split into multiple pages. Spear will generate common pagination variable, including previous/next page URLs, total number of pages, and more.

Paginated route names should use the [pagination].html. For instance, the file name /docs/[pagination].html will generate routes for /docs/1, /docs/2, etc.

You should write the element which has cms-loop in this [pagination].html

  <li cms-loop cms-content-type="feedback" cms-loop-id="feedback-loop">
    <h1>{%= feedback_title %}</h1>
    <p>{%= feedback_body %}</p>
  </li>

  <div cms-pagination cms-loop-id="feedback-loop">
    <a href="{%= #pagination_prev %}">[ Prev ]</a>
    <p>{%= #pagination_currrent %} / {%= #pagination_total %}
    <a href="{%= #pagination_next %}">[ Next ]</a>
  </div>

We can use the following variables:

pagination_prev : previous page URL
pagination_next : next page URL
pagination_current : current number
pagination_total : total pagination num

Nested Pagination

A more advanced use-case for pagination is nested pagination. This is when pagination is combined with other dynamic route params. You can use nested pagination to group your paginated collection by tag.

For example, if you want to group your paginated contents by some tag, you would use nested pagination by creating a /src/pages/[tag]/[pagination].html page that would match the following URLS:

/red/1 (tag=red)
/red/2 (tag=red)
/blue/1 (tag=blue)
/green/1 (tag=green)

仕様草案

Spear は、複数のページに分割する必要がある大規模なコンテンツのために、組み込みのページ分割をサポートします。Spear は、前ページ/次ページの URL、総ページ数など、一般的なページネーション変数を生成します。

ページ分割されたルート名は [pagination].html を使用します。例えば、/docs/[pagination].htmlというファイル名は、/docs/1、/docs/2などのルートを生成します。

この [pagination].html の中に cms-loop と cms-pagination を持つ要素を記述する必要があります。

  <li cms-loop cms-content-type="feedback" cms-loop-id="feedback-loop">
    <h1>{%= feedback_title %}</h1>
    <p>{%= feedback_body %}</p>
  </li>

  <div cms-pagination cms-loop-id="feedback-loop">
    <a href="{%= #pagination_prev %}">[ Prev ]</a>
    <p>{%= #pagination_currrent %} / {%= #pagination_total %}
    <a href="{%= #pagination_next %}">[ Next ]</a>
  </div>

cms-pagination と cms-loop との関係は cms-loop-id で紐付けることで実現します。

以下の変数が使えます：

pagination_prev : 前のページのURL
pagination_next : 次のページのURL
pagination_current : 現在のページ数
pagination_total : ページネーションの合計数

入れ子のページネーション

より高度なページネーションの使用例として、入れ子になったページネーションがあります。これはページ分割が他の動的なルートパラメータと組み合わされる場合です。入れ子のページ分割を使うことで、ページ分割されたコレクションをタグでグループ化できます。

たとえば、ページ分割されたコンテンツをタグでグループ化したい場合、/src/pages/[tag]/[pagination].html ページを作成することで入れ子ページ分割を使用します：

/red/1 (tag=red)
/red/2 (tag=red)
/blue/1 (tag=blue)
/green/1 (tag=green)

qst-exe commented 12 months ago

Can we also use cms-pagination-size as a variable?

https://github.com/unimal-jp/spear/issues/126#issuecomment-1457298564

vladinomo commented 12 months ago

Regarding attributes passed to spear tag, we need more parameters to meet demands for showing a variety of UI components. MUI - Pagination ranges gave me inspiration.

In some cases, we must show sibling items of a current page.
Also, we want to define the numbers of items around first/last items.

So, I propose additional attributes.

siblingCount
boundaryCount

spearタグに渡される属性に関して再現したいUIの多様性の観点から追加した方がいい要素をまとめました。

siblingCount
boundaryCount

の2つです。

以下のような用例で草案の内容だと表現できないと思いました。

選択中のページの前後のページへのリンクを生成したいとき
最初と最後のページに隣り合うリンクを生成/ないし数を指定したいとき

イメージとしてはMUI - Pagination ranges が参考になるかと思います

unimal-jp / spear

Pagination of cms-loop #126

Pattern

Tag Routing

タグルーティング

Spec Draft

pagination_prev : previous page URL

pagination_next : next page URL

pagination_current : current number

pagination_total : total pagination num

Nested Pagination

仕様草案

入れ子のページネーション