@searchstax-inc/searchstudio-ux-js 0.1.5 → 0.3.0

package/README.md

@@ -56,6 +56,13 @@ Initialization object
 
   `}`
 
+  `hooks?: {` - optional object that provides various hook options
+
+    `beforeSearch?: (props: ISearchObject) => ISearchObject | null;` - this function gets called before firing search. searchProps are being passed as a property and can be modified, if passed along further search will execute with modified properties, if null is returned then event gets canceled and search never fires.
+
+    `afterSearch?: (results: ISearchstaxParsedResult[]) => ISearchstaxParsedResult[];` - this function gets called after firing search and before rendering. It needs to return array of results that are either modified or untouched.
+  `};`
+
 }
 
 Initialization example
@@ -75,6 +82,16 @@ searchstax.initialize({
         return "Search results for: " + result.query;
       },
       ignoredKeys: [],
+    },
+    hooks: {
+      beforeSearch: function (props: ISearchObject) {
+        const propsCopy = { ...props };
+        return propsCopy;
+      },
+      afterSearch: function (results: ISearchstaxParsedResult[]) {
+        const copy = [...results];
+        return copy;
+      },
     }
   });
 ```
@@ -105,7 +122,26 @@ Our base theme is designed with this layout in mind but it is optional as all wi
 </div>
 ```
 
