Как создать панель для SaaS с React, Google Sheets и FusionCharts

Sponsored Content

This sponsored post features a product relevant to our readers while meeting our editorial guidelines for being objective and educational.

Russian (Pусский) translation by Marat Amerov (you can also view the original English article)

В этом уроке я объясню процесс создания панели инструментов SaaS путем извлечения данных из Google Sheets с использованием API Google Sheets. Для создания этой панели мы будем использовать React, библиотеку JavaScript для создания пользовательских интерфейсов; FusionCharts, библиотека диаграмм на основе JavaScript; и Bulma, CSS-фреймворк, основанный на Flexbox.

Для начала

Вот что мы охватим:

Установка

React
Компоненты FusionCharts и FusionCharts React
CSS-фреймворк Bulma
Настройка API Google Sheets

Подключение API Google Sheets и выборка данных

Создание макета панели SaaS

Создание KPI

Создание диаграмм

Заключение

Прежде чем мы начнем настройку, я хочу показать вам предварительную версию панели SaaS, которую вы сможете создать, пройдя этот урок. Вот ссылка того, что мы будем разрабатывать.

1. Настройка

Вам нужно настроить свой проект со следующими зависимостями:

React
Базовый пакет FusionCharts и его компонент для React
Bulma

Включение React

Шаблон React от Facebook поможет нам быстро начать работу. Он настроит React вместе со всеми утилитами, которые нам понадобятся для нашего приложения панели. Итак, в выбранном вами терминале (iTerm с Zsh у меня) вы можете пойти дальше и ввести:

$ npx create-react-app saas-dashboard

Вы можете узнать больше о шаблоне create-react-app, который мы использовали здесь.

saas-dashboard - это рабочий каталог, в который будет установлен шаблон React вместе со всеми утилитами и зависимостями, и мы добавим еще несколько, которые нам понадобятся для этого урока, как описано ниже.

Включение основного пакета FusionCharts и его компонента React

Мы будем использовать FusionCharts для визуализации диаграмм в нашем приложении для панели инструментов. Вы можете пойти дальше и узнать больше о FusionCharts на fusioncharts.com.

Есть несколько способов установить FusionCharts; для общих инструкций вы можете исследовать эту страницу документации.

Прямая загрузка FusionCharts

Вы можете напрямую загрузить файлы JavaScript с веб-сайта FusionCharts и включить их в свое приложение с помощью тега <script> в /public/index.html.

Использование NPM

В этом уроке мы будем использовать NPM. Итак, в терминале перейдите в рабочий каталог, то есть saas-dashboard и введите:

$ npm install --save fusioncharts

FusionCharts предоставляет легкий и простой в использовании компонент для React, который можно использовать для добавления диаграмм JavaScript в приложениях React без каких-либо хлопот. Мы будем использовать его в нашем приложении, поэтому давайте установим его с помощью команды ниже:

$ npm install --save react-fusioncharts

Вы можете узнать больше о компоненте FusionCharts React из репозитория FusionCharts.

Включение Bulma

Чтобы создать макет и пользовательский интерфейс для нашего приложения панели, мы будем использовать CSS-фреймворк Bulma . Итак, введите в терминале:

$ npm install --save bulma

Теперь, когда мы добавили все зависимости для нашего приложения панели, мы можем перейти к настройке API Google Sheets.

Настройка API Google Sheets

Мы создадим новый проект для нашего приложения панели из консоли API разработчика Google для использования данных из Google Sheets. Я буду назову его "gsheets-dashboard". Вы можете создать новый проект по этой ссылке.

После создания проекта вы будете перенаправлены на панель инструментов Google Developer API. Теперь, чтобы включить API Google Sheets для нашего приложения, нажмите Перейти к обзору API. После того, как вы нажмете Включить API и сервисы, вы увидите библиотеки API, поэтому продолжайте искать "API Google Sheets".

Найдя его, нажмите Включить, и после его обработки вы увидите страницу, как показано ниже:

На боковой панели, перейдите в раздел Учетные данные, нажмите кнопку Создать учетные данные и выберите Ключ API. Нажмите Ограниченный ключ и задайте для него имя (я установил "SaasDashboardAPIKey").

Сохраните сгенерированный ключ, так как он понадобится нам для извлечения данных из нашего Google Sheet позже.

