Skip to main content

Кастомизация

Кастомизация - это способ расширить UI возможности N2O через создание собственной темы стилей или визуальных компонентов.

Для создания кастомизации вам понадобятся знания следующих технологий:

Настройка окружения​

Для кастомизации вам потребуется установить следующее программное обеспечение:

Создание React проекта​

Перед тем как подключить кастомизацию необходимо создать React проект c N2O Framework.

Сборка React проекта выполняется менеджером пакетов yarn.

В корне N2O проекта выполните команду:

npm init react-app frontend

Эта команда создаст папку frontend, в ней создаст необходимые для начала работы файлы и папки, включая index.tsx.

Перейдите в папку /frontend:

cd frontend

Затем установите библиотеку n2o-framework:

yarn add n2o-framework

Далее необходимо удалить лишние файлы, созданные после инициализации. Удалите файлы App.css, App.js, App.test.js, logo.svg, reportWebVitals.js.

Отредактируйте файл /frontend/src/index.tsx. Он должен выглядеть следующим образом:

import React from 'react';
import ReactDOM from 'react-dom';
import N2O from 'n2o-framework';
import createFactoryConfig from "n2o-framework/lib/core/factory/createFactoryConfig";
import authProvider from "n2o-framework/lib/core/auth/authProvider";

import 'n2o-framework/dist/n2o.css';
import './index.css';

const config = {
  security: {
    authProvider,
    externalLoginUrl: '/'
  }
};

ReactDOM.render(
  <React.StrictMode>
    <N2O {...createFactoryConfig(config)} />
  </React.StrictMode>,
  document.getElementById('root')
);

Теперь N2O React проект готов.

Для сборки проекта в папке /frontend выполните команду:

yarn

А затем:

yarn build

В результате в папке /frontend/build появится index.html и другие статические ресурсы.

Чтобы подключить статические ресурсы к N2O серверу, в файле pom.xml в разделе <plugins> добавьте maven-resources-plugin:

<plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>Copy frontend build</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>target/classes/public</outputDirectory>
                <overwrite>true</overwrite>
                <resources>
                    <resource>
                        <directory>${project.basedir}/frontend/build</directory>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

Теперь N2O сервер будет раздавать статические ресурсы собранные в React проекте в папке /frontend/build.

Подключение кастомизаций​

Кастомизации передаются в N2O с помощью конфигурационного объекта:

note

Минимальный вид конфигурационного объекта, с обязательным свойством security

const config = {
    // ... кастомизации
    security: {
        authProvider,
        externalLoginUrl: './',
    },
}
frontend/src/index.tsx
import React from "react";
import N2O from "n2o-framework";
import authProvider from "n2o-framework/lib/core/auth/authProvider";
import createFactoryConfig from "n2o-framework/lib/core/factory/createFactoryConfig";

const config = {
    // ... кастомизации
    security: {
        authProvider,
        externalLoginUrl: './',
    },
}

ReactDOM.render(
  <React.StrictMode>
    <N2O {...createFactoryConfig(config)} />
  </React.StrictMode>,
  document.getElementById('root')
);

Конфигурационный объект содержит наборы компонентов, разбитые по типам кастомизации:

const config = {
  controls,
  widgets,
  regions,
  pages,
  headers,
  cells,
  fieldsets,
  fields,
  actions,
  snippets,
  buttons,
  templates: {
    header,
    footer,
    sidebar,
  },
  security
};
note

Для кастомизации header footer sidebar необходимо в свойство templates конфигурационного объекта, передать кастомные компоненты.

Пример описывающий как реализовать данную возможность:

Пример кастомного Header frontend/src/components/plugins/CustomHeader.js
import SimpleHeader from 'n2o-framework/lib/plugins/Header/SimpleHeader/SimpleHeader'
export function CustomHeader(config) {
    return (
        <SimpleHeader { ...config } />
    )
}
Пример кастомного Footer frontend/src/components/plugins/CustomFooter.js
import Footer from 'n2o-framework/lib/plugins/Footer/Footer'
export function CustomFooter(config) {
    return (
        <Footer { ...config } />
    )
}
Пример кастомного Sidebar frontend/src/components/plugins/CustomSidebar.js
import SideBar from 'n2o-framework/lib/plugins/SideBar/SideBar'
export function CustomSidebar(config) {
    return (
        <SideBar { ...config } />
    )
}

Имена переданных в N2O компонентов header footer sidebar задаются с помощью атрибута src в application.xml

Пример application.xml
<application xmlns="http://n2oapp.net/framework/config/schema/application-3.0"
             welcome-page-id="index">
    <header src="CustomHeader" />
    <sidebar src="CustomSidebar" />
    <footer src="CustomFooter" />
</application>

Передача кастомных компонентов в свойство templates конфигурационного объекта

