Створення GitHub Repo Explorer за допомогою React та Elasticsearch

Elasticsearch - одна з найпопулярніших повнотекстових пошукових систем, яка дозволяє швидко шукати величезні обсяги даних, тоді як React, мабуть, найкраща бібліотека для побудови користувальницьких інтерфейсів. Протягом останніх кількох місяців я був співавтором бібліотеки з відкритим кодом, ReactiveSearch , яка забезпечує компоненти React для Elasticsearch та спрощує процес побудови користувальницького інтерфейсу пошуку (UI).

Це додаток, який я буду будувати в цій історії:

Коротка ідея Elasticsearch

Elasticsearch - це база даних NoSQL, яка може здійснювати пошук великих обсягів даних за короткий час. Він здійснює повнотекстовий пошук даних, які зберігаються у формі документів (як об’єкти), досліджуючи всі слова в кожному документі.

Ось що сказано в документах Elasticsearch:

Elasticsearch - це високомасштабований механізм повнотекстового пошуку та аналітики з відкритим кодом. Це дозволяє зберігати, шукати та аналізувати великі обсяги даних швидко та майже в реальному часі.

Навіть якщо ви ніколи раніше не користувались Elasticsearch, ви могли б стежити за цією історією та створити власний пошук на основі Elasticsearch за допомогою React та ReactiveSearch. ?

Що таке ReactiveSearch?

ReactiveSearch - це бібліотека компонентів інтерфейсу React для Elasticsearch. Для пошуку даних у Elasticsearch вам потрібно написати запити . Потім вам потрібно буде відформатувати та відобразити дані JSON у вашому інтерфейсі. ReactiveSearch спрощує весь процес, оскільки вам не потрібно турбуватися про написання цих запитів. Це полегшує зосередження на створенні інтерфейсу користувача.

Ось приклад, який генерує інтерфейс вікна пошуку із пропозиціями, що стосуються конкретних категорій:

Це, швидше за все, зайняло б понад 100 рядків без бібліотеки та знань Elasticsearch Query DSL для побудови запиту.

У цій публікації я буду використовувати різні компоненти з бібліотеки для побудови остаточного інтерфейсу.

Вам слід спробувати останню програму, перш ніж ми глибоко пірнаємо. Ось посилання CodeSandbox для того самого.

Налаштування речей

Перш ніж розпочати побудову інтерфейсу, нам знадобиться набір даних, що містить репозиторії GitHub в Elasticsearch. ReactiveSearch працює з будь-яким індексом Elasticsearch, і ви можете легко використовувати його зі своїм власним набором даних.

Для стислості ви можете використовувати мій набір даних або клонувати його для себе, перейшовши за цим посиланням і натиснувши кнопку Клонувати цей додаток . Це дозволить вам зробити копію набору даних як власну програму.

Після введення назви програми процес клонування повинен почати імпортувати репозиторії 26K + у ваш обліковий запис.

Усі репозиторії структуровані у наступному форматі:

{ "name": "freeCodeCamp", "owner": "freeCodeCamp", "fullname": "freeCodeCamp~freeCodeCamp", "description": "The //freeCodeCamp.org open source codebase and curriculum. Learn to code and help nonprofits.", "avatar": "//avatars0.githubusercontent.com/u/9892522?v=4", "url": "//github.com/freeCodeCamp/freeCodeCamp", "pushed": "2017-12-24T05:44:03Z", "created": "2014-12-24T17:49:19Z", "size": 31474, "stars": 291526, "forks": 13211, "topics": [ "careers", "certification", "community", "curriculum", "d3", "education", "javascript", "learn-to-code", "math", "nodejs", "nonprofits", "programming", "react", "teachers" ], "language": "JavaScript", "watchers": 8462 }
  • Для налаштування проекту ми використаємо додаток create-response-app. Ви можете встановити додаток create-response-, виконавши в своєму терміналі таку команду:
npm install -g create-react-app
  • Після встановлення ви можете створити новий проект, запустивши:
create-react-app gitxplore
  • Після налаштування проекту ви можете перейти в каталог проекту та встановити залежність ReactiveSearch:
cd gitxplore npm install @appbaseio/reactivesearch
  • Ви також можете додати фантастичний CDN, який ми будемо використовувати для деяких піктограм, вставивши наступні рядки /public/index.htmlдо закінчення тегу:

Занурення в код

Я буду слідувати простій структурі каталогів для програми. Ось важливі файли:

src ├── App.css // App styles ├── App.js // App container ├── components │ ├── Header.js // Header component │ ├── Results.js // Results component │ ├── SearchFilters.js // Filters component │ └── Topic.js // rendered by Results ├── index.css // styles ├── index.js // ReactDOM render └── theme.js // colors and fonts public └── index.html