В разделе Ограничения API выберите API Google Sheets и сохраните. Теперь мы готовы перейти к следующему шагу, где мы подключим API Google Sheets и получим некоторые данные.

2. Подключение API Google Sheets и выборка данных

Мы перейдем на страницу Google Sheet, которую будем использовать в нашем приложении для панели инструментов. Вот скриншот того, как это выглядит, построенный с некоторыми примерами данных, которые я собрал для вымышленного SaaS-бизнеса. Вы увидите ежемесячные данные за три года, сфокусированные на некоторых ключевых показателях эффективности (SaP) SaaS-бизнеса. К ним относятся доходы, клиенты и другие показатели роста.

Теперь нам нужно поделиться листом, чтобы каждый мог его увидеть. Для этого в меню Файл нажмите Поделиться. Затем нажмите Получить общую ссылку, и после ее обработки лист будет предоставлен для доступа "Любой, у кого есть ссылка" по умолчанию.

Поскольку мы хотим сделать лист общедоступным, перейдите к разделу "Любой, у кого есть ссылка для просмотра" и выберите опцию Дополнительно в раскрывающемся списке. Выберите "On - Public on the web" и сохраните.

Вы можете получить доступ к листу, который я буду использовать по этой ссылке.

Мы запомним идентификатор таблицы (это можно найти в URL-адресе для Google Sheets, у меня это 1QZ3vKssyG9xEG-RJklQlBezIR8WqCfML4EfO2qe5vbw).

Мы будем использовать метод batchGet для нашего приложения панели. Он возвращает один или несколько диапазонов значений из электронной таблицы. Вы можете узнать больше об этом здесь. Вооружившись ключом API и идентификатором электронной таблицы, давайте обратимся к проводнику API Google Sheets, чтобы проверить его (вы также можете использовать браузер/postman (я использовал его!), Чтобы проверить результат и получить ответ JSON, который выглядит примерно так):

Я подверг цензуре API-ключ - вы можете поставить свой собственный ключ API на его место.

Теперь давайте откроем наш рабочий каталог (для меня saas-dashboard) в редакторе кода и создадим новый файл с именем config.js. Добавим свой API-ключ и идентификатор электронной таблицы следующим образом.

export default {
    apiKey: 'YOUR_API_KEY',
    spreadsheetId: '1kVwf5oIZMPqY4Y2WRj9NzeDgy3zBBj-px-Hl41sFlT8'
}

Теперь перейдем к файлу App.js. Мы будем добавлять все непосредственно в App.js, который дал нам наш шаблон. Это не лучшая архитектура, а просто демонстрация концепций.

Следующие шаги показывают, как я подключу наше приложение для панели к API Google Sheets и получу из него данные:

1. Импортируйте файл config.js, который мы создали с помощью приведенного ниже кода, и объявите переменную с URL-адресом запроса для API Google Sheets.

import config from './config';

const url = `https://sheets.googleapis.com/v4/spreadsheets/${ config.spreadsheetId }/values:batchGet?ranges=Sheet1&majorDimension=ROWS&key=${ config.apiKey }`;

2. Теперь мы установим пустой массив в this.state, как показано в коде ниже:

constructor() {
    super();
    this.state = {
     items:[]
    };
  }

3. Извлечем JSON-данные из метода жизненного цикла React componentDidMount:

componentDidMount() {
    fetch(url).then(response => response.json()).then(data => {
      let batchRowValues = data.valueRanges[0].values;
 
      const rows = [];
      for (let i = 1; i < batchRowValues.length; i++) {
        let rowObject = {};
        for (let j = 0; j < batchRowValues[i].length; j++) {
          rowObject[batchRowValues[0][j]] = batchRowValues[i][j];
        }
        rows.push(rowObject);
      }
      
      this.setState({ items: rows });
    });
}

Потрясающие! Теперь, когда мы установили соединение с нашими Google Sheets, мы можем приступить к созданию макета для нашей панели.

Примечание: Вы можете проверить соединение, залогировав переменную items в state.

3. Построение макета SaaS Dashboard

Мы будем использовать Bulma для создания макета для нашего приложения панели. Bulma - это CSS-фреймворк, основанный на Flexbox, который предоставляет нам множество готовых и настраиваемых элементов и компонентов.

