### Implement VTEX Gallery Layout Switching Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md This example illustrates the configuration of the `gallery-layout-switcher` block, which manages user-selectable layout options. It also shows how to define individual `gallery-layout-option` blocks, linking them to specific layout names and associating them with icons and rich text for display. ```json { "gallery-layout-switcher": { "children": [ "gallery-layout-option#whole", "gallery-layout-option#two", "gallery-layout-option#many" ] }, "gallery-layout-option#whole": { "props": { "name": "whole" }, "children": [ "icon-single-grid", "rich-text#option-whole" ] }, "gallery-layout-option#two": { "props": { "name": "two" }, "children": [ "icon-inline-grid", "rich-text#option-two" ] }, "gallery-layout-option#many": { "props": { "name": "many" }, "children": [ "icon-menu", "rich-text#option-many" ] } } ``` -------------------------------- ### Configure Facet Ordering in Filter Navigator Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Example JSON configuration for the `filter-navigator.v3` block, demonstrating how to use the `facetOrdering` prop to sort facets. This example sorts the 'brand' facet by 'name' in ascending order. Note that `facetOrdering` conflicts with `enableFiltersFetchOptimization` in `vtex.store` and requires setting the latter to `false`. ```jsonc { "filter-navigator.v3": { "props": { "facetOrdering": [ { "key": "brand", "orderBy": "name", "order": "ASC" } ] } } } ``` -------------------------------- ### Structure Search Result Layout Blocks Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md This JSON configuration defines the structure of the `search-result-layout` block, including its children like `search-result-layout.desktop`, `search-result-layout.mobile`, and `search-not-found-layout`. It also shows an example of configuring `search-result-layout.desktop` with specific children and the `preventRouteChange` prop. ```json { "search-result-layout": { "blocks": [ "search-result-layout.desktop", "search-result-layout.mobile", "search-not-found-layout" ] }, "search-result-layout.desktop": { "children": [ "flex-layout.row#searchbread", "flex-layout.row#searchtitle", "flex-layout.row#result" ], "props": { "preventRouteChange": true } } } ``` -------------------------------- ### Search Result Component `context` and `querySchema` Props Reference Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Detailed API documentation for the `context` and `querySchema` props of the `/vtex-apps/search-result` component, including type, description, and default values for each configurable property. Also includes important notes regarding pagination and cache behavior. ```APIDOC context and querySchema Props: queryField (string) Description: Mandatory. Query string of the search URL that defines the results that should be fetched in the custom query. For example: `Blue`. This prop only works if the `mapField` prop is declared as well. Default: undefined mapField (string) Description: Mandatory. Search URL's `map` parameter to define which results should be fetched in the custom query, for example `specificationFilter_100`. This prop only works if the `queryField` prop is declared as well. Default: undefined maxItemsPerPage (number) Description: Maximum number of items per search page. The maximum value of this prop is `50`. If a higher number is added, the query will fail. Default: 10 orderByField (enum) Description: Determines which order products must follow when displayed. The possible values are named after the sorting type: `OrderByReleaseDateDESC`, `OrderByBestDiscountDESC`, `OrderByPriceDESC`, `OrderByPriceASC`, `OrderByNameASC`, `OrderByNameDESC`, or `OrderByTopSaleDESC`. `ASC` and `DESC` stand for ascending order and descending order, respectively, based on the position of each value's corresponding code in the [ASCII table](http://www.asciitable.com/). The last option (`OrderByTopSaleDESC`) considers the number of sold units of the product in the past 90 days, taking into account only ecommerce orders (no physical stores orders) from `order-placed` events (e.g. without checking if the payment was approved). If the store has an app, it is possible to consider the events from the app as long as they are implemented on the store's side, they aren't implemented by default. In case the shopper has an ad-blocking extension or a browser restriction that disables sending events, their navigation will not be counted. If not set to any of the mentioned values, the fallback behavior is sorting by [relevance settings](https://help.vtex.com/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/1qlObWIib6KqgrfX1FCOXS). Default: "" hideUnavailableItems (boolean) Description: Determines whether the search result should hide unavailable items (`true`) or not (`false`). This prop only hides items that are unavailable according to indexed information, without taking into account `simulationBehavior`. Default: false facetsBehavior (string) Description: Defines the filters' behavior. When set to `Dynamic`, it restricts the results according to the filters that the user has already selected. If set to `Static`, all filters will continue to be displayed to the user, even if there are no results. Default: Static skusFilter (enum) Description: Refines the SKUs returned for each product in the query. The fewer returned SKUs, the more performant your shelf query will be. Available value options: `FIRST_AVAILABLE` (returns only the first available SKU), `ALL_AVAILABLE` (returns all available SKUs), and `ALL` (returns all product's SKUs). Default: ALL_AVAILABLE simulationBehavior (enum) Description: Defines whether the search data will be up-to-date (`default`) or fetched using the Cache (`skip`). You should only use the last option if you prefer faster queries than the most up-to-date prices or inventory. Default: default installmentCriteria (enum) Description: Defines which price should be displayed when different installments are available. Possible values are: `MAX_WITHOUT_INTEREST` (displays the maximum installment option with no interest attached to it) or `MAX_WITH_INTEREST` (displays the maximum installment option whether it has interest attached to it or not). Default: "MAX_WITHOUT_INTEREST" excludedPaymentSystems (string) Description: List of payment systems that should not be considered when displaying the installment options to users. This prop configuration only works if the `installmentCriteria` prop was also declared. In case it was not, all available payment systems will be displayed regardless. Default: undefined includedPaymentSystems (string) Description: List of payment systems that should be considered when displaying the installment options to users. This prop configuration only works if the `installmentCriteria` prop was also declared. In case it was not, all available payment systems will be displayed regardless. Default: undefined Notes: - Pagination does not display results after page 50. You can configure it to display more products per page using the prop `maxItemsPerPage` by increasing the quantity of products on each page. - When the `simulationBehavior` prop is set as `skip`, it defines that the search data should only be fetched using the store's cache. This may impact the content displayed on store pages since the cache storage changes according to user interaction in each page. ``` -------------------------------- ### Configure VTEX Gallery Block Layouts Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md This JSON snippet demonstrates how to define multiple display layouts for a `gallery` block. Each layout specifies a name, a component to render items, and the number of items per row, supporting different configurations for desktop and mobile. ```json { "gallery": { "props": { "layouts": [ { "name": "whole", "component": "OneOrTwoLineSummary", "itemsPerRow": 1 }, { "name": "two", "component": "OneOrTwoLineSummary", "itemsPerRow": 2 }, { "name": "many", "component": "ManyByLineSummary", "itemsPerRow": { "desktop": 5, "mobile": 1 } } ], "OneOrTwoLineSummary": "product-summary.shelf", "ManyByLineSummary": "product-summary.shelf" } } } ``` -------------------------------- ### API Reference: `search-products-progress-bar` Block Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Documentation for the `search-products-progress-bar` block, which shows a progress bar for search results. This block does not require any specific properties. ```APIDOC search-products-progress-bar: Block Description: Shows a progress bar of search results. This block does not need any prop when declared. Props: None ``` -------------------------------- ### API Reference: `order-by` Block Predefined Sorting Options Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Lists the predefined sorting options available for the `order-by` block, along with their corresponding API values. ```APIDOC Sorting Options for order-by block: Relevance: "" Top Sales Descending: "OrderByTopSaleDESC" Release Date Descending: "OrderByReleaseDateDESC" Best Discount Descending: "OrderByBestDiscountDESC" Price Descending: "OrderByPriceDESC" Price Ascending: "OrderByPriceASC" Name Ascending: "OrderByNameASC" Name Descending: "OrderByNameDESC" Collection: "OrderByCollection" ``` -------------------------------- ### Configuring Search Result Layout with Context Props Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Shows how to configure the `search-result-layout` block on a search page by passing context-specific properties like `skusFilter` and `simulationBehavior` directly within the `store.search` block's props. ```json { "store.search": { "blocks": [ "search-result-layout" ], "props": { "context": { "skusFilter": "FIRST_AVAILABLE", "simulationBehavior": "default" } } } } ``` -------------------------------- ### Gallery Layout Switcher Component Props Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Defines the configurable properties for the `gallery-layout-switcher` component, controlling how search results are displayed and arranged. These props allow customization of layout, custom product summary rendering, and initial SKU selection. ```APIDOC gallery-layout-switcher Props: layouts: object - List of layouts used to arrange and display the items on the search results page. If no value is provided, the `gallery` block must receive a `product-summary-shelf` block instead as a child. Check the layouts object section for props of this block. (Default: undefined) [component_value]: block - Defines which blocks should be rendered per layout. The prop name is not `undefined`, you must include the value passed on the `component` prop. This prop's value must match the block name of your choosing to be rendered in that specific layout. (Default: undefined) customSummaryInterval: number - Defines the item interval at which the Gallery should render a custom `product-summary` block. For example, declaring `5` would render a custom block at every four items rendered. It is important to know that this prop doesn't support `layouts` yet. (Default: undefined) CustomSummary: block - Defines a block to be rendered according to the interval defined by the `customSummaryInterval` prop. (Default: undefined) preferredSKU: PreferredSKUEnum - Controls which SKU will be initially selected in the product summary. (Default: "FIRST_AVAILABLE") ``` -------------------------------- ### VTEX IO Search Result Blocks Reference Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Detailed documentation for the blocks available in the `vtex-apps/search-result` application, including their purpose, mandatory status, and usage context for constructing search result pages. ```APIDOC search-result-layout: Description: Enables you to build the search result page using its three children blocks: `search-result-layout desktop`, `search-result-layout.mobile`, and `search-not-found-layout`. It must be used in the `store.search` template since it uses the context provided by the VTEX Search API. Mandatory: Yes search-result-layout.customQuery: Description: Used instead of `search-result-layout` in scenarios in which the search result will be declared in a template that doesn't fetch Search context, such as Home. It accepts a `querySchema` prop that executes search custom queries. It also supports three children blocks: `search-result-layout.desktop`, `search-result-layout.mobile` and `search-not-found-layout`. Mandatory: Yes search-result-layout.desktop: Description: Builds the search result page structure for desktop mode. Mandatory: Yes search-result-layout.mobile: Description: Builds the search result page structure for mobile mode. If the `search-result-layout.mobile` is not provided, the `search-result-layout.desktop` will be used instead. Mandatory: No search-layout-switcher: Description: Enables mobile users to switch between the available layout modes. Mandatory: No search-not-found-layout: Description: Builds the whole search result page structure for scenarios in which no result was fetched. It is rendered whenever users search for a term that doesn't return a product. Mandatory: No gallery: Description: Displays the gallery with all the products found in the search. Mandatory: Yes gallery-layout-switcher: Description: Logical block that allows users to switch between the available `gallery`'s layouts. To know how to build your search results with multiple layouts, access the documentation. Mandatory: No gallery-layout-option: Description: Defines how each layout option should be rendered for users. To know how to build your search results with multiple layouts, access the documentation. Mandatory: No not-found: Description: Contains a text and a description for the page that was not found in the search. It must be declared as a child of `search-not-found-layout`. Mandatory: No search-content: Description: Decides, behind the scenes, which block will be displayed: either the `gallery` block (if products are found) or the `not-found` block (if the selected filters lead to an empty search results page). This means that both `gallery` and `not-found` must be declared as `search-content` children. Mandatory: Yes store.not-found#search: Description: When configured, it displays a `404` error message whenever the server cannot return what the browser request was or when it is configured not to handle that request. Mandatory: No search-products-count-per-page: Description: Displays the total number of products being displayed on the search results page. Mandatory: No search-products-progress-bar: Description: Displays a progress bar of products being displayed on the search results page. Mandatory: No order-by.v2: Description: Allows users to choose the product ordination on the search results page. Mandatory: No filter-navigator.v3: Description: Allows users to apply different filters to the search. On mobile, renders a button that, when clicked on, displays all available filters in a sidebar. Mandatory: No total-products.v2: Description: Displays the total amount of products found for that search. Mandatory: No search-title.v2: Description: Displays a title for the search that was done. Mandatory: No search-fetch-more: Description: Displays the **Show More** button. This button is not rendered when the user is on the last page. Mandatory: No ``` -------------------------------- ### APIDOC: VTEX gallery-layout-option Block Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md API documentation for the `gallery-layout-option` block, which defines the rendering of each layout choice within a `gallery-layout-switcher`. It requires a `name` prop matching a defined gallery layout. ```APIDOC gallery-layout-option: Description: This block defines how each layout option should be rendered for users. Props: name: Type: string Description: Mandatory. Name of the layout option. This prop's value must match the one passed to the 'name' prop of the layouts object. Default: undefined ``` -------------------------------- ### Configure Search Page Queries for Specific Contexts Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md This JSON configuration defines the `store.search` block and its variations for specific search contexts like category, brand, department, and subcategory. It sets `skusFilter` to `FIRST_AVAILABLE` and `simulationBehavior` to `default` for each context, allowing custom behaviors for different search pages. ```json { "store.search": { "blocks": [ "search-result-layout" ], "props": { "context": { "skusFilter": "FIRST_AVAILABLE", "simulationBehavior": "default" } } }, "store.search#category": { "blocks": [ "search-result-layout" ], "props": { "context": { "skusFilter": "FIRST_AVAILABLE", "simulationBehavior": "default" } } }, "store.search#brand": { "blocks": [ "search-result-layout" ], "props": { "context": { "skusFilter": "FIRST_AVAILABLE", "simulationBehavior": "default" } } }, "store.search#department": { "blocks": [ "search-result-layout" ], "props": { "context": { "skusFilter": "FIRST_AVAILABLE", "simulationBehavior": "default" } } }, "store.search#subcategory": { "blocks": [ "search-result-layout" ], "props": { "context": { "skusFilter": "FIRST_AVAILABLE", "simulationBehavior": "default" } } } } ``` -------------------------------- ### Configure Gallery Block for Search Results Display Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Defines how fetched items are displayed on the store's search results page. It can use a default product summary child or be configured with multiple layouts for flexible item arrangement. ```APIDOC gallery block: Description: Defines how fetched items should be displayed on the store's search results page. Expected Child (no props): product-summary.shelf Props: layouts: array of objects Description: Provides several layouts to the page, allowing your store to have different arrangements of items. Users can switch between layouts using the `gallery-layout-switcher` block. ``` -------------------------------- ### Layouts Object Properties Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Properties for configuring individual layout definitions within the `gallery-layout-switcher` component. Each layout requires a unique name, a component reference, and defines the number of items to display per row. ```APIDOC layouts Object Props: name: string - Mandatory. Layout name. This value must be unique i.e. not equal to other layout names declared in the `gallery` block. (Default: undefined) component: string - Mandatory. Names the `[component_value]` prop from the `gallery` block, which is responsible for declaring the block to be rendered in this layout. This prop's value can be any of your choosing as long as it is PascalCased. Caution: For this to work, the chosen value must be named after the `gallery` block's `[component_value]` prop. Do not use the `component` prop's value to directly pass the desired block name itself. (Default: undefined) itemsPerRow: number / object - Mandatory. Number of items to be displayed in each row of this layout. This prop works with responsive values, therefore it also accepts an object with different numbers for desktop, tablet or phone screen sizes. (Default: undefined) ``` -------------------------------- ### APIDOC: VTEX gallery-layout-switcher Block Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md API documentation for the `gallery-layout-switcher` block, a logical component enabling users to toggle between defined gallery layouts. It does not accept direct props but requires `gallery-layout-option` children to function correctly. ```APIDOC gallery-layout-switcher: Description: A logical block that allows users to switch between the available gallery layouts. Props: None Children: - gallery-layout-option (expected in the same order as layouts for accessibility) ``` -------------------------------- ### API Reference: `search-products-count-per-page` Block Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Documentation for the `search-products-count-per-page` block, which displays the number of products per search page. This block does not require any specific properties. ```APIDOC search-products-count-per-page: Block Description: Shows the product count per search page. This block does not need any prop when declared. Props: None ``` -------------------------------- ### API Reference: `search-fetch-more` Block Properties Source: https://github.com/vtex-apps/search-result/blob/master/docs/README.md Properties for the `search-fetch-more` block, which renders a 'Show More' button to load additional search results. This block is only rendered if there is a next page. ```APIDOC search-fetch-more: Block htmlElementForButton: enum Description: Which HTML element will be displayed for Show more button component. Possible values are: a (displays a element with href and rel attributes) or button (displays a