Intent to implement: Built-in see-more for amp-list

Motivation

Paging for <amp-list> is currently limited and requires integration with other AMP components. Adding a “see more” would simplify common use cases, and adding an option to automatically fetch more more elements would allow publishers to build powerful infinitely scrolling lists.

Proposed design

Add a “load-more” parameter to <amp-list> to indicate that more items are available to be fetched. The overflow element will be used to trigger the fetch. Paging rules will be guessed by the component according to these rules:

• If pageSize is specified, paging will use a pageSize+offset model where each additional page will have an offset parameter incremented by the value specified by pageSize.
• Otherwise a pageNum parameter will be added and then incremented.

Alternatively, a load-more-bookmark attribute can specified, in which case, a value will be retrieved from the response (based on simple dot notation) to be passed to the next page. For instance, if the first response is:

{
  "items": [ ... ],
  "bookmark": "foo"
}  

then <amp-list load-more-bookmark="bookmark" src="https://some/url"> would request a second page from https://some/url?bookmark=foo.

Additionally, If the load-more="auto" then the fetch will be triggered automatically if the component detects that the bottom of the list is near the bottom of the viewport.

The component will consider the list to be at its end and not fetch more items if:

• load-more-bookmark is specified and resolves to a falsey value
• response contains a truthy value for _end.
• the last response is empty.

Examples

Simple Case

  <amp-list src="https://some/url" load-more>
    <div overflow><button>See More</button</div>
  </amp-list>

The simplest case: Tapping the overflow div will load an additional page, appending page=n to the query parameters. The url for the 2nd page will be https://some/url?page=2, the 3rd: https://some/url?page=3, etc. The overflow div will be shown as long as the component determines that there is an additional page.

In the simple case, the list will be considered to be at its end and the overflow div will not be shown if _end is set in the json:

{
  "items": [...],
  "_end": true
}

or if items is empty:

{
  "items": []
}

pageSize+offset paging

  <amp-list src="https://some/url?pageSize=20" load-more>
    <div overflow><button>See More</button</div>
  </amp-list>

If pageSize is specified in the initial src, additional pages will have an incrementing offset value specified in the query params. In the above case the 2nd page would be https://some/url?pageSize=20&offset=20, the 3rd: https://some/url?pageSize=20&offset=40, etc.

Bookmark paging

  <amp-list src="https://some/url" load-more load-more-bookmark="next">
    <div overflow><button>See More</button</div>
  </amp-list>

If a load-more-bookmark attribute is specified, the response will be parsed and the bookmark value will be retrieved. In the example above, if the first response is:

{
  "items": [],
  "next": "page-2"
}

then ?next=page-2 will be appended to the src url as: https://some/url?next=page-2. If next is not found in the response:

{
  "items": []
}

or it resolves to a falsey value:

{
  "items": [],
  "nexts": false
}

then the list will be considered to be at its end and the overflow element will not be shown.

Automatic Paging

  <amp-list src="https://some/url" load-more="auto">
    <div overflow><button>See More</button</div>
  </amp-list>

If the load-more attribute is set to auto, then the component will load the next page automatically if the bottom of the amp-list component is near the bottom of the viewport. Initially, “near” will be 1.5x viewport height.

Note that the resize rules will still be followed in the automatic paging case. That means that the overflow div could still be shown in the case that a resize request is rejected.

/cc @choumx @ericlindley-g @aghassemi

[cathyxz]

Hi @clodisewp !

Generally speaking, usage questions about “how do I do X” are good questions to ask on stackoverflow and then link to in the using-amp channel of our slack (amphtml.slack.com).

For your specific question, I believe that the action attribute on <form> is not bindable based on our list of bindable attributes here. But if you have follow ups unrelated to this issue, feel free to follow up on slack with questions, or to open a separate issue if a bug / feature request is applicable.

I think this particular issue can be closed, since @cpapazian 's original load-more PR has merged long ago, and follow up work is being tracked by https://github.com/ampproject/amphtml/issues/14060. Thank you @cpapazian for your hard work setting all of this up!

[aghassemi]

I am thinking just a few CSS state classes on amp-list, might handle most cases:

• show-more-loading (while fetch is happening). Should be used to switch ‘overflow’ between a button and loading icon for instance (whether amp-list should do anything UI-wise here or leave it completely up to the author is up for debate). IMO we need this in the initial version.
• show-more-failed: If load more fails, the overflow button stays visible but this can allow author to add additional information or customize the button (eg. rename it to retry)

Somewhat related, one use-case to try with this API is ability to have a special “end of list” presentation. I think this might already be doable by server-side returning a different last item and having two templates and use conditional rendering feature of the amp-mustache to pick but worth exploring to see how it can be made easier. Maybe supporting a last-item template can become a first-class feature to remove the need to use conditional rendering.