Ось посилання на остаточне репо, якщо ви хочете посилатися на що-небудь у будь-який момент.

1. Додавання стилів

Я написав адаптивні стилі для програми, які ви можете скопіювати у свою програму. Просто запустіть свій улюблений текстовий редактор і скопіюйте стилі як /src/index.cssзвідси, так і /src/App.cssзвідси відповідно.

Тепер створіть файл, /src/theme.jsкуди ми додамо кольори та шрифти для нашого додатка:

const theme = { typography: { fontFamily: 'Raleway, Helvetica, sans-serif', }, colors: { primaryColor: '#008000', titleColor: 'white' }, secondaryColor: 'mediumseagreen', }; export default theme;

2. Додавання першого компонента ReactiveSearch

Всі компоненти ReactiveSearch обгорнуті навколо контейнерного компонента ReactiveBase, який надає дані з Elasticsearch дочірнім компонентам ReactiveSearch.

Ми використаємо це в /src/App.js:

import React, { Component } from 'react'; import { ReactiveBase } from '@appbaseio/reactivesearch'; import theme from './theme'; import './App.css'; class App extends Component { render() { return ( GitXplore ); } } export default App;

Для appand credentialsprop ви можете використовувати ті, які я тут надав. Якщо ви клонували набір даних у власному додатку раніше, ви можете отримати їх на сторінці облікових даних програми. Якщо ви вже знайомі з Elasticsearch, ви можете замість цього передати urlпідказку з посиланням на вашу власну URL-адресу кластера Elasticsearch.

Крім того, ви можете скопіювати свої програми credentialsз інформаційної панелі програм. Наведіть курсор на картку вашого додатка та натисніть Копіювати дані для читання .

Після додавання цього ви побачите такий базовий макет:

3. Додавання DataSearch

Далі я додаю компонент DataSearch для пошуку по сховищах. Він створює компонент інтерфейсу пошуку та дозволяє нам легко шукати в одному або декількох полях. Оновлена renderфункція в /src/App.jsбуде виглядати так:

// importing DataSearch here import { ReactiveBase, DataSearch } from '@appbaseio/reactivesearch'; ...  // Adding the DataSearch here ...

DataSearchКомпонент проходить всередині ReactiveBaseкомпонента і отримує всі необхідні дані з нього , тому ми не повинні писати Elasticsearch опитує себе. Навколишні divs додають деякі classNameвластивості стилю. Вони просто додають макет до програми. Ви можете пройти всі стилі, в /src/App.cssяких ми створили раніше. Ви могли помітити, що ми передали деякий реквізит DataSearchкомпоненту.

Ось як вони працюють:

  • componentId: унікальний ідентифікатор рядка, який ми використаємо пізніше для підключення двох різних компонентів ReactiveSearch.
  • filterLabel: значення рядка, яке з'явиться в меню фільтрів пізніше.
  • dataField: an array of strings containing Elasticsearch fields on which search has to performed on. You can check the dataset and see that these fields also matches the column name. All fields specified here matches the structure of data, for example name refers to the name of repo, description refers to its description, but there is a field with a .raw added here, name.raw which is a multi-field of the name field. Elasticsearch can index the same data in different ways for different purposes, which we can use to get better search results.
  • placeholder: sets the placeholder value in the input box.
  • autosuggest: setting a false value for the prop causes the results to update immediately in the results.
  • iconPosition: sets the position of the ? icon.
  • URLParams: is a boolean which tells the component to save the search term in the browser’s URL so we can share a URL to a specific search query. For example, check this link to see all results related to “react”.
  • className: adds a class for styling using CSS.
  • innerClass: adds a class to different sections of a component for styling using CSS. Here, I’ve added a class to the input box for styling. A detailed description can be found in the docs.

With this, our app should get a working search bar:

4. Adding the Results view

Next, we’ll be adding the Results component at /src/components/Results.js and importing it in /src/App.js.

Here’s how you can write the Results component:

import React from 'react'; import { SelectedFilters, ReactiveList } from '@appbaseio/reactivesearch'; const onResultStats = (results, time) => ( {results} results found in {time}ms ); const onData = (data) => ( {data.owner}/{data.name} ); const Results = () => ( ); export default Results;

I’ve imported two new components from ReactiveSearch, SelectedFilters and ReactiveList. SelectedFilters will render the filters for our ReactiveSearch components at one place:

