Django-Gentelella

h1. Django-gentelella

*Django Gentelella* - это интерфейс для применения темы Gentelella https://colorlib.com/polygon/gentelella/ на проекты, написанные на основе фреймворка Django. Данный интерфейс состоит из собственных форм, базовых шаблонов страниц, к которым применена тема Gentelella, а также содержит набор кастомных элементов страниц (таблицы, модальные формы, элементы рендера и прочее).

h2. Установка

Для установки пакета необходимо склонировать репозиторий в директорию проекта

<pre>

git clone gitosis@dev.skycover.ru:/django_gentelella

</pre>

добавить django_gentelella в список установленных приложений в @settings.py@

<pre>

<...>

INSTALLED_APPS = [

    'django.contrib.admin',

    <...>,

    'django_gentelella',

]

<...>

</pre>

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

Для использования темы Gentelella в шаблонах следует встраивать их в базовый:

<pre>

{% extends 'django_gentelella/templates/base.html' %}

</pre>

Для использования компонентов необходимо импортировать django_gentelella в шаблон:

<pre>

{% load django_gentelella %}

</pre>

h2. Компоненты

h3. Модели

*IntervalField* — поле для хранения интервалов дат в форме количества секунд. Наследуется от BigInt, в качестве аргументов может принимать verbose_name, минимальное и максимальное значение, формат.

h3. Формы

*ModelForm* - заменяет используемые поля форм Django на соответствующие поля Django Gentelella

*Form* - оформляет используемые поля как form-control

*ROFormMixin* - миксин для установки статуса Read Only для полей. В качестве аргументов получает:

## *read_only* - список полей для установки на них статуса

## *read_only_exclude* - список полей, для которых статус устанавливать не надо (в случае, если read_only == '__all__')

*IntervalFormField* - поле для указания интервала времени в определённое количество часов, минут и секунд.

*IntervalWidget* - виджет для поля указания интервала.

!intfield.png!

*Select2* - виджет для оформления полей выбора элемента из множества.

!chfield.png!

*Select2Multiple* - виджет для оформления полей множественного выбора.

!multiselect.png!

*CheckBox* - виджет для оформления поля выбора как группы кнопок.

!check.png!

Также предоставлены собственные замены для стандартных виджетов:

|_. Виджет Django |_. Виджет DG |

| NumberInput | IntegerInput |

| TextInput | TextInput |

| Textarea | TextArea |

| Select | Select2 |

| SelectMultiple | Select2Multiple |

| DateTimeInput | DateTime |

| DateInput | Date |

| TimeInput | TimeInput |

| CheckboxInput | SwitheryInput |

*Пример использования компонентов Django Gentelella в формах*

<pre>

from django import forms

from django_gentelella.forms import Select2, Select2Multiple, Form, DateTimeRangeField, DateTimeRangeWidget, IntervalFormField, SwitheryInput, CheckBox, Form, Date

class TestForm(Form):

    choices = (

        ('spam', 'Spam'),

        ('eggs', 'Eggs'),

        ('spanish_inquisition', 'Spanish Inquisition'),

    )

    interval = IntervalFormField(label='Interval field', required=False) 

    choice = forms.ChoiceField(label='Choice field', choices=choices, widget=Select2, required=False)

    multiselect = forms.MultipleChoiceField(label='Multiple choices', choices=choices, widget=Select2Multiple, required=False)

    swithery = forms.BooleanField(label='Swithery input', widget=SwitheryInput, required=False)

    radiobox = forms.ChoiceField(label='Checkboxes', choices=choices, widget=CheckBox, required=False)

    date = forms.DateField(label='Date', widget=Date)

</pre>

h3. Виды

*BaseView* - базовый вид, от которого необходимо наследовать прочие виды проекта.

Переменные класса:

# title - заголовок страницы. По-умолчанию: 'Base View';

# title_icon - иконка страницы в формате названия из пакета Font Awesome. По умолчанию: 'bus';

# position - идентификатор пункта меню, считающегося выбранным, когда страница открыта. По умолчанию: None;

# breadcrumbs - значение, отвечающее за отображение "хлебных крошек" вверху страницы. По умолчанию: False;

# menu - меню в левой колонке базового шаблона (см. "Редактирование меню"). По умолчанию: OrderedDict();

# template_name - имя шаблона, использующегося в базовом виде. По умолчанию: 'django_gentelella/base.html'.

*GentelellaCreateView* - собственный вариант вида CreateView из django.views.generic.

Переменные класса:

# menu - меню в левой колонке базового шаблона (см. "Редактирование меню"). По умолчанию: NotImplemented;

# title - заголовок страницы. По умолчанию: NotImplemented;

# template_name - имя шаблона, использующегося в виде. По умолчанию: NotImplemented.

# model - модель, объект которой создаётся в данном виде. По умолчанию: NotImplementedError

# form_class - использующаяся на странице форма. По умолчанию: NotImplemented.

# success_url - ссылка, на которую будет совершён переход при успешном создании объекта. По умолчанию: NotImplemented.