Вот как это будет выглядеть. Для получения дополнительной информации о том, что эти KPI означают для бизнеса, прочитайте Saas Metrics, которые действительно имеют значение: KPI, которые вы должны отслеживать. После того, как вы создали панель, окончательная версия будет выглядеть как на скриншоте ниже:

Вы также можете проверить работающую панель здесь.

Теперь давайте разделим макет нашей панели на три части:

Раздел навигации
Раздел KPI
Раздел Графиков

Мы также перезапишем некоторые из стилей по умолчанию, предоставленных Bulma, используя наш собственный CSS, который будет представлен в файле App.css.

Создание раздела навигации

Для создания навигации мы будем использовать компонент Navma из Bulma. Ниже приведен фрагмент HTML-кода:

<nav className="navbar has-shadow is-spaced" role="navigation" aria-label="main navigation">
        <div className="navbar-brand">
                <div className="navbar-item is-size-4 has-text-weight-semibold has-text-grey-darker">SaaS Dashboard<span className="is-size-6 has-text-grey has-text-weight-normal">by FusionCharts</span></div>
        </div>
        <div className="navbar-end" aria-label="menu" aria-expanded="false">
                <a id="btn-2018" className="navbar-item is-active has-text-link" href="#" onClick={this.updateDashboard}>2018</a>
                <a id="btn-2017" className="navbar-item" href="#" onClick={this.updateDashboard}>2017</a>
                <a id="btn-2016" className="navbar-item" herf="#" onClick={this.updateDashboard}>2016</a>
        </div>
</nav>

Теперь, когда наш раздел навигации готов, мы создадим container для размещения следующих двух разделов нашей панели. Вот фрагмент кода HTML:

<div className="container is-fullhd">
  // kpi section
  
  // charts section
</div>

Вы можете узнать больше о контейнерах здесь.

Создание раздела KPI

Чтобы создать раздел KPI, мы будем использовать HTML-тег <section> и использовать компоненты Columns и Card, предоставленные Bulma. Ниже приведен фрагмент HTML:

<section className="section is-bottom-paddingless has-paddingtop-size-1">
   <div className="columns">
      <div className="column">
         <div className="card">
            <div className="card-content">
               <div className="columns columns-kpi is-mobile is-desktop has-block-display">
                  <div className="column header is-two-thirds-desktop is-full-tablet is-two-thirds-mobile has-text-left is-bottom-paddingless">Renewed Users
                  </div>
                  <div id="renewed-users-changeper" className="column has-text-right has-text-left-tablet-only has-text-left-desktop-only is-bottom-paddingless" data-up="↑" data-down="↓">...</div>
               </div>
               <div id="renewed-users-val">...</div>
            </div>
         </div>
      </div>
   </div>
</section>

Приведенный выше фрагмент создаст одну карту KPI. Точно так же мы создадим карточки для всех четырех ключевых показателей эффективности, которые мы хотим продемонстрировать.

Создание раздела Графиков

Чтобы создать раздел диаграмм, мы снова будем использовать HTML-тег <section> с компонентами Columns и Card, предоставленными Bulma. Мы оставим пустой тег <div> с уникальным идентификатором графика.

Ниже приведен фрагмент HTML:

<section className="section is-bottom-paddingless has-paddingtop-size-1">
   <div className="columns is-multiline">
      <div className="column is-half-tablet is-one-third-desktop is-half-fullhd">
         <div className="card">
            <div className="card-content has-chart">
               <div className="columns is-marginless is-mobile is-desktop has-block-display">
                  <div className="column header is-two-thirds-desktop is-full-tablet is-two-thirds-mobile has-text-left is-bottom-paddingless">Monthly Reccuring Revenue</div>
                  <div id="mrr-changeper" className="column has-text-right has-text-left-tablet-only has-text-left-desktop-only is-bottom-paddingless" data-up="↑" data-down="↓">...</div>
               </div>
               <div id="mrr-val">...</div>
            </div>
            <div id="mrr-chart">
            </div>
         </div>
      </div>
   </div>
</section>

Мы добавим все карточки с диаграммами в компоненты одного столбца, чтобы наша панель была отзывчивой, добавив различные точки останова, предоставленные Bulma для каждого столбца. Вы можете узнать больше об этих адаптивных точках останова в документации Bulma.