frontend/src/index.tsx
import CustomHeader from "./components/plugins/CustomHeader";
import CustomSidebar from "./components/plugins/CustomSidebar";
import CustomFooter from "./components/plugins/CustomFooter";

const config = {
    // ... кастомизации
    templates: {
        CustomHeader,
        CustomSidebar,
        CustomFooter,
    },
    security
}

ReactDOM.render(
  <React.StrictMode>
    <N2O {...createFactoryConfig(config)} />
  </React.StrictMode>,
  document.getElementById('root')
);
note

Хорошей практикой будет создать папку components в frontend/src для размещения в ней всех ваших компонентов. В папке components разделить компоненты по типам кастомизаций, например: /pages, /widgets, /cells. В каждой из этих папок будут находиться:

  • папки с кастомными компонентами
  • файл index.tsx, в котором будут экспортироваться эти компоненты
frontend/src/components/pages/index.tsx
import HelloPage from './HelloPage/HelloPage.js';

export default {
    HelloPage
};

В config объект передать импортированные наборы компонентов:

frontend/src/index.tsx
import pages from './components/pages';

const config = {
    pages,
    security
}

Переданные в N2O компоненты можно использовать в конфигурациях с помощью атрибута src:

Подключение кастомного компонента
<?xml version='1.0' encoding='UTF-8'?>
<simple-page xmlns="http://n2oapp.net/framework/config/schema/page-4.0"
             src="HelloPage">
    ...
</simple-page>

Отладка​

Для отладки кастомизаций необходимо будет запустить приложение в режиме разработки. В режиме разработки все вносимые в проект изменения автоматически применяются и сразу отображается результат. Для этого необходимо клиентскую часть проекта запустить на локальном NodeJS сервере, а серверная часть может находиться как удаленно, так и запущена локально.

Проксирование запросов на сервер N2O осуществляется с помощью библиотеки http-proxy-middleware. Для подключения http-proxy-middleware к проекту выполните команду:

yarn add http-proxy-middleware --dev

URL целевого сервера указывается в файле setupProxy.js. Создайте его в папке src и укажите цель для проксирования:

frontend/src/setupProxy.js
const {createProxyMiddleware} = require('http-proxy-middleware');
module.exports = function (app) {
    app.use(
        '/n2o',
        createProxyMiddleware({
            // URL целевого сервера (локальный или удаленный)
            target: "http://localhost:8080",
            changeOrigin: true
        })
    );
};

Запуск приложения выполняется командой:

yarn start

Приложение откроется по адресу http://localhost:3000.

Кастомизация стилей​

Кастомизация стилей предназначена для изменения общего внешнего оформления приложения в соответствии с вашими пожеланиями. Кастомизация стилей заключается в переопределении стилей стандартных css классов и css-переменных N2O и Bootstrap на свои собственные.

Стандартные стили N2O находятся в папке frontend/node_modules/n2o-framework/src/sass:

frontend/node_modules/n2o-framework/src/sass
/n2o             // папка со основными стилями N2O
/theme           // папка со стилями темы N2O
bootstrap.scss   // корневой файл всех стилей, импортированных из библиотеки bootstrap
n2o.scss         // корневой файл всех стилей N2O
variables.scss   // корневой файл всех css-переменных N2O

Сборка стилей N2O выполняется с помощью библиотеки sass. Для ее подключения выполните команду:

yarn add sass --dev

После этого файл index.css, расположенный в папке src проекта, необходимо переименовать в index.scss.

Чтобы передать управление стилями проекту, необходимо отредактировать директивы import в файле index.tsx:

src/index.tsx
//import 'n2o-framework/dist/n2o.css';  // эту директиву необходимо удалить
import './index.scss';                  // файл index.css необходимо переименовать в index.scss
...

Файл index.scss является корневым файлом стилей вашего проекта, поэтому все файлы стилей должны подключаться в него. Первым должен быть подключен корневой файл стилей N2O:

frontend/src/index.scss
@import "n2o-framework/src/sass/n2o.scss";
...

Теперь необходимо скопировать в ваш проект файлы со стилями и css-переменными, которые вы будете переопределять, из frontend/node_modules/n2o-framework/src/sass.

note

Хорошей практикой считается хранение файлов стилей проекта в отдельной папке, например /sass. Рекомендуется сохранять такие же названия папкам, которые вы будете копировать из n2o-framework.

Для подключения измененных стилей укажите относительный путь до файла с изменениями в index.scss:

frontend/src/index.scss
// стандартные стили N2O
@import "n2o-framework/src/sass/n2o.scss";

// файлы общих стилей вашего проекта
@import "./sass/variables.scss";
@import "./sass/theme/variables";
...
// файлы стилей компонентов вашего проекта
@import "./sass/someComponent.scss";
@import "./sass/anotherComponent.scss"
note

При подключении файлов стилей к проекту решающее значение имеет очередность подключения. Следует строго придерживаться следующего порядка:

  1. файл стилей N2O
  2. файлы с css-переменными вашего проекта
  3. файлы стилей компонентов, контролов, темы вашего проекта