Используется точно так же, как и CreateView из django.views.generic.

h3. Тэги шаблонов

*custom_table* - отрисовывает таблицу по заданным данным. В качестве аргументов принимает список данных и перечень полей (каждое поле записано как отдельный аргумент формата field__name="Name"). Первая строка внутри тэга - то, что следует отображать при отсутствии данных, далее - данные для тех полей с особым форматированием:

<pre>

{% field 'name' %}

<b>{{ obj.name }}</b>

</pre>

Также поля можно подавать через объект OrderedDict, где ключи - это идентификаторы полей, а значения  - заголовки:

<pre>

fields = OrderedDict((

    ('first', 'First Thing'),

    ('second', 'Second Thing'),

    ('third', 'Third Thing'),

    ('pseudo', 'Pseudothing')

))

</pre>

Закрывающий тэг: @{% end_custom_table %}@

Данные для таблицы подаются в виде списка словарей, где ключи - это названия полей таблицы.

Пример:

<pre>

table_contents = [{

    'first': 'Spam',

    'second': 'Eggs',

    'third': 'Spanish Inquisition',

},

{

    'first': 'Something Completely Different',

    'second': 'Ni!',

    'third': 'What is your favourite colour?'

}

]

</pre>

<pre>

{% custom_table table_contents field__first='First Thing' field__second='Second Thing' field__third='Third Thing' field__pseudo='Pseudothing' %}

  Nothing's going on here, citizen.

  {% field 'pseudo' %}

  Beware the simulacrum!

{% end_custom_table %}

</pre>

<pre>

{% custom_table table_contents fields %}

  Nothing's going on here, citizen.

  {% field 'pseudo' %}

  Beware the simulacrum!

{% end_custom_table %}

</pre>

!table.png!

*xpanel* - div-контейнер для элементов в виде панели. В качестве обязательного аргумента принимает заголовок. Пример:

<pre>

{% xpanel 'Заголовок' %}

  содержимое

{% end_xpanel %}

</pre>

!panel.png!

*modal* - контейнер для элементов в виде вызываемого модального окна. Принимает следующие аргументы:

## Заголовок

## size - размер окна

## id_ - идентификатор окна

Пример использования:

<pre>

<button class='btn btn-primary' data-toggle="modal" data-target="#modal">Check messages</button>

{% modal 'Заголовок' size='xl' id_='modal' %}

  Содержимое

{% end_modal %}

</pre>

!modal.png!

h3. Шаблоны

*base* - базовый шаблон, в который встраиваются все страницы сайта в теме. 

*footer* - футер страницы.

*login* - стандартная страница логина.

h3. Редактирование бокового меню

Для того чтобы сделать кастомное боковое меню, следует создать собственный вид, наследующийся от BaseView из django_gentelella, в котором указать переменную menu с желаемым меню, сформированным в формате OrderedDict. Каждый элемент словаря должен иметь в качестве ключа уникальный идентификатор, а в качестве значения - кортеж или список со следующими данными:

# Название пункта

# Ссылка, на которую ведёт пункт

# Описание пункта

# Права, которыми должен обладать пользователь для отображения или сокрытия пункта. Например ['right_to_view|1'], где слева от | указано название права, справа - показывать или, наоборот, скрывать пункт при наличии такого права у пользователя.

# Дочерние пункты

Пример использования:

<pre>

MENU = OrderedDict((

    # название, ссылка, описание, 'права|показывать[01]', иконка

    ('main_page', (

        'Страница', reverse_lazy(''),

        'Это страница, на ней написано', [],

        'credit-card', OrderedDict((

            ('ultra_main_page', (

                'Та же страница', reverse_lazy(''),

                'Дочерний пункт меню', [],

                'credit-card', OrderedDict((

                ))

            )),

        ))

    )),

    ('submain_page', (

        'Та же страница', reverse_lazy('test'),

        'Это та же самая страница', [],

        'credit-card', OrderedDict(())

    )),

    ))

class MyBaseView(BaseView):

    menu = MENU

    template_name = 'django_gentelella/base.html'

    title_icon = 'balance-scale'

    title = 'DG Test'

    permission_required = ()

    def get(self, request, *args, **kwargs):

        return super().get(request, *args, **kwargs)

</pre>

Создаваемые впоследствие виды наследоваться от MyBaseView.

!menu.png!

h3. Тэги

Тэги - это шаблоны компонентов, которые можно импортировать в собственный шаблон для стандартизированного рендера отдельных его частей.

**form_template** - шаблон для рендера форм. 

Пример использования:

<pre>

{% include 'django_gentelella/tags/form_template.html' with form=form %}

</pre>

!form_t.png!

h3. Скрипты

*native_message* - скрипт на JS для создания браузерных уведомлений. Принимает следующие аргументы:

# title - заголовок;

# message - сообщение;

# options - опции уведомления.

h2. Дополнительные материалы

"Gentelella Alela!":https://colorlib.com/polygon/gentelella/index.html - демо-страница темы Gentelella.