ReactiveList renders the search results. Here’s how its props work:

  • dataField: orders the results using name field here.
  • onData: accepts a function which returns a JSX. The function is passed each result individually. Here we’re generating a basic UI which we’ll modify later.
  • onResultStats: similar to onData but for the result stats. The function is passed the number of results found and time taken.
  • react: the react prop tells the ReactiveList to listen to changes made byCategorySearch component, we’ve provided the componentId of the CategorySearch component here called repo. Later we’ll add more components here.
  • pagination: a boolean which tells the ReactiveList to split the results into pages, each page containing the number of results specified in the size prop.

Now we can import and use the Results component in /src/App.js. Just add it inside the div with results-container class.

... import Results from './components/Results'; ... render() { return( ... ... ) }

With this component, a basic version of our search UI should start coming together:

5. Adding a Header component

Lets create a Header component at /src/components/Header.js which we’ll use to render more search filters.

Here’s how to create a simple Header component:

import React, { Component } from 'react'; import SearchFilters from './SearchFilters'; class Header extends Component { constructor(props) { super(props); this.state = { visible: false, }; } toggleVisibility = () => { const visible = !this.state.visible; this.setState({ visible, }); } render() { return ( GitXplore Toggle Filters ); } } export default Header; 

I’ve moved the navigation code in .. from /src/App.js here. The Header component has a method which toggles visible in the state. We’re using this to add a class which would make it take up the entire screen size on mobile layout. I’ve also added a toggle button which calls the toggleVisibility method.

It also renders another component called SearchFilters and passes all the props from the parent App component. Let’s create this component to see things in action.

Create a new file /src/components/SearchFilters.js:

import React from 'react'; const SearchFilters = () => ( Search filters go here! ); export default SearchFilters;

Next, I’ll update the App component to use the Header component that we created just now.

6. Updating App component and handling topics in state

We’ll add a state variable in App component called currentTopics which would be an array of currently selected topics in the app.

We’ll then use the currentTopics and pass them to the Header and Results components:

import React, { Component } from 'react'; import { ReactiveBase, DataSearch } from '@appbaseio/reactivesearch'; import Header from './components/Header'; import Results from './components/Results'; import theme from './theme'; import './App.css'; class App extends Component { constructor(props) { super(props); this.state = { currentTopics: [], }; } setTopics = (currentTopics) => { this.setState( currentTopics: currentTopics ); } toggleTopic = (topic) => { const { currentTopics } = this.state; const nextState = currentTopics.includes(topic) ? currentTopics.filter(item => item !== topic) : currentTopics.concat(topic); this.setState({ currentTopics: nextState, }); } render() { return ( ); } } export default App;

The setTopics method will set whichever topics are passed to it, which we’ll pass to the Header component. The toggleTopic method will remove a topic from the state in currentTopics if it’s already present and add the topic if it is not present.

We’ll pass the toggleTopic method to the Results component:

7. Adding more filters

Lets add more filters to the UI in /src/components/SearchFilters.js. I’ll be using three new components from ReactiveSearch here, MultiDropdownList, SingleDropdownRange and RangeSlider. The components are used in a similar fashion as we used the DataSearch component earlier.

Here’s the code:

import React from 'react'; import PropTypes from 'prop-types'; import { MultiDropdownList, SingleDropdownRange, RangeSlider, } from '@appbaseio/reactivesearch'; const SearchFilters = ({ currentTopics, setTopics, visible }) => ( ); SearchFilters.propTypes = { currentTopics: PropTypes.arrayOf(PropTypes.string), setTopics: PropTypes.func, visible: PropTypes.bool, }; export default SearchFilters; 

The SearchFilters component we’ve created above takes in three props from the Header component, currentTopics, setTopics and visible. The visible prop is just used to add a className for styling.

The first component we’ve used here is a MultiDropdownList which renders a dropdown component to select multiple options. The first MultiDropdownList has a dataField of language.raw. It’ll populate itself with all the languages available in the repositories dataset.

We’ve used another MultiDropdownList to render a list of topics:

Here’s how the props work here:

  • componentId: similar to the previous ReactiveSearch components, this is a unique identifier which we’ll later associate in the Results component that we created to get search results.
  • dataField: maps the component to the topics.raw field in Elasticsearch.
  • placeholder: sets the placeholder value when nothing is selected.
  • title: adds a title for the component in the UI.
  • filterLabel: sets the label of the components in the removable filters (the SelectedFilters which we used in the Results component).
  • size: tells the component to render a maximum of 1000 items in the list.
  • queryFormat: when set to 'and' as we’ve used here, it gives results which matches all the selected tags (exactly like intersection).
  • defaultSelected: sets the selected items in the component. Here we’re passing currentTopics which we’ve stored in the state at /src/App.js.
  • onValueChange: is a function that will be called by the component when we make a change in its value. Here we call the setTopics function which we received in the props. Therefore, whenever we select or deselect a value in the component it would update the currentTopics in the state of main App component.

