# sitesearch-ux-vue Library to build Site Search page ## changelog changelog is documented at CHANGELOG.md ## Installation npm install following package `npm install --save @searchstax-inc/searchstudio-ux-vue` Add following code to `` ``` ``` ## Usage After importing SearchstaxWrapper component needs to wrap all other components: ``` // other components will go there ``` ## Initialization 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 ``` sampleConfig = { language: "en", model: "Main Profile", searchURL: "", suggesterURL: "", trackApiKey: "", searchAuth: "", authType: "basic", router: { enabled: true, routeName: "searchstax", title: (result: ISearchObject) => { 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; }, } }; ``` ## Initial layout Our base theme is designed with this layout in mind but it is optional as all widgets have id parameters and can be attached to any element. ``` ``` ### widgets Following widgets are available: [Answer Widget](#answer-widget) [Input Widget](#input-widget) [Location Widget](#location-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) ### Answer Widget ### SearchStax Site Search solution offers Vue widgets to assist in building your custom search page. The SearchstaxAnswerWidget component for Vue provides an AI answer widget for your searches. **Usage** ``` ``` **Props** - showMoreAfterWordCount - number(default 100) determining after how many words UI will show “Show More” view. - feedbackWidget – an optional object that configures thumbs-up and thumbs-down feedback functionality. Example of feedbackWidget config: ``` const feedbackConfig = { renderFeedbackWidget: true, emailOverride: searchstaxEmailOverride, thumbsUpValue: 10, thumbsDownValue: 0 } ``` **searchAnswerTemplate** The templates prop allows customizing the answer UI. It receives the following props: - answerData – Data object of type: ISearchstaxAnswerData - showMore - Handler for exiting the show more view **Example** ``` ``` ### Input Widget ### SearchStax Site Search solution offers a Vue search-input widget to assist with your custom search page. The SearchstaxInputWidget provides a search input box with autosuggest/autocomplete functionality. **Usage** ``` ``` **Props** - suggestAfterMinChars - default 3. Number of characters needed for autosuggest to start triggering - beforeAutosuggest - callback function that 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 - callback function that gets called after autosuggest has values but before rendering. It needs to return same type of data but it can be modified. **inputWidgetTemplate** The inputTemplate prop allows customizing the input UI. It receives the following props: - suggestions – Array of autosuggestion results - onMouseLeave - Handler for mouse leave event - onMouseOver - Handler for mouse over event - onMouseClick - Handler for mouse click event **example** ``` ``` ### Location Widget ### SearchStax Site Search solution offers a Vue search-location widget to assist with your custom search page. The SearchstaxLocationWidget provides a location search input with location-based search functionality. **Usage** ``` const config = { appId: "APP_ID", relatedSearchesAPIKey: "KEY" } const locationWidgetConfig = { locationDecode: (term: string): Promise => { return new Promise((resolve) => { // make a request to google geocoding API to retrieve lat, lon and address const geocodingAPIKey = "GEOCODING_API_KEY"; const geocodingURL = `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent( term )}&key=${geocodingAPIKey}`; fetch(geocodingURL) .then((response) => response.json()) .then((data) => { if (data.status === "OK" && data.results.length > 0) { const result = data.results[0]; const location = { lat: result.geometry.location.lat, lon: result.geometry.location.lng, address: result.formatted_address, }; resolve(location); } else { resolve({ address: undefined, lat: undefined, lon: undefined, error: true, }); } }) .catch(() => { resolve({ address: undefined, lat: undefined, lon: undefined, error: true, }); }); }); }, locationDecodeCoordinatesToAddress: (lat: string, lon: string): Promise => { return new Promise((resolve) => { fetch( `https://geocoding-staging.searchstax.co/reverse?location=${lat},${lon}&components=country:US&app_id=${config.appId}`, { method: "GET", headers: { Authorization: `Token ${config.relatedSearchesAPIKey}`, }, } ) .then((response) => response.json()) .then((data) => { if (data.status === "OK" && data.results.length > 0) { const result = data.results[0]; resolve({ address: result.formatted_address, lat: lat, lon: lon, error: false, }); } else { resolve({ address: undefined, lat: lat, lon: lon, error: true, }); } }) .catch(() => { resolve({ address: undefined, lat: lat, lon: lon, error: true, }); }); }); }, locationSearchEnabled: false, locationValuesOverride: { locationDistanceEnabled: true, filterValues: ["any", "1000"], filterUnit: "miles", locationFilterDefaultValue: "any" }, } ``` **Props** - locationDecode - callback function to override location decoding - locationDecodeCoordinatesToAddress - callback function to override location decoding **Template Override** The searchLocationTemplate prop allows customizing the location input UI. It receives the following props: - locationData – data containing info on when to show certain elements - inputValue – value of location input - locationBlur - Handler for location input blur - radiusChange - Handler for location radius change - selectValue - Value of radius select - inputChange - location input change handler - locationError - boolean stating if location has error - getCurrentLocation - Handler for getting current location from browser **Example** ``` const config = { appId: "APP_ID", relatedSearchesAPIKey: "KEY" } const locationWidgetConfig = { locationDecode: (term: string): Promise => { return new Promise((resolve) => { // make a request to google geocoding API to retrieve lat, lon and address const geocodingAPIKey = "GEOCODING_API_KEY"; const geocodingURL = `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent( term )}&key=${geocodingAPIKey}`; fetch(geocodingURL) .then((response) => response.json()) .then((data) => { if (data.status === "OK" && data.results.length > 0) { const result = data.results[0]; const location = { lat: result.geometry.location.lat, lon: result.geometry.location.lng, address: result.formatted_address, }; resolve(location); } else { resolve({ address: undefined, lat: undefined, lon: undefined, error: true, }); } }) .catch(() => { resolve({ address: undefined, lat: undefined, lon: undefined, error: true, }); }); }); }, locationDecodeCoordinatesToAddress: (lat: string, lon: string): Promise => { return new Promise((resolve) => { fetch( `https://geocoding-staging.searchstax.co/reverse?location=${lat},${lon}&components=country:US&app_id=${config.appId}`, { method: "GET", headers: { Authorization: `Token ${config.relatedSearchesAPIKey}`, }, } ) .then((response) => response.json()) .then((data) => { if (data.status === "OK" && data.results.length > 0) { const result = data.results[0]; resolve({ address: result.formatted_address, lat: lat, lon: lon, error: false, }); } else { resolve({ address: undefined, lat: lat, lon: lon, error: true, }); } }) .catch(() => { resolve({ address: undefined, lat: lat, lon: lon, error: true, }); }); }); }, locationSearchEnabled: false, locationValuesOverride: { locationDistanceEnabled: true, filterValues: ["any", "1000"], filterUnit: "miles", locationFilterDefaultValue: "any" }, }
NEAR
WITHIN
``` ### Result Widget ### The SearchStax Site Search solution offers a Vue results widget to assist with your custom search page. The SearchstaxResultsWidget component displays the search results. **Usage** ``` ``` **Props** - renderMethod – either “pagination” or “infiniteScroll”. - resultsPerPage – number of results on a page. - afterLinkClick – Callback function invoked when a result link is clicked. Allows modifying the result object. **Result Template Override** The resultsTemplate prop allows customizing the result UI. It receives following props: - searchResults - Array of result items - resultClicked - Handler for result click events **No Results Template Override** The noResultTemplate prop allows customizing the result UI. It receives following props: - searchResults - Array of result items - resultClicked - Handler for result click events - searchTerm - Search input term - metadata - Metadata object - executeSearch - Handler for executing srearch - store - Main store of app **Example of default render method** ``` ``` **Example of infinite scroll and pagination render methods** ``` ``` ### Pagination Widget ### The SearchStax Site Search solution offers a Vue pagination widget to assist with you custom search page. The SearchstaxPaginationWidget component displays pagination controls for search results. **Usage** ``` ``` **Main Template Override** Main template for the pagination controls. It receives following props: - paginationData – Pagination info object - previousPage – Handler for previous page click - nextPage - – Handler for next page click **Infinite Scroll Template Override** Main template for the pagination controls in infinite scroll mode. It receives following props: - isLastPage - boolean, true if its last page - results - results.length can be used if there are results **Example** ``` // infinite scroll example ``` ### Facets Widget ### The SearchStax Site Search solution offers a Vue SearchstaxFacetsWidget component to display facets on your custom search page. **Facet Selection and Order** Facet lists are configured and ordered on the Site Search [Faceting Tab](https://www.searchstax.com/docs/searchstudio/faceting-tab/). **Usage** ``` ``` **Props** - 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 - itemsPerPageMobile: number; // default expanded facets for mobile - beforeFacetsRender `(facets: IFacetData[]) => IFacetData[]` — Called with the current facets array before the widget renders. Return the same or a modified array to filter, reorder, or transform facets (e.g., hide certain facets or change their order). **Main Template Desktop Override** Main wrapper template for desktop facets display. It receives following props: - facetsTemplateDataDesktop - Facets data object - isNotDeactivated - Check if facet group is active - toggleFacetGroup - Toggle facet group active state - isChecked - Check if facet value is selected - selectFacet - Handler for facet select - showMoreLessDesktop - Show more/less facets handler - facetContainers - Object of facet DOM containers - updateRefDesktop - Handler for keeping checkbox references **Main Template Mobile Override** Main wrapper template for mobile facets display. It receives following props: - facetsTemplateDataMobile - Facets data object - selectedFacetsCheckboxes - Selected facet values - isNotDeactivated - Check if facet group is active - toggleFacetGroup - Toggle facet group active state - isChecked - Check if facet value is selected - selectFacet - Handler for facet select - showMoreLessDesktop - Show more/less facets handler - facetContainers - Object of facet DOM containers - openOverlay - Handler to open mobile overlay - unselectFacet - Handler to unselect specific facet - unselectAll - Handler to unselect all facets - closeOverlay - Handler to close mobile overlay - updateRefMobile - Handler for keeping mobile checkbox references **Example** ``` ``` ### SearchFeedback Widget ### The SearchStax Site Search solution provides a search feedback widget to support your Vue search pages. The SearchstaxSearchFeedbackWidget displays search feedback and stats. **Usage** ``` ``` **Main Template Override** Main template for the search feedback message. It receives following props: - searchFeedbackData - Feedback data object - onOriginalQueryClick - Handler for clicking on original query suggestion **Example** ``` ``` ### RelatedSearches widget ### The SearchStax Site Search solution offers a Vue widget for displaying related searches. The SearchstaxRelatedSearchesWidget for Vue component displays related searches. **Usage** ``` ``` **Props** - relatedSearchesURL: API URL for fetching related searches - relatedSearchesAPIKey?: API key for related searches API **Main Template Override** Main template for related searches. It receives following props: - relatedData - Related searches data object - executeSearch - Handler to run new search from related term **Example** ``` ``` ### ExternalPromotions widget ### The SearchStax Site Search solution offers a Vue external-promotions widget for your custom search page. The SearchstaxExternalPromotionsWidget component displays external promotions fetched from the API. **Usage** ``` ``` **Main Template Override** Main template for external promotions. It receives following props: - externalPromotionsData – External promotions data object - trackClick – Handler for tracking link clicks **Example** ``` ``` ### Sorting Widget ### The SearchStax Site Search solution offers a Vue sorting widget for your custom search page. The SearchstaxSortingWidget component displays sorting options for search results. **Usage** ``` ``` **Main Template Override** Main template for sorting widget. It receives following props: - sortingData – Sorting data object - orderChange – Handler for sorting change - selectedSorting – Current selected sorting **Example** ``` ``` ## Template overrides Templates use vue templating. ## STYLING scss styles can be imported from searchstudio-ux-js ``` @import './../node_modules/@searchstax-inc/searchstudio-ux-js/dist/styles/scss/mainTheme.scss'; ``` css can be taken from ``` ./../node_modules/@searchstax-inc/searchstudio-ux-js/dist/styles/mainTheme.css ```