Приведенный выше фрагмент создаст одну карту. Точно так же мы создадим карты для всех шести графиков, которые мы хотим продемонстрировать. Если вы уже выполнили вышеуказанные шаги, у вас должна быть такая же компоновка, как на изображении выше. Если нет, не беспокойтесь, я добавлю ссылку на Github-репозиторий для этой панели в конце урока.

4. Создание KPI для SaaS Dashboard

Теперь, когда наш макет готов, мы определим функциональность для некоторых элементов и отправим им данные из Google Sheets. Мы начнем с определения функции getData в нашем компоненте, которая будет использовать год в качестве аргумента для деструктуризации данных Google Sheets, представленных в состоянии приложения.

Теперь мы пройдемся по данным, чтобы рассчитать значения, необходимые для ключевых показателей эффективности. Ниже приведен код для создания KPI для "Обновленных пользователей".

getData = arg => {
   // google sheet data
   const arr = this.state.items;
   const arrLen = arr.length;

   // renewed users
   let renewedUsersVal = 0;
   let prevRenewedUsersVal = 0;
   let renewedUsersChangeper = 0;
   const renewedUsersChangeperElem = document.getElementById("renewed-users-changeper");

   for (let i = 0; i < arrLen; i++) {
      let monthStr = arr[i]["month"];
      if (monthStr.includes(arg)) {
         renewedUsersVal += parseInt(arr[i].renewed_users);
      } else if (monthStr.includes(parseInt(arg) - 1)) {
         prevRenewedUsersVal += parseInt(arr[i].renewed_users);
      }
   }

   // feeding kpi card values and chart kpi tickers
   document.getElementById("renewed-users-val").innerHTML = renewedUsersVal;
};

Аналогично, мы определим переменные для других KPI и присвоим им значение при циклическом проходе данных с использованием приведенного выше фрагмента кода.

5. Создание графиков для SaaS Dashboard

Теперь мы сформируем JSON-данные для графиков и будем использовать FusionCharts и его компонент React для их визуализации.

В функции getData, которую мы создали на предыдущем шаге, мы определим пустой массив, в котором будут данные для графиков. Ниже приведен необходимый код:

// chart cards
let chartDataArr = [];
      
// chart 1 => MRR
let mrrChangeper = 0;
const mrrChangeperElem = document.getElementById('mrr-changeper');

for (let i = 0; i < arrLen; i++) {
   let monthStr = arr[i]["month"];
   if (monthStr.includes(arg)) chartDataArr.push(arr[i]);
}

let chartDataArrLen = chartDataArr.length;

Мы будем использовать диаграмму "Multi-series 2D Single Y Combination Chart" (mscombi2d) на нашей панели. FusionCharts предоставляет множество атрибутов, которые можно использовать для настройки стилей диаграмм.

Теперь мы создадим файл с именем "chartCosmetics.js", в котором будут параметры стилей для нашего графика, чтобы нам не приходилось определять их каждый раз, когда мы его создаем. Вот как это выглядит:

