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

package/README.md

@@ -28,35 +28,7 @@ After importing Searchstax class a new instance needs to be created:
 ```const searchstax = new Searchstax();```
 
 ## Initialization
-Initialization object
-
-{
-
-  `language: string;` - language code. Example: 'en'
-
-  `searchURL: string;` - SeachStudio select endpoint
-
-  `suggesterURL: string;` - SeachStudio suggest endpoint
-
-  `trackApiKey: string;` - Api key used for tracking events
-
-  `searchAuth: string;` - Authentication value. based on authType it's either a token value or basic auth value
-
-  `authType: 'token' | 'basic';` - Type of authentication
-
-  `router: {` - optional object containing router settings
-
-    'enabled: boolean' - if enabled navigation will history and will keep track of search state
-
-    'routeName: string' - prefix name for all search properties
-
-    'title: (result: ISearchObject) => string' - function that will update page title
-
-    `ignoredKeys: string[]` - array of keys to ignore and not keep track of
-
-  `}`
-
-}
+Initialization object needs to be of type: [ISearchstaxConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/connector.interface.ts#L5)
 
 Initialization example
 ```
@@ -75,6 +47,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,40 +87,31 @@ Our base theme is designed with this layout in mind but it is optional as all wi
 </div>
 ```
 
-## Input widget
-Initialization properties
-
-a. id of container where widget will be rendered
+### widgets
+Following widgets are available:
 
-b. {
+[Input Widget](#input-widget)
 
-  `suggestAfterMinChars: number;` - controls how many characters the UI should accept at the minimum before showing suggestions
+[Result Widget](#result-widget)
 
-  `templates?: {` - optional object that defines template override options
+[Facets Widget](#facets-widget)
 
-    `mainTemplate?: {` - optional object for overriding main template
-        `template: string;` - main template in Mustache templating language
-        `searchInputId: string;` - id of search input within the mainTemplate
-    `};`
+[Pagination Widget](#pagination-widget)
 
-    `autosuggestItemTemplate?: {` - autosuggest item template in Mustache
-      `template: string;` - autosuggest template in Mustache templating language
-    `};`
-  `};`
+[SearchFeedback Widget](#searchfeedback-widget)
 
-  `hooks?: {` - optional object that provides various hook options
+[RelatedSearches Widget](#relatedsearches-widget)
 
-    `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.
+[ExternalPromotions Widget](#externalpromotions-widget)
 
-    `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.
+[sorting Widget](#sorting-widget)
 
-    `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.
+### Input Widget ###
+Initialization properties
 
-  `};`
+a. id of container where widget will be rendered
 
-}
+b. Input widget config object of type: [ISearchstaxSearchInputConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchInputConfig.interface.ts#L4)
 
 
 example of input widget initialization with minimum options
@@ -154,15 +127,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,39 +159,12 @@ example of input widget initialization with various options
     },
   });
 ```
-## Result widget
+### Result Widget ###
 Initialization properties
 
 a. id of container where widget will be rendered
 
-b. {
-
-  `searchResultUniqueIdAttribute?: string;` - this is needed only if searchResultTemplate is overridden. searchResultTemplate needs to have unique result id property. Default is data-searchstax-unique-result-id="uniqueId". see example below on how it is used
-
-  `templates?: {` - optional object that defines template override options
-
-    `mainTemplate?: {`
-        template: string; - main template in Mustache templating language.,
-        searchResultsContainerId: string;` - this is needed only if mainTemplate is overridden. It points to an element in the template where results need to be rendered
-    }
-
-    `searchResultTemplate?: {`
-        template: string - result template using Mustache. ISearchstaxParsedResult is passed to the template and all its properties are available to be used when rendering;
-        searchResultUniqueIdAttribute?: string - this is needed only if searchResultTemplate is overridden. searchResultTemplate needs to have unique result id property. Default is data-searchstax-unique-result-id="niqueId". see example below on how it is used
-    }
-
-    `noSearchResultTemplate?: {`
-        template: string - Mustache template for no results section override. spellingSuggestion and searchTerm are values available in the template
-    }
-
-  `};`
-
-  `hooks?: {` - optional object that provides various hook options
-
-    `afterLinkClick?: (resultClicked: ISearchstaxParsedResult) => ISearchstaxParsedResult | null;` - function is called after user clicks result and passes that result as a property. when result is passed along tracking will execute and user will be navigated if null is returned events are canceled and nothing happens.
-
-  `};`
-}
+b. Result widget config object of type: [ISearchstaxSearchResultsConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchResultsConfig.interface.ts#L3)
 
 example of results widget initialization with minimum options
 ```
@@ -325,23 +262,12 @@ example of result widget initialization with various options
   });
 ```
 
-## Pagination widget
+### Pagination 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
-        `previousButtonClass: string;` - class of previous page link within template,
-        `nextButtonClass: string;` - class of next page link within template,
-    `};`
-  `};`
-
-}
+b. Pagination widget config object of type: [ISearchstaxSearchPaginationConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchPaginationConfig.interface.ts#L1)
 
 example of pagination widget initialization with minimum options
 ```
@@ -373,68 +299,12 @@ 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,
-
-   `itemsPerPageDesktop`: number - default expanded facets for desktop,
-
-   `itemsPerPageMobile`: number - default expanded facets for mobile,
-
-  `templates?: {` - optional object that defines template override options
-
-    `mainTemplateDesktop?: {` - optional object for overriding main template
-        `template: string;` - main template in Mustache templating language
-        `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
-        `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
-        'selectedFacetsContainerId: string' - id of container where selected facets will be listed
-    `},`
-
-    `showMoreButtonContainerTemplate?: {` - optional object for overriding facet section show more/less template
-        `template: string;` - main template in Mustache templating language
-        `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
-        '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
-        '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
-        'inputCheckboxClass: string;' - class of checkboxes
-        'checkTriggerClasses: string[];' - class list of elements that trigger facet select/unselect action
-       `},`
-
-       `filterByTemplate?: {` - optional object for overriding filter by button template
-        `template: string;` - main template in Mustache templating language
-        'containerId: string;' - id where button will be placed within the template
-       `},`
-
-       `selectedFacetsTemplate?: {` - optional object for overriding selected facets template
-        `template: string;` - main template in Mustache templating language
-        'containerId: string;' - id where selected facets will be placed within the template
-       `},`
-  `};`
-
-}
+b. Facets widget config object of type: [ISearchstaxSearchFacetsConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchFacetsConfig.interface.ts#L1)
 
 example of facets widget initialization with minimum options
 ```
@@ -478,10 +348,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 +389,7 @@ example of facets widget initialization with various options
         </div>
       {{/shouldShow}}
       `,
-            containerId: ``,
+            containerClass: `searchstax-facets-pill-clear-all`,
         },
         facetItemTemplate: {
             template: `
@@ -538,7 +408,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 +417,197 @@ 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. SearchFeedback widget config object of type: [ISearchstaxSearchFeedbackConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchFeedbackConfig.interface.ts#L1)
+
+
+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. RelatedSearches widget config object of type: [ISearchstaxRelatedSearchesConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchRelatedSearchesConfig.interface.ts#L1)
+
+
+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. ExternalPromotions widget config object of type: [ISearchstaxExternalPromotionsConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchExternalPromotionsConfig.interface.ts#L1)
+
+
+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. Sorting widget config object of type: [ISearchstaxSearchSortingConfig](https://github.com/searchstax/searchstudio-ux-js/blob/main/src/interfaces/searchSortingConfig.interface.ts#L1)
+
+
+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