From e2aba602e13c09fa56e5d33446d4be979d9ba1de Mon Sep 17 00:00:00 2001 From: iam4x Date: Wed, 3 May 2017 11:55:38 +0200 Subject: [PATCH 1/3] doc: connectStarRating --- .../star-rating/connectStarRating.js | 81 ++++++++++++++++--- 1 file changed, 70 insertions(+), 11 deletions(-) diff --git a/src/connectors/star-rating/connectStarRating.js b/src/connectors/star-rating/connectStarRating.js index fc9f71b70b..502c545f02 100644 --- a/src/connectors/star-rating/connectStarRating.js +++ b/src/connectors/star-rating/connectStarRating.js @@ -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(''); + * } + * + * StarRatingRenderingOptions.widgetParams.containerNode + * .find('li[data-refine-value]') + * .each(function() { $(this).off('click'); }); + * + * var listHTML = StarRatingRenderingOptions.items.map(function(item) { + * return '
  • ' + + * '' + + * item.stars.map(function(star) { return star === false ? '☆' : '★'; }).join(' ') + + * '& up (' + item.count + ')' + + * '
    • '; + * }); + * + * 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); From 8fb543b2c8015661060cba6f39acb26e5c96a646 Mon Sep 17 00:00:00 2001 From: iam4x Date: Wed, 3 May 2017 12:00:39 +0200 Subject: [PATCH 2/3] doc: connectStats --- src/connectors/stats/connectStats.js | 43 +++++++++++++++++++++------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/src/connectors/stats/connectStats.js b/src/connectors/stats/connectStats.js index 557658c270..48464cc09a 100644 --- a/src/connectors/stats/connectStats.js +++ b/src/connectors/stats/connectStats.js @@ -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); From b6b84377bc41c9eaf980dad81690e60380b3841c Mon Sep 17 00:00:00 2001 From: iam4x Date: Wed, 3 May 2017 15:33:43 +0200 Subject: [PATCH 3/3] doc: connectToggle --- src/connectors/toggle/connectToggle.js | 63 ++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 8 deletions(-) diff --git a/src/connectors/toggle/connectToggle.js b/src/connectors/toggle/connectToggle.js index 4d3261fcda..5c123fafa4 100644 --- a/src/connectors/toggle/connectToggle.js +++ b/src/connectors/toggle/connectToggle.js @@ -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") @@ -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 = '' + + * '' + + * ToggleRenderingOptions.value.name + '(' + ToggleRenderingOptions.value.count + ')' + + * ''; + * + * 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);