Если запустить проект в режиме разработки, все изменения в файлах стилей будут подхватываться и сразу отображаться.

Кастомное действие​

Кастомное действие позволяет расширить логику работы с n2o store. Для вызова с сервера, в реакт проекте не требуется дополнительных действий. Обработка кастомного действия зависит от бизнес-требования.

Если необходимо расширить n2o store новыми ключами данных, следует написать reducer.

note

Хорошей практикой будет создать папку reducers в frontend/src для размещения в ней всех ваших reducers. Импорт в config вашего App (app/src/App.jsx) производить из общего файла импорта index.tsx

Ключ в config должен быть customReducers

index.tsx
import { customReducer1 } from './reducers/custom1/store'
import { customReducer2 } from './reducers/custom2/store'

export const customReducers = { custom1: customReducer, custom2: customReducer2 }

Если нет необходимости расширять n2o store, достаточно реализовать saga effect для манипуляции на кастомным действием.

note

Хорошей практикой будет создать папку sagas в frontend/src для размещения в ней всех ваших sagas. Импорт в config вашего App (app/src/App.jsx) производить из общего файла импорта index.tsx

Ключ в config должен быть customSagas

index.tsx
import { saga } from './sagas/action1/saga1'
import { saga2 } from './sagas/action2/saga2'

export const customSagas = [
    saga,
    saga2,
]

Импорт в n2o config

app/src/App.jsx
const config = createFactoryConfig({
    // ... кастомизации
    customReducers,
    customSagas,
})

ReactDOM.render(
  <React.StrictMode>
    <N2O {...config} />
  </React.StrictMode>,
  document.getElementById('root')
);

Для расширения существующих объектов данных из n2o store необходимо создать расширенный объект данных.

note

Не является безопасной практикой. Мы не можем отвечать за работоспособность функционала при изменении данных из n2o-framework store. Рекомендуется только добавление новых ключей данных, а не мутации уже существующих.

Пример. Чтобы расширить объект page.

  1. Выполняем импорт pageSlice из n2o-framework.
  2. Выполняем импорт initialState из n2o-framework.
  3. Создаем slice в качестве name указываем pageSlice.name
  4. Добавляем значение initialState
  5. В поле reducers необходимо сделать спред всех редюсеров pageSlice.caseReducers.
note

Список reducers можно увидеть по пути n2o-framework/lib/reducers

import { pageSlice, initialState } from 'n2o-framework/lib/ducks/pages/store'

const extendedPagesSlice = createSlice({
   name: pageSlice.name,
   initialState,
   reducers: {
      ...pageSlice.caseReducers,
      // ... ваша логика
   }
})

export const pagesReducers = extendedPagesSlice.reducer

При экспорте, в customReducers, необходимо использовать ключ reducer из n2o-framework.

export const customReducers = { pages: pagesReducers }
note

Клиентские действия реализуются идентично сервер/клиент действиям.

Для конфигурации кастомного действия в xml используется элемент <action>. В данном теге необходимо указать Redux тип действия, а также можно настроить поведение приложения после выполнения действия. Полезная нагрузка Redux действия конфигурируется с помощью дочернего для <action> элемента <payload>. Тег <payload> поддерживает возможность использования любых атрибутов, а также возможность преобразованием в json-объекты атрибуты, использующие "дефис" в именовании.

xml конфигурация кастомного действия
<action type="n2o/actionImpl/START_INVOKE"
    redirect-url="/test" redirect-target="application">
    <payload dataProvider-url="n2o/data/mi2"
             dataProvider-method="POST"
             datasource="_main"
             model="resolve"
             pageId="_"
             widgetId="_main"/>
</action>
json, полученный в результате компиляции
"action": {
    "type": "n2o/actionImpl/START_INVOKE",
    "payload": {
    "datasource": "_main",
    "widgetId": "_main",
    "model": "resolve",
    "dataProvider": {
        "method": "POST",
        "url": "n2o/data/mi2"
        },
    "pageId": "_"
    },
    "meta": {
        "success": {
            "refresh": {
                "datasources": [
                    "_main"
                    ]
                },
            "redirect": {
                "path": "/test",
                "pathMapping": {},
                "queryMapping": {},
                "target": "application"
                }
            },
        "fail": {}
    }
}

Смена favicon и других статичных элементов​

Чтобы поменять иконку приложения favicon, необходимо:

  1. Написать реализацию StaticCustomizationController
  2. Указать путь расположения новой иконки, реализовав метод faviconPath()

Пример:

@Controller
public class MyFaviconController extends StaticCustomizationController {

    @Value("${n2o.favicon.path}")
    private String path;

    @Override
    protected String faviconPath() {
        return path;
    }
}

Также с помощью реализации StaticCustomizationController можно переопределить получение других статичных элементов.