Основы

Темы Flextype состоят из файлов и стилей, которые вместе определяют внешний вид сайта. Они могут сильно отличаться между собой, позволяя пользователям быстро изменить дизайн веб-сайта. Мы используем препроцессор Sass для генерации CSS-файлов темы Default, но ничто не мешает вам использовать Less препроцессор или даже обычный CSS.

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

Используйте корректно структурированный, не содержащий ошибок PHP-код и валидный HTML-код

  • Всегда используйте HTML со встроенным(inline) PHP кодом. Никогда не используйте блоки PHP кода.
  • Всегда экранируйте потенциально опасные переменные перед выводом, используя встроенные функции экранирования.
  • Всегда используйте короткий PHP синтаксис (<?=) при выводе переменных. Для всего остального встроенного кода PHP используйте <?php. Не используйте короткие теги.
  • Всегда используйте альтернативный синтаксис для структур управления, которые предназначены для того чтобы сделать шаблоны более понятными.
  • Никогда не используйте фигурные PHP скобки.
  • Только один оператор в каждом PHP теге.
  • Избегайте использования точек с запятой. Они не нужны, если на каждый PHP тег есть только одна инструкция.
  • Никогда не используйте управляющие структуры for, while или switch. Вместо этого используйте if и foreach.

Пример синтаксиса

Пример кода, который соответствует приведенным выше правилам синтаксиса:

<h1>Welcome!</h1>
<p>Hello <?= Html::toText($name) ?></p>

<h2>Friends</h2>
<ul>
    <?php foreach($friends as $friend): ?>
        <li>
            <a href="/profile/<?= Html::toText($friend['id']) ?>">
                <?= Html::toText($friend['name']) ?>
            </a>
        </li>
    <?php endforeach ?>
</ul>

<?php if ($invitations): ?>
    <h2>Invitations</h2>
    <p>You have some friend invites!</p>
<?php endif ?>

Стандарты кодирования CSS

Как и для любых других стандартов кодирования целью формирования стандартов кодирования CSS в Flextype является создание основы для сотрудничества и контроля в рамках различных аспектов проекта и сообщества Flextype, от основного кода до тем и плагинов. Файлы в проекте должны выглядеть так, как будто созданы одним разработчиком. Прежде всего, создавайте код, который будет читаемым, существенным, последовательным и красивым.

Синтаксис

  • После значения свойства обязательно ставится точка с запятой.
  • Для отступов внутри правил используются два пробела. Для правильного форматирования используйте файл .editorconfig в вашем редакторе.
  • Шестнадцатеричное значение цвета не сокращается, а пишется полностью из всех шести символов. Для записи используются строчные буквы. Например, #f5f5f5.
  • Названия тегов и свойств в правилах пишутся строчными буквами.
  • Начальный ноль для значений не сокращается (например, .5 вместо 0.5).
  • Во всех случаях в стилях используются двойные кавычки. В необязательных случаях кавычки не опускаются.
  • После двоеточия в правилах ставится один пробел (top: 10px;). А перед двоеточием пробел не нужен.
  • После запятых внутри значений rgb(), rgba(), hsl(), hsla() или rect() пробелы ставятся. Это повышает удобочитаемость.
  • До и после комбинатора между селекторами (например, p > a) ставится один пробел.
  • Каждое объявление в правиле пишется на новой строке.
  • Перед открывающейся фигурной скобкой ставится один пробел. После скобки запись идёт с новой строки:
    .selector {
      color: #f5f5f5;
    }
    
  • Закрывающая фигурная скобка пишется на новой строке и без отступа. Следующее после этого правило отделяется пустой строкой.
  • Единицы измерения не пишутся, там где в них нет необходимости. Например, border: 0.
  • Для проверки CSS-кода используйте конфигурацию для настройки валидатора stylelint.
  • Для автоматического применения этих правил используйте файл конфигурации csscomb.json для настройки CSSComb.

Пример хорошего кода:

/* Хорошо */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0, 0, 0, 0.5);
  box-shadow: 0 1px 2px #cccccc, inset 0 1px 0 #ffffff;
}

/* Плохо */
.selector, .selector-secondary, .selector[type=text]{
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0,0,0,.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF}

Порядок свойств

Объявления логически связанных свойств группируются в следующем порядке:

  1. Позиционирование
  2. Блочная модель
  3. Типографика
  4. Оформление
  5. Анимация
  6. Разное

Позиционирование следует первым потому, что оно влияет на положение блоков в потоке документа. Блочная модель идёт следующей, так как она определяет размеры и расположение блоков.

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

Сгруппированные объявления в правиле отделяются друг от друга пустой строкой.

Порядок объявления подробных правил, таких как font-size, font-family, line-height, должен соответствовать порядку в сокращённой версии правила. В случае совместного использования подробных и сокращённых правил, первой должна идти сокращённая версия.

Пример:

.declaration-order {
  /* Позиционирование */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Блочная модель */
  display: block;
  float: right;
  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;

  /* Типографика */
  font: normal 13px/1.5 "Arial", sans-serif;
  font-style: normal;
  font-size: 13px;
  line-height: 1.5;
  font-family: "Arial", sans-serif;
  text-align: center;
  color: #333333;

  /* Оформление */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;
  opacity: 1;

  /* Анимация */
  transition: color 1s;

  /* Разное */
  will-change: auto;
}

Имена классов

  • Имена классов пишутся строчными буквами, используется дефис (но не знаки нижнего подчёркивания или camelCase). Дефисы служат разделителями во взаимосвязанных классах (например, .button и .button-danger).
  • Имена классов должны быть такими, чтобы по ним можно было быстро понять какому элементу страницы задан класс: избегайте сокращений (единственное исключение — .btn для кнопок), но не делайте их слишком длинными (более трёх слов).
  • Для написания классов используются английские слова и термины. Транслитом названия классов и атрибутов не пишутся.

Пример:

/* Хорошо */
.alert-danger { … }
.tweet .user-picture { … }
.button { … }
.layout-center { … }

/* Плохо */
.testElement { … }
.t { … }
.big_red_button { … }
.knopka { … }

Правило @import

Правило @import работает медленнее, чем тег <link>. В стилях @import не должен использоваться.

Пример:

<!-- Хорошо: подключение тегом link -->
<link rel="stylesheet" href="module.css">

<!-- Плохо -->
<style>
  @import url("module.css");
</style>

Варианты шрифта

Альтернативные варианты шрифта и тип семейства указываются в конце перечисления font-family.

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

Порядок шрифтов следующий:

  1. нестандартный шрифт;
  2. веб-безопасный;
  3. тип шрифта.

Список веб-безопасных шрифтов можно посмотреть здесь — cssfontstack.com.

/* Хорошо: указан альтернативный веб-безопасный шрифт и его тип семейства */
body {
  font-family: "Helvetica", "Arial", sans-serif;
}

/* Кому-то нравится Arial, кому-то Tahoma */
body {
  font-family: "Helvetica", "Tahoma", sans-serif;
}

/* Плохо: указан только нестандартный шрифт */
body {
  font-family: "Helvetica";
}

/* Плохо: указан только нестандартный шрифт и тип семейства, альтернативный веб-безопасный шрифт отсутствует */
body {
  font-family: "Helvetica", sans-serif;
}

/* Плохо: Georgia — шрифт с засечками, а нестандартный шрифт — без засечек */
body {
  font-family: "Helvetica", "Georgia", sans-serif;
}