ReactiveList
ReactiveList
creates a data-driven result list UI component. This list can reactively update itself based on changes in other components or changes in the database itself.
Example uses:
- showing a feed of results based on the applied search criteria.
- streaming realtime feed updates based on applied criteria like in a newsfeed.
Usage
Basic Usage
<template>
<reactive-list
:react=`{
"and": ["CitySensor", "SearchSensor"]
}`
>
<div slot="renderData" slot-scope="{ item }">
{{ item.title }}
</div>
</reactive-list>
</template>
Usage With All Props
<reactive-list
componentId="SearchResult"
dataField="ratings"
paginationAt="bottom"
loader="Loading Results.."
sortBy="desc"
:stream="true"
:pagination="false"
:pages="5"
:size="10"
:showResultStats="true"
:react=`{
and: ["CitySensor", "SearchSensor"]
}`
/>
Props
-
componentId
String
unique identifier of the component, can be referenced in other components’react
prop. -
dataField
String
data field to be connected to the component’s UI view. It is useful for providing a sorting context i.e. results would be sorted based on thedataField
. -
excludeFields
String Array
[optional]
fields to be excluded in search results. -
includeFields
String Array
[optional]
fields to be included in search results. -
stream
Boolean
[optional]
whether to stream new result updates in the UI. Defaults tofalse
.stream: true
is appended to the streaming hit objects, which can be used to selectively react to streaming changes (eg. showing fade in animation on new streaming hits, Twitter/Facebook like streams, showing the count of new feed items available like 2 New Tweets) -
pagination
Boolean
[optional]
pagination <> infinite scroll switcher. Defaults tofalse
, i.e. an infinite scroll based view. When set totrue
, a pagination based list view with page numbers will appear. -
paginationAt
String
[optional]
Determines the position where to show the pagination, only applicable when pagination prop is set totrue
. Accepts one oftop
,bottom
orboth
as valid values. Defaults tobottom
. -
pages
Number
[optional]
number of user selectable pages to be displayed when pagination is enabled. Defaults to 5. -
sortBy
String
[optional]
sort the results by eitherasc
ordesc
order. It is an alternative tosortOptions
, both can’t be used together. -
sortOptions
Object Array
[optional]
an alternative to thesortBy
prop,sortOptions
creates a sorting view in the ReactiveList component’s UI. Each array element is an object that takes three keys:label
- label to be displayed in the UI.dataField
- data field to use for applying the sorting criteria on.sortBy
- specified as eitherasc
ordesc
.
-
size
Number
[optional]
number of results to show per view. Defaults to 10. -
loader
String|slot-scope
[optional]
display to show the user while the data is loading, acceptsString
orJSX
markup. -
showResultStats
Boolean
[optional]
whether to show result stats in the form of results found and time taken. Defaults totrue
. -
react
Object
[optional]
a dependency object defining how this component should react based on the state changes in the sensor components. -
URLParams
Boolean
[optional]
when set adds the current page number to the url. Only works whenpagination
is enabled. -
renderData
Function|slot-scope
[optional]
returns a list element object to be rendered based on theres
data object. This callback function prop or slot is called for each data item rendered in the ReactiveList component’s view. For example,<div slot="renderData" slot-scope="{ item }"> <a class="full_row single-record single_record_for_clone" key="item._id" > <div class="text-container full_row" :style="{ paddingLeft: '10px' }"> <div class="text-head text-overflow full_row"> <span class="text-head-info text-overflow"> {{ item.name ? item.name : "" }} - {{ item.brand ? item.brand : "" }} </span> <span class="text-head-city">{{ item.brand ? item.brand : "" }}</span> </div> <div class="text-description text-overflow full_row"> <ul class="highlight_tags"> {{ item.price ? `Priced at $${{ item.price }}` : "Free Test Drive" }} </ul> </div> </div> </a> </div>
-
renderAllData
Function|slot-scope
[optional]
works like renderData but all the data objects are passed to the callback function or slot. It accepts an object with these properties:results
,streamResults
,loadMore
,base
&triggerClickAnalytics
.results
: An array of results obtained from the applied query.streamResults
: An array of results streamed since the applied query, aka realtime data. Here, a meta property_updated
or_deleted
is also present within a result object to denote if an existing object has been updated or deleted.loadMore
: A callback function to be called to load the next page of results into the view. The callback function is only applicable in the case of infinite loading view (i.e.pagination
prop set tofalse
).base
: An internally calculated value, useful to calculate analytics. Read MoretriggerClickAnalytics
: A function which can be called to register a click analytics. Read More
-
renderResultStats
Function|slot-scope
[optional] renders custom result stats using a callback function that takesstats
object as parameter and expects it to return a string or html.stats
object contains following propertiestotalResults
- Total number of results foundtotalPages
- Total number of pages found based on current page sizecurrentPage
- Current page number for which data is being rendereddisplayedResults
- Number of results displayed in current view-
time
- Time taken to find total results:renderResultStats=" function(stats){ return ( `Showing ${stats.displayedResults} of total ${stats.totalResults} in ${stats.time} ms` ) } "
-
renderError
String|Function|slot-scope
[optional] can be used to render an error message in case of any error.
:renderError="error => (
<div>
Something went wrong!<br/>Error details<br/>{error}
</div>
)
"
or
<template slot="renderError" slot-scope="error">
<div>
Something went wrong!<br/>Error details<br/>{{ error }}
</div>
</template>
- renderNoResults
String|Function|slot-scope
[optional] show custom message or component when no results found. - defaultQuery
Function
[optional]
applies a default query to the result component. This query will be run when no other components are being watched (via React prop), as well as in conjunction with the query generated from the React prop. The function should return a query.
Demo
Styles
ReactiveList
component supports innerClass
prop with the following keys:
resultsInfo
sortOptions
resultStats
noResults
button
pagination
active
list
poweredBy
Read more about it here.
Extending
ReactiveList
component can be extended to
- customize the look and feel with
className
, - render individual result data items using
renderData
, - render the entire result data using
renderAllData
. - connect with external interfaces using
queryChange
.
<ReactiveList
...
className="custom-class"
:renderData=`
function({ item }) {
return(
<div>
{ item.data }
</div>
)
}
`
@queryChange=`
function(prevQuery, nextQuery) {
// use the query with other js code
console.log('prevQuery', prevQuery);
console.log('nextQuery', nextQuery);
}
`
/>
- className
String
CSS class to be injected on the component container. - renderData
Function|slot-scope
[optional]
a callback function or slot-scope where user can define how to render the view based on the data changes. -
renderAllData
Function|slot-scope
[optional]
an alternative callback function or slot-scope torenderData
, where user can define how to render the view based on all the data changes.
It accepts an object with these properties:results
,streamResults
,loadMore
,base
&triggerClickAnalytics
.results
: An array of results obtained from the applied query.streamResults
: An array of results streamed since the applied query, aka realtime data. Here, a meta property_updated
or_deleted
is also present within a result object to denote if an existing object has been updated or deleted.loadMore
: A callback function to be called to load the next page of results into the view. The callback function is only applicable in the case of infinite loading view (i.e.pagination
prop set tofalse
).base
: An internally calculated value, useful to calculate analytics. Read MoretriggerClickAnalytics
: A function which can be called to register a click analytics. Read More
Note
The
streamResults
parameter will be[]
unlessstream
prop is set totrue
. Check the handling streaming guide for more info.
Events
-
queryChange
is an event which accepts component’s prevQuery and nextQuery as parameters. It is called everytime the component’s query changes. This event is handy in cases where you want to generate a side-effect whenever the component’s query would change. -
pageChange
called when the current page is changed. If not defined,window
will be scrolled to the top of the page. -
pageClick accepts a function which is invoked with the updated page value when a pagination button is clicked. For example if ‘Next’ is clicked with the current page number as ‘1’, you would receive the value ‘2’ as the function parameter.
-
data
Function
[optional] gets triggered after data changes, which returns an object with these properties:results
,streamResults
,loadMore
,base
&triggerClickAnalytics
. -
resultStats
Function
[optional] gets triggered after stats changes, which returns an object with these properties:totalResults
- Total number of results foundtotalPages
- Total number of pages found based on current page sizecurrentPage
- Current page number for which data is being rendereddisplayedResults
- Number of results displayed in current viewtime
- Time taken to find total results
- error
gets triggered in case of an error and provides the
error
object, which can be used for debugging or giving feedback to the user if needed.
Note:
The fundamental difference between
pageChange
andpageClick
is thatpageClick
is only called on a manual interaction with the pagination buttons, whereas,pageChange
would also be invoked if some other side effects caused the results to update which includes updating filters, queries or changing pages. The behaviour of these two may change in the future versions as we come up with a better API.
- error invoked when query listener throws any error