export default {
   currencyChart: {
      bgcolor: "#FFFFFF",
      canvasBgColor: "#FFFFFF",
      showBorder: "0",
      showCanvasBorder: "0",
      showLabels: "0",
      drawCrossLine: "1",
      divLineAlpha: "0",
      showYAxisValues: "0",
      chartLeftMargin: "0",
      chartRightMargin: "0",
      canvasRightMargin: "0",
      canvasLeftMargin: "0",
      chartBottomMargin: "0",
      canvasBottomMargin: "0",
      chartTopMargin: "0",
      canvasTopMargin: "0",
      showValues: "0",
      shadow: "0",
      legendPadding: "0",
      showShadow: "0",
      paletteColors: "#3273DC",
      drawAnchors: "0",
      showAlternateHGridColor: "0",
      crossLineColor: "#363636",
      crossLineAlpha: "15",
      drawCrossLineOnTop: "0",
      usePlotGradientColor: "1",
      plotFillAlpha: "15",
      plotColorinTooltip: "0",
      tooltipBorderAlpha: "0",
      toolTipPadding: "0",
      baseFontColor: "#205BBB",
      baseFontSize: "15",
      baseFont: "Nunito",
      tooltipbgalpha: "0",
      plotFillAngle: "90",
      numberPrefix: "$",
      plotToolText: "<b>$label: $dataValue</b>"
   },
   percentChart: {
      bgcolor: "#FFFFFF",
      canvasBgColor: "#FFFFFF",
      showBorder: "0",
      showCanvasBorder: "0",
      showLabels: "0",
      drawCrossLine: "1",
      divLineAlpha: "0",
      showYAxisValues: "0",
      chartLeftMargin: "0",
      chartRightMargin: "0",
      canvasRightMargin: "0",
      canvasLeftMargin: "0",
      chartBottomMargin: "0",
      canvasBottomMargin: "0",
      chartTopMargin: "0",
      canvasTopMargin: "0",
      showValues: "0",
      shadow: "0",
      legendPadding: "0",
      showShadow: "0",
      paletteColors: "#3273DC",
      drawAnchors: "0",
      showAlternateHGridColor: "0",
      crossLineColor: "#363636",
      crossLineAlpha: "15",
      drawCrossLineOnTop: "0",
      usePlotGradientColor: "1",
      plotFillAlpha: "15",
      plotColorinTooltip: "0",
      tooltipBorderAlpha: "0",
      toolTipPadding: "0",
      baseFontColor: "#205BBB",
      baseFontSize: "15",
      baseFont: "Nunito",
      tooltipbgalpha: "0",
      plotFillAngle: "90",
      numberSuffix: "%",
      plotToolText: "<b>$label: $dataValue</b>"
   }
};

Теперь, мы сформируем массив JSON-данных для каждого графика и будем использовать указанные выше параметры стилей:

// mrr-chart
let mrrChartDataArr = [];
let mrrChartCatArr = [];
for (let i = 0; i < chartDataArrLen; i++) {
   mrrChartCatArr.push({ label: chartDataArr[i].month });
   mrrChartDataArr.push({ value: chartDataArr[i].gross_revenue });
}

const mrrChartConfig = {
   type: "mscombi2d",
   width: "100%",
   height: "100%",
   dataFormat: "json",
   dataSource: {
      chart: chartCosmetics.currencyChart,
      categories: [
         {
            category: mrrChartCatArr
         }
      ],
      dataset: [
         {
            renderAs: "spline",
            lineThickness: "3",
            alpha: "50",
            data: mrrChartDataArr
         },
         {
            renderAs: "splinearea",
            showPlotBorder: "0",
            plotToolText: " ",
            data: mrrChartDataArr
         }
      ]
   }
};

// passing mrr chart JSON array to app's state
this.setState({ mrrChartData: mrrChartConfig });

// feeding value to KPI present in chart card
document.getElementById('mrr-val').innerHTML = `$${ chartDataArr[chartDataArrLen-1].gross_revenue }`;

Примечание: Необходимо объявить нулевую переменную в состоянии приложения для каждого графика, чтобы ее можно было использовать позже, как мы делали выше для данных Google Sheet.

Теперь, когда JSON-данные готовы для наших графиков, мы передадим их компоненту React в FusionCharts под элементом <div>, который мы создали для каждого графика.

<div id="mrr-chart">
  <ReactFC {...this.state.mrrChartData} />
</div>

Чтобы узнать больше об использовании компонента FusionCharts React, вы можете обратиться к странице документации для разработчиков.

Вы можете выполнить вышеуказанные шаги, чтобы создать оставшиеся графики. Теперь мы будем вызывать функцию getData с 2018 в качестве аргумента метода componentDidMount, чтобы наша панель по умолчанию загружала данные для 2018. Если вы уже выполнили вышеуказанные шаги, у вас должна быть функционирующая панель, как на рисунке ниже:

Заключение

Этот урок поможет вам создать инструментальную панель SaaS с помощью Google Sheets. После этого вы можете поработать над магией, добавив больше элементов пользовательского интерфейса, диаграмм, KPI и дополнительных функций. Я добавил некоторые стили и функциональность сам, и вы можете проверить последнюю версию панели здесь.

Для справки, вы можете проверить исходный код из репозитория на Github. Если у вас есть какие-либо вопросы или предложения, оставьте комментарий ниже или напишите мне в Twitter!