Loop

<Loop> is a very commonly used React component installed by default in SocialStack projects. It is used to loop over lists of items typically from the API.

Sample Usage

Simple loop over everything of a given type (user in this case). Note that it will always be restricted by what you are permitted to see.

import Loop from 'UI/Loop';

...

     <Loop over='user'>
       {
           user=> {
                  return <p>{user.username}</p>;
           }
       }
     </Loop>

Optionally you can filter your results based on some particular where filter.

import Loop from 'UI/Loop';

...

     <Loop over='page' filter={
       {
              where: {
                     url: {
                            startsWith: '/en-admin/'
                     }
              }
       }
     }>
       {
           page => {
                  return <p>{page.title}</p>;
           }
       }
     </Loop>

Live loops

Sometimes you'll want a loop to update in realtime - whenever someone else on the site sends you a message, for example. By default any loop can update live like this, and all it takes is the live prop:

import Loop from 'UI/Loop';

...

     <Loop over='user' live>
       {
           user=> {
                  return <p>{user.username}</p>;
           }
       }
     </Loop>

Try creating a new user account - you'll see it appear on this loop without needing to do anything else, again assuming that you are permitted to see the content.

If you would like a callback whenever a new object is added via the live mechanism, you can use the onLiveCreate prop on your Loop.

Sorting

Filters support an order clause - see the page on filters for more information here.

Pagination

A loop can be automatically paginated using the UI/Paginator component. This is done using the paged prop:

import Loop from 'UI/Loop';

...

     <Loop over='user' paged={10}>
       {
           user=> {
                  return <p>{user.username}</p>;
           }
       }
     </Loop>

Paged itself has multiple configuration options, including the ability to specify which pagination component to use. At its basics though, just setting it to the number of items to display per page will get things moving.

For advanced usage, the available configuration options are like so:

import Loop from 'UI/Loop';

...

<Loop paged={{
    pageSize: 10,
    showInput: false,
    showSummary: false,
    maxLinks: 3,
    module: 'UI/MyCustomPaginator'
}} ...>

The module option should be used carefully to avoid inconsistency (i.e. a need to specify it on every loop would potentially arise). Instead, it's recommended to uninstall the default UI/Paginator and create a custom component of the same name.

If you'd like to restrict the result count but without a paginator visible, you can directly set pageSize and pageIndex into the filter. This is effectively what the paged prop does, along with displaying its additional UI.

import Loop from 'UI/Loop';

...

<Loop filter={{
    pageSize: 10,
    pageIndex: 0 // optional
}} ...>

Includes

Includes are a mechanism in SocialStack for obtaining related data in the same API call. They are a feature of the public API but are exposed via Loop too:

    import Loop from 'UI/Loop';
    
    ...
    
    <Loop over='page' includes={['creatorUser']}>
        {page => {
            return <div>
                The page "{page.title}" was created by {page.creatorUser.username}
            </div>;
        }}
    </Loop>

Looping over just included items

If you'd like to have live includes or loop over items which are "on" something else, then you can use the on filter:

    import Loop from 'UI/Loop';
    
    ...
    
    <Loop over='tag' filter={{on: {type: 'Page', id: 4}}}>
        {tag => {
            return {tag.name};
        }}
    </Loop>

Unlike regular includes, these loops support going live too.