Skip to content

Commit

Permalink
Merge branch 'feat/instantsearch.js/v2' of github.com:algolia/instant…
Browse files Browse the repository at this point in the history 
…search.js into feat/instantsearch.js/v2
  • Loading branch information
Alexandre Stanislawski committed May 3, 2017
2 parents d9fd225 + b6b8437 commit 47d7e8d
Show file tree
Hide file tree
Showing 3 changed files with 157 additions and 30 deletions.
81 changes: 70 additions & 11 deletions src/connectors/star-rating/connectStarRating.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,27 +20,86 @@ search.addWidget(
Full documentation available at https://community.algolia.com/instantsearch.js/connectors/connectStarRating.html
`;

/**
* @typedef {Object} StarRatingItems
* @property {string} name Name corresponding to the number of stars.
* @property {string} value Number of stars as string.
* @property {number} count Count of matched results corresponding to the number of stars.
* @property {boolean[]} stars Array of length of maximum rating value with stars to display or not.
* @property {boolean} isRefined Indicates if star rating refinement is applied.
*/

/**
* @typedef {Object} CustomStarRatingWidgetOptions
* @property {string} attributeName Name of the attribute for faceting (eg. "free_shipping")
* @property {number} [max = 5] the maximum rating value
* @property {string} attributeName Name of the attribute for faceting (eg. "free_shipping").
* @property {number} [max = 5] The maximum rating value.
*/

/**
* @typedef {Object} StarRatingRenderingOptions
* @property {Object[]} items all the elements to render
* @property {function} createURL a function that creates a url for the next state (takes the filter value as parameter)
* @property {function} refine a function that switch to the next state and do a search (takes the filter value as parameter)
* @property {boolean} hasNoResults a boolean that indicates that the last search contains no results
* @property {InstantSearch} instantSearchInstance the instance of instantsearch on which the widget is attached
* @property {Object} widgetParams all original options forwarded to rendering
* @property {StarRatingItems[]} items Possible star ratings the user can apply.
* @property {function(item.value)} createURL Creates an URL for the next state (takes the item value as parameter).
* @property {function(item.value)} refine Switch to the next state and do a search (takes the filter value as parameter).
* @property {boolean} hasNoResults Indicates that the last search contains no results.
* @property {InstantSearch} instantSearchInstance Instance of instantsearch on which the widget is attached.
* @property {Object} widgetParams All original `CustomStarRatingWidgetOptions` forwarded to the `renderFn`.
*/

/**
* Connects a rendering function with the star rating business logic.
* **StarRating** connector provides the logic to build a custom widget that will give the user ability to refine search results by clicking on stars.
* The stars are based on the selected attributeName.
* @type {Connector}
* @param {function(StarRatingRenderingOptions, boolean)} renderFn function that renders the star rating widget
* @return {function(CustomStarRatingWidgetOptions)} a widget factory for star rating widget
* @param {function(StarRatingRenderingOptions, boolean)} renderFn Rendering function for the custom **StarRating** widget.
* @return {function(CustomStarRatingWidgetOptions)} Re-usable widget factory for a custom **StarRating** widget.
* @example
* var $ = window.$;
* var instantsearch = window.instantsearch;
*
* // custom `renderFn` to render the custom StarRating widget
* function renderFn(StarRatingRenderingOptions, isFirstRendering) {
* if (isFirstRendering) {
* StarRatingRenderingOptions.widgetParams.containerNode.html('<ul></ul>');
* }
*
* StarRatingRenderingOptions.widgetParams.containerNode
* .find('li[data-refine-value]')
* .each(function() { $(this).off('click'); });
*
* var listHTML = StarRatingRenderingOptions.items.map(function(item) {
* return '<li data-refine-value="' + item.value + '">' +
* '<a href="' + StarRatingRenderingOptions.createURL(item.value) + '">' +
* item.stars.map(function(star) { return star === false ? '☆' : '★'; }).join(' ') +
* '& up (' + item.count + ')' +
* '</a></li>';
* });
*
* StarRatingRenderingOptions.widgetParams.containerNode
* .find('ul')
* .html(listHTML);
*
* StarRatingRenderingOptions.widgetParams.containerNode
* .find('li[data-refine-value]')
* .each(function() {
* $(this).on('click', function(event) {
* event.preventDefault();
* event.stopPropagation();
*
* StarRatingRenderingOptions.refine($(this).data('refine-value'));
* });
* });
* }
*
* // connect `renderFn` to StarRating logic
* var customStarRating = instantsearch.connectors.connectStarRating(renderFn);
*
* // mount widget on the page
* search.addWidget(
* customStarRating({
* containerNode: $('#custom-star-rating-container'),
* attributeName: 'rating',
* max: 5,
* })
* );
*/
export default function connectStarRating(renderFn) {
checkRendering(renderFn, usage);
Expand Down
43 changes: 32 additions & 11 deletions src/connectors/stats/connectStats.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,42 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c

/**
* @typedef {Object} StatsRenderingOptions
* @property {number} hitsPerPage the maximum number of hits per page returned by Algolia
* @property {number} nbHits the number of hits in the result set
* @property {number} nbPages the number of pages computed for the result set
* @property {number} page the current page
* @property {number} processingTimeMS the time taken to compute the results inside the Algolia engine
* @property {string} query the query used for the current search
* @property {object} widgetParams all widget options forwarded to rendering
* @property {InstantSearch} instantSearchInstance the instance of instantsearch on which the widget is attached
* @property {number} hitsPerPage The maximum number of hits per page returned by Algolia.
* @property {number} nbHits The number of hits in the result set.
* @property {number} nbPages The number of pages computed for the result set.
* @property {number} page The current page.
* @property {number} processingTimeMS The time taken to compute the results inside the Algolia engine.
* @property {string} query The query used for the current search.
* @property {InstantSearch} instantSearchInstance Instance of instantsearch on which the widget is attached.
* @property {object} widgetParams All original `CustomStatsWidgetOptions` forwarded to the `renderFn`.
*/

/**
* Connects a rendering function with the stats business logic.
* **Stats** connector provides the logic to build a custom widget that will displays Algolia API search statistics (hits number and processing time).
* @type {Connector}
* @param {function(StatsRenderingOptions, boolean)} renderFn function that renders the stats widget
* @return {function} a widget factory for stats widget
* @param {function(StatsRenderingOptions, boolean)} renderFn Rendering function for the custom **Stats** widget.
* @return {function} Re-usable widget factory for a custom **Stats** widget.
* @example
* var $ = window.$;
* var instantsearch = window.instantsearch;
*
* // custom `renderFn` to render the custom Stats widget
* function renderFn(StatsRenderingOptions, isFirstRendering) {
* if (isFirstRendering) return;
*
* StatsRenderingOptions.widgetParams.containerNode
* .html(StatsRenderingOptions.nbHits + ' results found in ' + StatsRenderingOptions.processingTimeMS);
* }
*
* // connect `renderFn` to Stats logic
* var customStatsWidget = instantsearch.connectors.connectStats(renderFn);
*
* // mount widget on the page
* search.addWidget(
* customStatsWidget({
* containerNode: $('#custom-stats-container'),
* })
* );
*/
export default function connectStats(renderFn) {
checkRendering(renderFn, usage);
Expand Down
63 changes: 55 additions & 8 deletions src/connectors/toggle/connectToggle.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,15 @@ search.addWidget(
Full documentation available at https://community.algolia.com/instantsearch.js/connectors/connectToggle.html
`;

/**
* @typedef {Object} ToggleValue
* @property {string} name Human-readable name of the filter.
* @property {boolean} isRefined Indicates if the toggle is on or off.
* @property {number} count How many results are matched after applying the toggle refinement.
* @property {Object} onFacetValue Value of the toggle when it's on.
* @property {Object} offFacetValue Value of the toggle when it's off.
*/

/**
* @typedef {Object} CustomToggleWidgetOptions
* @property {string} attributeName Name of the attribute for faceting (eg. "free_shipping")
Expand All @@ -33,18 +42,56 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c

/**
* @typedef {Object} ToggleRenderingOptions
* @property {Object} value the value of the toggle with `name`, `isRefined`, `count`, `onFacetValue` and `offFacetValue`
* @property {function(facetValue)} createURL the function to create a url for the next state
* @property {function(facetValue)} refine updates to the next state
* @property {Object} widgetParams all `CustomToggleWidgetOptions` forwarded to rendering
* @property {InstantSearch} instantSearchInstance the instance of instantsearch on which the widget is attached
* @property {ToggleValue} value The current toggle value.
* @property {function()} createURL Creates an URL for the next state.
* @property {function(value)} refine Updates to the next state by applying the toggle refinement.
* @property {InstantSearch} instantSearchInstance Instance of instantsearch on which the widget is attached.
* @property {Object} widgetParams All original `CustomToggleWidgetOptions` forwarded to the `renderFn`.
*/

/**
* Connects a rendering function with the toggle business logic.
* **Toggle** connector provides the logic to build a custom widget that will provides an on/off filtering feature based on an attribute value.
* @type {Connector}
* @param {function(ToggleRenderingOptions, boolean)} renderFn function that renders the toggle widget
* @return {function(CustomToggleWidgetOptions)} a widget factory for toggle widget
* @param {function(ToggleRenderingOptions, boolean)} renderFn Rendering function for the custom **Toggle** widget.
* @return {function(CustomToggleWidgetOptions)} Re-usable widget factory for a custom **Toggle** widget.
* @example
* var $ = window.$;
* var instantsearch = window.instantsearch;
*
* // custom `renderFn` to render the custom ClearAll widget
* function renderFn(ToggleRenderingOptions, isFirstRendering) {
* ToggleRenderingOptions.widgetParams.containerNode
* .find('a')
* .off('click');
*
* var buttonHTML = '<a href="' + ToggleRenderingOptions.createURL() + '">' +
* '<input type="checkbox" value="' + ToggleRenderingOptions.value.name + '"' +
* ToggleRenderingOptions.value.isRefined ? ' checked' : '' + '/>' +
* ToggleRenderingOptions.value.name + '(' + ToggleRenderingOptions.value.count + ')' +
* '</a>';
*
* ToggleRenderingOptions.widgetParams.containerNode.html(buttonHTML);
* ToggleRenderingOptions.widgetParams.containerNode
* .find('a')
* .on('click', function(event) {
* event.preventDefault();
* event.stopPropagation();
*
* ToggleRenderingOptions.refine(ToggleRenderingOptions.value);
* });
* }
*
* // connect `renderFn` to Toggle logic
* var customToggle = instantsearch.connectors.connectToggle(renderFn);
*
* // mount widget on the page
* search.addWidget(
* customToggle({
* containerNode: $('#custom-toggle-container'),
* attributeName: 'free_shipping',
* label: 'Free Shipping (toggle single value)',
* })
* );
*/
export default function connectToggle(renderFn) {
checkRendering(renderFn, usage);
Expand Down

0 comments on commit 47d7e8d

Please sign in to comment.