The next ReactiveSearch component we’ve used here is a SingleDropdownRange. It uses a new prop called data.

Here’s how it works:

The data prop accepts an array of objects with start and end values and shows the specified label in the dropdown. It’s mapped to the pushed field in the dataset which is a date type in Elasticsearch. One cool way to specify date range in Elasticsearch is using the now keyword. now refers to the current time, now-1M refers to one month before, now-6M to six month before and now-1y to a year before now.

I’ve used another SingleDropdownRange component for the created field in the dataset.

Here I’ve specified year ranges in datetime for different years:

The third component I’ve used is a RangeSlider which renders a slider UI. I’ve used to RangeSlider components, one for the stars field and the other for forks.

Two main props that this component introduces are range and rangeLabels:

  • range: prop specifies a range for the data with a start and end value.
  • rangeLabels: prop takes the labels to show below the slider.
  • showHistogram: is a boolean prop which shows a histogram with the distribution of data. Here I’ve set it to false since it’s not needed.

Now we just need to connect these filters to the Results component. We just have to update one line in the ReactiveList rendered by the Results component to include the componentIds of these components.

Update the react prop in the ReactiveList that we rendered in the Results component:

const Results = () => ( );

That should make your results update for all the filters ?

8. Updating the results view

Up until now, we’ve been seeing only a basic version of the results. As the final piece of this app, lets add some flair to the results ✌️

We’ll be using another component inside our Results components to render different topics.

Here’s how you can create your own at /src/components/Topic. Feel free to add your own taste ?

 import React, { Component } from 'react'; import PropTypes from 'prop-types'; class Topic extends Component { handleClick = () => { this.props.toggleTopic(this.props.children); } render() { return ( #{this.props.children} ); } } Topic.propTypes = { children: PropTypes.string, active: PropTypes.bool, toggleTopic: PropTypes.func, }; export default Topic;

This component renders its children and adds a click handler to toggle the topics which updates the currentTopics inside the main App component’s state.

Next, we just need to update our Results component at /src/components/Results.js:

import React from 'react'; import { SelectedFilters, ReactiveList } from '@appbaseio/reactivesearch'; import PropTypes from 'prop-types'; import Topic from './Topic'; const onResultStats = (results, time) => ( {results} results found in {time}ms ); const onData = (data, currentTopics, toggleTopic) => (  {data.owner}/ {data.name} {data.description} { data.topics.slice(0, 7) .map(item => (  {item}  )) } {data.stars} {data.forks} {data.watchers} ); const Results = ({ toggleTopic, currentTopics }) => ( onData(data, currentTopics, toggleTopic)} onResultStats={onResultStats} react={{ and: ['language', 'topics', 'pushed', 'created', 'stars', 'forks', 'repo'], }} pagination innerClass={{ list: 'result-list-container', pagination: 'result-list-pagination', resultsInfo: 'result-list-info', poweredBy: 'powered-by', }} size={6} sortOptions={[ { label: 'Best Match', dataField: '_score', sortBy: 'desc', }, { label: 'Most Stars', dataField: 'stars', sortBy: 'desc', }, { label: 'Fewest Stars', dataField: 'stars', sortBy: 'asc', }, { label: 'Most Forks', dataField: 'forks', sortBy: 'desc', }, { label: 'Fewest Forks', dataField: 'forks', sortBy: 'asc', }, { label: 'A to Z', dataField: 'owner.raw', sortBy: 'asc', }, { label: 'Z to A', dataField: 'owner.raw', sortBy: 'desc', }, { label: 'Recently Updated', dataField: 'pushed', sortBy: 'desc', }, { label: 'Least Recently Updated', dataField: 'pushed', sortBy: 'asc', }, ]} /> ); Results.propTypes = { toggleTopic: PropTypes.func, currentTopics: PropTypes.arrayOf(PropTypes.string), }; export default Results;

I’ve updated the onData function to render more detailed results. You’ll also notice a new sortOptions prop in the ReactiveList. This prop accepts an array of objects which renders a dropdown menu to select how you wish to sort the results. Each object contains a label to display as the list item, a dataField to sort the results on and a sortBy key which can either be asc (ascending) or desc (descending).

That’s it, your very own GitHub repository explorer should be live!

Original text


Useful links

  1. GitXplore app demo, CodeSandbox and source code
  2. ReactiveSearch GitHub repo
  3. ReactiveSearch docs

Hope you enjoyed this story. If you have any thoughts or suggestions, please let me know and do share your version of the app in comments!

You may follow me on twitter for latest updates. I've also started posting more recent posts on my personal blog.