-## Input widget
+### widgets
+Following widgets are available:
+
+[Input Widget](#input-widget)
+
+[Result Widget](#result-widget)
+
+[Facets Widget](#facets-widget)
+
+[Pagination Widget](#pagination-widget)
+
+[SearchFeedback Widget](#searchfeedback-widget)
+
+[RelatedSearches Widget](#relatedsearches-widget)
+
+[ExternalPromotions Widget](#externalpromotions-widget)
+
+[sorting Widget](#sorting-widget)
+
+### Input Widget ###
 Initialization properties
 
 a. id of container where widget will be rendered
@@ -128,10 +164,6 @@ b. {
 
   `hooks?: {` - optional object that provides various hook options
 
-    `beforeSearch?: (props: ISearchObject) => ISearchObject | null;` - this function gets called before firing search. searchProps are being passed as a property and can be modified, if passed along further search will execute with modified properties, if null is returned then event gets canceled and search never fires.
-
-    `afterSearch?: (results: ISearchstaxParsedResult[]) => ISearchstaxParsedResult[];` - this function gets called after firing search and before rendering. It needs to return array of results that are either modified or untouched.
-
     `beforeAutosuggest?: (props: ISearchstaxSuggestProps) => ISearchstaxSuggestProps | null;` - this function gets called before firing autosuggest. autosuggestProps are being passed as a property and can be modified, if passed along further search will execute with modified properties, if null is returned then event gets canceled and search never fires.
 
     `afterAutosuggest?: (result: ISearchstaxSuggestResponse) => ISearchstaxSuggestResponse;`- this function gets called after autosuggest has values but before rendering. It needs to return same type of data but it can be modified.
@@ -154,15 +186,6 @@ example of input widget initialization with various options
  searchstax.addSearchInputWidget("searchstax-input-container", {
     suggestAfterMinChars: 3,
     hooks: {
-      beforeSearch: function (props: ISearchObject) {
-        const propsCopy = { ...props };
-        return propsCopy;
-      },
-      afterSearch: function (results: ISearchstaxParsedResult[]) {
-        const copy = [...results];
-        // copy.splice(0, 1);
-        return copy;
-      },
       afterAutosuggest: function (result: ISearchstaxSuggestResponse) {
         const copy = { ...result };
         return copy;
@@ -195,7 +218,7 @@ example of input widget initialization with various options
     },
   });
 ```
-## Result widget
+### Result Widget ###
 Initialization properties
 
 a. id of container where widget will be rendered
@@ -325,7 +348,7 @@ example of result widget initialization with various options
   });
 ```
 
-## Pagination widget
+### Pagination Widget ###
 Initialization properties
 
 a. id of container where widget will be rendered
@@ -335,7 +358,7 @@ b. {
   `templates?: {` - optional object that defines template override options
 
     `mainTemplate?: {` - optional object for overriding main template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. Data available: IPaginationData
         `previousButtonClass: string;` - class of previous page link within template,
         `nextButtonClass: string;` - class of next page link within template,
     `};`
@@ -373,14 +396,16 @@ example of pagination widget initialization with various options
   });
 ```
 
-## Facets widget
+### Facets Widget ###
 Initialization properties
 
 a. id of container where widget will be rendered
 
 b. {
 
-   `facetingType`: "and" | "or" | "showUnavailable" - type that determines how facets will behave,
+   `facetingType`: "and" | "or" | "showUnavailable" | "tabs" - type that determines how facets will behave,
+
+   'specificFacets?: string[]' - optional array of facet names that if provided will only render those facets
 
    `itemsPerPageDesktop`: number - default expanded facets for desktop,
 
@@ -389,12 +414,12 @@ b. {
   `templates?: {` - optional object that defines template override options
 
     `mainTemplateDesktop?: {` - optional object for overriding main template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language data available: IFacetsTemplateData
         `facetsContainerClass: string;` - class of container where facets will be placed
     `},`
 
     `mainTemplateMobile?: {` - optional object for overriding main mobile template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. data available: IFacetsTemplateData
         `facetsContainerId: string;` - id of container where facets will be placed
         `closeOverlayTriggerClasses: string[];` - class list of all elements that should trigger mobile overlay close action
         `filterByContainerId: string` - id of container where "Filter By" button will be rendered
@@ -402,23 +427,23 @@ b. {
     `},`
 
     `showMoreButtonContainerTemplate?: {` - optional object for overriding facet section show more/less template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. data available: IFacetData
         `showMoreButtonClass: string;` - class of container where show more/less button will be placed
     `},`
 
     `facetItemContainerTemplate?: {` - optional object for overriding facet container template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. data available: IFacetData
         'facetListTitleContainerClass: string;' - container class where facet category title will be rendered within template
         `facetListContainerClass: string;` - container class where facet items will be listed
        `},`
 
       `clearFacetsTemplate?: {` - optional object for overriding clear facets container template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. data available: {shouldShow: boolean}
         'containerId: string;' - container id where clear facets button will be rendered
        `},`
 
       `facetItemTemplate?: {` - optional object for overriding clear facet item template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. data available:  { ...IFacetValueData, isChecked }
         'inputCheckboxClass: string;' - class of checkboxes
         'checkTriggerClasses: string[];' - class list of elements that trigger facet select/unselect action
        `},`
@@ -429,7 +454,7 @@ b. {
        `},`
 
        `selectedFacetsTemplate?: {` - optional object for overriding selected facets template
-        `template: string;` - main template in Mustache templating language
+        `template: string;` - main template in Mustache templating language. data available: IFacetValue | IFacetValueRange
         'containerId: string;' - id where selected facets will be placed within the template
        `},`
   `};`
@@ -478,10 +503,10 @@ example of facets widget initialization with various options
         </div>
       </div>
       `,
-            facetsContainerId: ``,
+            facetsContainerClass: `searchstax-facets-container-mobile`,
             closeOverlayTriggerClasses: ["searchstax-facets-mobile-overlay-done","searchstax-search-close",],
-            filterByContainerId: ``,
-            selectedFacetsContainerId: ``,
+            filterByContainerClass: `searchstax-facets-pills-container`,
+            selectedFacetsContainerClass: `searchstax-facets-pills-selected`,
         },
         showMoreButtonContainerTemplate: {
             template: `
@@ -519,7 +544,7 @@ example of facets widget initialization with various options
         </div>
       {{/shouldShow}}
       `,
-            containerId: ``,
+            containerClass: `searchstax-facets-pill-clear-all`,
         },
         facetItemTemplate: {
             template: `
@@ -538,7 +563,7 @@ example of facets widget initialization with various options
         <div class="searchstax-facets-pill-label">Filter By</div>
       </div>
       `,
-            containerId: ``,
+            containerClass: `searchstax-facets-pill-filter-by`,
         },
         selectedFacetsTemplate: {
             template: `
@@ -547,13 +572,249 @@ example of facets widget initialization with various options
         <div class="searchstax-facets-pill-icon-close"></div>
       </div>
       `,
-            containerId: ``,
+            containerClass: `searchstax-facets-pill-facets`,
         },
 
     },
   });
 ```
 
+### SearchFeedback Widget ###
+Initialization properties
+
+a. id of container where widget will be rendered
+
+b. {
+
+  `templates?: {` - optional object that defines template override options
+
+    `main?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+    `};`
+
+  `};`
+
+}
+
+
+example of search feedback widget initialization with minimum options
+```
+searchstax.addSearchFeedbackWidget("search-feedback-container", {});
+```
+
+
+example of search feedback widget initialization with various options
+```
+searchstax.addSearchFeedbackWidget("search-feedback-container", {
+    templates: {
+      main: {
+          template: `
+        {{#searchExecuted}}
+            <div class="searchstax-feedback-container">
+                Showing <b>{{startResultIndex}} - {{endResultIndex}}</b> of <b>{{totalResults}}</b> results {{#searchTerm}} for "<b>{{searchTerm}}</b>" {{/searchTerm}}
+            </div>
+        {{/searchExecuted}}
+        `,
+      }
+    },
+  });
+```
+
+## RelatedSearches widget
+Initialization properties
+
+a. id of container where widget will be rendered
+
+b. {
+
+  `templates?: {` - optional object that defines template override options
+
+    `main?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `relatedSearchesContainerClass: string;` - class where related searches will be rendered within the template
+    `};`
+
+    `relatedSearch?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `relatedSearchContainerClass: string;` - class where related search item will be rendered within the template
+    `};`
+
+  `};`
+
+}
+
+
+example of search feedback widget initialization with minimum options
+```
+  searchstax.addRelatedSearchesWidget("searchstax-related-searches-container", {
+     relatedSearchesURL: "URL",
+     relatedSearchesAPIKey: "KEY"
+  })
+```
+
+
+example of search feedback widget initialization with various options
+```
+searchstax.addRelatedSearchesWidget("searchstax-related-searches-container", {
+     relatedSearchesURL: "URL",
+     relatedSearchesAPIKey: "KEY",
+    templates: {
+      main: {
+          template: `
+        {{#hasRelatedSearches}}
+            <div class="searchstax-related-searches-container" id="searchstax-related-searches-container">
+                Related searches: <span id="searchstax-related-searches"></span>
+                {{#relatedSearches}}
+                <span class="searchstax-related-search">
+
+                </span>
+            {{/relatedSearches}}
+            </div>
+        {{/hasRelatedSearches}}
+        `,
+          relatedSearchesContainerClass: `searchstax-related-search`,
+      },
+      relatedSearch: {
+          template: `
+        <span class="searchstax-related-search searchstax-related-search-item">
+            {{ related_search }}{{^last}}<span>,</span>{{/last}}
+        </span>
+        `,
+          relatedSearchContainerClass: `searchstax-related-search-item`,
+      },
+    },
+  });
+```
+
+### ExternalPromotions widget ###
+Initialization properties
+
+a. id of container where widget will be rendered
+
+b. {
+
+  `templates?: {` - optional object that defines template override options
+
+    `mainTemplate?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `externalPromotionsContainerId: string;` - id where external promotions will be rendered within the template
+    `};`
+
+    `externalPromotion?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+    `};`
+
+  `};`
+
+}
+
+
+example of search feedback widget initialization with minimum options
+```
+  searchstax.addExternalPromotionsWidget("searchstax-external-promotions-layout-container", {})
+```
+
+
+example of search feedback widget initialization with various options
+```
+searchstax.addExternalPromotionsWidget("searchstax-external-promotions-layout-container",  {
+    templates: {
+      mainTemplate: {
+          template: `
+        {{#hasExternalPromotions}}
+            <div class="searchstax-external-promotions-container" id="searchstax-external-promotions-container">
+                 External promotions go here
+            </div>
+        {{/hasExternalPromotions}}
+    `,
+          externalPromotionsContainerId: `searchstax-external-promotions-container`,
+      },
+      externalPromotion: {
+          template: `
+        <div class="searchstax-external-promotion searchstax-search-result">
+            <div class="icon-elevated"></div>
+            {{#url}}
+            <a href="{{url}}" data-searchstax-unique-result-id="{{uniqueId}}" class="searchstax-result-item-link"></a>
+            {{/url}}
+            <div class="searchstax-search-result-title-container">
+                <span class="searchstax-search-result-title">{{name}}</span>
+            </div>
+            {{#description}}
+            <p class="searchstax-search-result-description searchstax-search-result-common">
+            {{description}}
+            </p>
+            {{/description}}
+            {{#url}}
+            <p class="searchstax-search-result-description searchstax-search-result-common">
+            {{url}}
+            </p>
+            {{/url}}
+            </div>
+        </div>
+        `,
+      },
+    },
+  });
+```
+
+
+### Sorting Widget ###
+Initialization properties
+
+a. id of container where widget will be rendered
+
+b. {
+
+  `templates?: {` - optional object that defines template override options
+
+    `main?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `selectId: string;` - id of select element within the template
+    `};`
+
+  `};`
+
+}
+
+
+example of sorting widget initialization with minimum options
+```
+  searchstax.addSearchSortingWidget("search-sorting-container", {});
+```
+
+
+example of sorting widget initialization with various options
+```
+searchstax.addSearchSortingWidget("search-sorting-container", {
+    templates: {
+      main: {
+          template: `
+      {{#searchExecuted}}
+        {{#hasResultsOrExternalPromotions}}
+        <div class="searchstax-sorting-container">
+            <label class="searchstax-sorting-label" for="sort-by">Sort By</label>
+            <select id="searchstax-search-order-select" class="searchstax-search-order-select">
+                <option value="">
+                Relevance
+                </option>
+                <option value="date desc">
+                Newest Content
+                </option>
+                <option value="date asc">
+                Oldest Content
+                </option>
+            </select>
+        </div>
+        {{/hasResultsOrExternalPromotions}}
+      {{/searchExecuted}}
+      `,
+          selectId: `searchstax-search-order-select`
+      }
+    },
+  });
+```
+
+
 ## Template overrides
 Templates use mustache templating. For more info see https://github.com/janl/mustache.js