Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Sitecore/Sitecore-Search-TS-SDK-Starter-Kit
Sitecore Search JS SDK Starter Kit
https://github.com/Sitecore/Sitecore-Search-TS-SDK-Starter-Kit
Last synced: 3 months ago
JSON representation
Sitecore Search JS SDK Starter Kit
- Host: GitHub
- URL: https://github.com/Sitecore/Sitecore-Search-TS-SDK-Starter-Kit
- Owner: Sitecore
- License: apache-2.0
- Created: 2023-06-06T14:43:33.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-10T10:07:04.000Z (6 months ago)
- Last Synced: 2024-05-16T13:24:01.105Z (6 months ago)
- Language: TypeScript
- Size: 4.74 MB
- Stars: 6
- Watchers: 3
- Forks: 16
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- Awesome-Sitecore - Sitecore Search Starter Kit - A website example This repository has an example implementation of a content website using the Sitecore Search JS SDK integrating with Sitecore Search services with the supports of event tracking. (Sitecore Search)
README
Sitecore Search Starter Kit
A website built using React + Sitecore Search SDK for React
Demo »
# Sitecore Search Starter Kit
This repository has an example implementation of a content website using the `Sitecore Search JS SDK` which
integrates with Sitecore Search services and supports event tracking.
## Table of contents
- [Prerequisites](#prerequisites)
- [Quick start](#quick-start)
- [Pages](#Pages)
- [Home](#Home)
- [Search](#Search)
- [Content detail page](#Content-detail-page)
- [Events](#Events)
- [Monitoring example](#Monitoring-example)
- [Documentation](#learn-more)
## Prerequisites
### Node.js
The Search Starter Kit needs to have Node.js installed to build the project. We recommend using the LTS version of Node.js. You can find the latest version of Node.js [here](https://nodejs.org/en/).
### Environment variables
The Sitecore Search Starter Kit needs some environment variables to work. You can get the values for them in the [Developers resources section](https://doc.sitecore.com/discover/en/developers/discover-developer-guide/index_en.html?contextId=apiaccess) of Customer Engagement Console (CEC). For full functionality, create a **.env** file in the root of the project and add the following environment variables.
The following variables should exist within the **.env** file:
```
VITE_SEARCH_ENV=
VITE_SEARCH_CUSTOMER_KEY=
VITE_SEARCH_API_KEY=
VITE_SEARCH_PATH=. This variable is optional, use it only if the site domain also includes an extra path.
```
### CEC configuration
The account that will be used must have an initial configuration that needs to be made on CEC:
#### Sources
Information sources must be entered and processed in CEC, to populate the content catalog.
#### Suggestion Blocks
Suggestions blocks must have a field named `title_context_aware` (this needs to be configured for the `preview search widget`).
The following picture shows a sample configuration:
#### Sorting options
Sorting options must include `featured_desc` and `feature_asc` criteria pre-configured. The picture shows how it should look on CEC:
#### Pre configured widgets
The account must have the following widgets created before:
| Name | ID | Type | Description | Used in |
|--------------------------------------|---------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
| [Search Results Page] Search Results | `rfkid_7` | `Search Results` | Search results widget. Will include a grid with the results together with the avility to filter results by different facets. | `/search`, `/detail/*` |
| Preview Search | `rfkid_6` | `Preview Search` | It is an input that does a quick search over the content. It is included on the page header. | Every page |
| SEO | `search_seo` | `SEO` | A SEO widget. | Every page |
| Home Hero | `home_hero` | `HTML Block` | An html block that appears at the home hero. It has rules to show content dependending on the language selected. | `/` |
| FAQs Title | `faqs_title` | `HTML Block` | An html block with the title of the "Frequently asked questions" section. | `/` |
| Highlight Title | `highlight_title` | `HTML Block` | An html block with the title of the "Highlighted Articles" section. | `/` |
| Search Home Highlights Articles | `search_home_highlights_articles` | `Search Results` | Search Results widget used on the "Highlighted Articles section". | `/` |
| N/A | `rfkid_qa` | `Questions` | This widget appears on the home page, used on the "Frequently Asked Questions" or in the search page. Please ask for support if this does not appears as it is still an experimental feature (This type of widget can't be created on CEC as well). | `/` , `/search` |
Please, check our [demo website](https://developers.sitecorecloud.io/search-sdk/react/website) to check and visualize the different widgets.
## Quick start
To start using `Sitecore Search Starter Kit`:
1. Install [Node.js](htts://nodejs.org/en/). We recommend the LTS version.
2. Clone the repository: `git clone [email protected]:Sitecore/Sitecore-Search-JS-SDK-Starter-Kit.git`.
3. In the repository, to install all dependencies, run `npm install`.
4. In the root of the project, create a `.env` file then add the following environment variables to it:
```
VITE_SEARCH_ENV=
VITE_SEARCH_CUSTOMER_KEY=
VITE_SEARCH_API_KEY=
VITE_SEARCH_PATH= (optional)
```
5. To start the development server, run `npm run dev`.
6. To view the site, open your browser to **http://localhost:5174**
7. To build the app for production, run: `npm run build`
## Pages
The JS SDK uses React Router to perform page navigation. Each page is a React component with a `useEffect` hook used to register uri change.
For example, for home page we have:
```javascript
useEffect(() => {
PageController.getContext().setPageUri('/');
}.[]);
```
With this, the SDK can change browser context and customize tracking/service response.
### Home
Route: `/` shows the main page of the site.
The home page has the following configuration:
- 1st section: it is a content block with a locale rule to change the content if you switch the language.
- 2nd section: a content block with the title (Frequently asked questions) with the same rule than 1st section. It also has a `questions` widget below that only shows some questions based on a specific keyphrase.
- 3rd section: a content block with the title (same mechanism than 2nd section) and a `search` widget with a filter applied (type = blogs).
Events tracked are:
- A `widget appear` event per widget that appears on the page.
### Search
Route: `/search` shows the results returned after submitting the form in the header.
It contains:
- a `questions` widget in case that the application recognizes that the filtering term is a question (e.g.: `What is XM Cloud` ).
Otherwise, if it is not recognizing the search term as a question won't show anything
- A `search results` widget that will show on any case.
Events tracked are:
- A `widget appear` event for the questions and answer widget if it is present.
- A `widget appear` event for the search result widget present on the page.
### Content detail page
Route: `/detail/`. E.g.: `/detail/content-121212` shows the details of a specific content.
__Note:__
*In this example, the content information has been filtered from the `SearchResults` widget data for demonstration purposes. We do not recommend this approach in production. Restrict Search services to search and recommendations and create separate services for other data.*
Events tracked are:
- A `widget appear` event for the search result.
## Events
Events are an important part of the Search platform. The JS SDK automatically fires events it can infer when they happen. To register other events, you have to verbosely dispatch them.
Refer to the [JS SDK documentation](https://doc.sitecore.com/discover/en/developers/discover-js-sdk-for-react/index_en.html?contextId=events) for more about dispatching events.
### Monitoring example
An example of monitoring could be debug event tracking in the CEC. The following video shows how you can verify the events that the SDK trigger:
### Adding a new widget
The starter kit comes with the `@sitecore-search/cli` as a dev dependency. We also added a `package.json` script as a short cut to create
a widget based on the [templates available](https://developers.sitecorecloud.io/search-sdk/react/latest/storybook/index.html?path=/docs/widget-templates-introduction--page).
For widget creation, open a terminal in the root of the project and execute the following command:
`npm run create-widget`
Then follow the instructions from the wizard.
More documentation for the cli can be found [here](https://www.npmjs.com/package/@sitecore-search/cli).
## Documentation
Sitecore Search SDK documentation is written for both developers and [business users](https://developers.sitecorecloud.io/search-sdk/react/1.x/storybook/index.html?path=/story/introduction-introduction--page).
JS SDK for React documentation includes:
* [Components, functions, and query hooks](https://developers.sitecorecloud.io/search-sdk/react/1.x/storybook/index.html?path=/story/sdk-hooks-introduction--page).
* [Templates and ui primitives](https://developers.sitecorecloud.io/search-sdk/react/1.x/storybook/index.html).
For data feeds and URL configuration, refer to the [Search developer guide](https://developers.sitecorecloud.io/search-sdk/react/1.x/storybook/index.html?path=/story/introduction-introduction--page).
## Contributions
We are very grateful to the community for contributing bug fixes and improvements. We welcome all efforts to evolve and improve the Search Starter Kit. The following sections explain how you can participate in these efforts.
### Bug reports
You can use GitHub to submit [bug reports](https://github.com/Sitecore/Sitecore-Search-TS-SDK-Starter-kit/issues/new?template=bug_report.md) for Search Starter Kit.
### Feature requests
You can use GitHub to submit [feature requests](https://github.com/Sitecore/Sitecore-Search-TS-SDK-Starter-kit/issues/new?template=feature_request.md) for Search Starter Kit.
### Code of Conduct
Sitecore has adopted a [Code of Conduct](CODE_OF_CONDUCT.md) that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
### Contributing Guide
If you want to make changes to the code, follow these steps:
1. Fork the Sitecore Search Starter Kit Repo GitHub repo.
2. Clone the forked repo to your local machine.
3. Create a feature branch from `main` for your changes. e.g. `git checkout -b my-feature-branch`
4. Run `npm install`
5. Run `npm run dev` (to preview your changes locally)
6. Commit, push to your remote fork of the Search Starter Kit repo, then open a pull request (PR) to the `main` branch of the Developer Portal repo.
Your changes will be reviewed and merged if appropriate.