English description | Описание на русском
Вся файловая структура генерируется автоматически. Руками ничего создавать не нужно!
Сборщик имеет следующую файловую структуру:
├── gulpfile.js # gulpfile сборщика
├── tars.json # Системный файл с информацией о текущей версии
├── tars-config.js # Конфигурационный файл
├── package.json # Основные зависимости
├── .babelrc # Конфиг для Babel
├── .eslintrc # Конфиг для eslint
├── user-package.json # Пользовательские зависимости
└── tars/ # Таски и хелперы для gulp
├── helpers/ # Хелперы
├── tasks/ # Основные таски (разложены по папкам в соответствии с типом таска)
├── user-tasks/ # Пользовательские таски
├── watchers/ # Основные вотчеры (разложены по папкам в соответствии с типом отслеживаемых файлов)
├── user-watchers/ # Пользовательские вотчеры
└── tars.js # Основной файл сборщика
├── markup/ # Основная папка с проектом
├── components/ # Компоненты
├── pages/ # Шаблоны страниц
└── static/ # Различная статика (css, js и т.п.)
└── docs/ # Документация
Компонент — самостоятельная единица на странице. Пример компонента — «header» или «footer». Каждая страница состоит из компонентов. Компоненты могут подключать друг друга и быть вложены друг в друга.
exampleComponent/ # Пример компонента
├── assets/ # Файлы, относящиейся только к данному компоненту (файлы любого типа) Поддиректории не поддерживаются.
├── ie/ # Cтили для IE8 и IE9 (ie9.scss|sass|less|styl и ie8.scss|sass|less|styl)
├── data/ # Папка для хранения данных для компонента
└── data.js # Данные для компонента в виде js-объекта (формат объекта есть в компонентк-примере _template)
├── exampleComponent.html # Html-представление компонента (также может иметь расширение jade или hbs, в зависимости от выборанного шаблонизатора)
├── exampleComponent.scss|sass|less|styl # Css-представление компонента (scss|sass|less|styl, в зависимости от выбранного css-препроцессора)
├── exampleComponent.js # Js-представление компонента
└── anotherComponentFolder
Любой компонент может быть вложен (как структурно, так и в коде) в любой другой.
Изображения из директории assets в результате сборки будут перемещены в static/img/assets/имя_компонента или static/img/assets/имя_компонента/имя_вложенного_компонента, если у компонент вложен в другой компонент. К картинкам относятся: svg, png, jpg, jpeg, jpe, gif, tiff и bmp. Все остальные файлы будут помещены в папку components-assets (имя папки зависит от опции fs.componentsFolderName).
Основная идея в том, чтобы сделать компонент как можно более изолированной структурой. Здесь можно использовать BEM, веб-компоненты (и их реализация от Google), что-то еще. Можно все делать и по старинке, внутри одного компонента вся верстка, но это крайне не рекомендуется. Если говорить терминами BEM, то каждый компонент — это блок. Есть отличная лекция о том, как лучше организовать свой код, ссылка.
В pages находятся шаблоны страниц, в которые в итоге будут включены компоненты. Страницы являются лэйаутом и должны содержать в себе как можно меньше кода, чтобы структура была как можно более прозрачная.
Чтобы создать новую страницу, просто скопируйте существующую (или _template) и переименуйте или используйте tars add-page.
Также вы можете добавить компонент с помощью TARS-CLI — tars add-component.
Будем считать, что css-препроцессором был выбран Scss.
static/ # Папка для статики. Название для папки настраивается в tars-config.js
├── fonts/ # Шрифты (может содержать поддиректории)
├── img/ # Картинки. Название для папки настраивается в tars-config.js
├── content/ # Контентные картинки (может содержать поддиректории)
├── plugins/ # Картинки для плагинов (может содержать поддиректории)
├── general/ # Общие картинки для проекта (может содержать поддиректории)
├── sprite/ # Растровые картинки, которые должны быть включены в спрайт (png)
├── 96dpi/ # Картинки для экранов с dpi 96
...
└── 384dpi/ # Картинки для экранов с dpi 384 (более подробно в разделе работы с изображениями)
└── svg/ # SVG-картинки
├── js/ # js
├── framework/ # js-фреймворки (например, backbone)
├── libraries/ # js-библиотеки (например, jquery)
├── plugins/ # js-плагины
└── separate-js/ # js-файлы, которые не должны попасть в итоговый склеенный js-файл.
├── misc/ # Общие файлы, которые будут перемещены в корень собранного проекта — фавиконка, robots.txt и т.д. (может содержать поддиректории)
└── scss
├── entry/ # Стили, для точек входа при ручном управлении компиляции стилей. Подробнее [тут](css-manual-processing.md).
├── etc/ # Стили, которые будут подключаться в самом конце (может содержать поддиректории)
├── libraries/ # Стили библиотек (может содержать поддиректории)
├── plugins/ # Стили для плагинов (может содержать поддиректории)
├── separate-css/ # Стили, которые не должны попасть в итоговый склеенный css-файл.
├── sprite-generator-templates/ # Шаблоны, по которым генерируются спрайты
├── sprites-scss/ # Миксины для спрайтов
├── common.scss # Общие стили для всего проекта
├── fonts.scss # Стили для подключенный шрифтов
├── GUI.scss # Стили для GUI-элементов типа кнопок, полей ввода и т.д.
├── mixins.scss # Набор миксинов
├── normalize.scss # Сброс стилей
└── vars.scss # Переменные проекта
После сборки проекта в корне появятся две папки: dev и builds. Ниже дано описание dev-версии сборки (С включенным режимом --ie8), так как готовый билд не сильно отличается от dev.
dev/
└── static/ # Статика для проекта (имеет имя, заданное в tars-config)
└── css/ # Готовые файлы стилей для всех основных браузеров, IE9 и IE8, если включена их поддержка и стили, которые не вошли в общую сборку.
└── components-assets/ # Файлы для компонентов.
└── exampleComponent/
└── img/ # Картинки для проекта
└── assets/ # Файлы для компонентов. Содержит в себе директории с именами тех компонентов, которые имеют доп. файлы (только картинки)
└── exampleComponent/
└── content/ # Картинки для контента
└── plugins/ # Картинки для плагинов
└── svg-sprite/ # SVG-спрайт
└── png-sprite/ # PNG-спрайты для разных dpi
└── rastered-svg-images/ # Отрастированные svg-картинки для IE8
└── minified-svg/ # Минифицированные svg
└── js/ # Итоговый main.js файл и js-файлы, которые не должны попасть в общую сборку.
└── separate-js/
└── temp/ # Папка для данных для компонентов
├── Готовые страницы и файлы из папки misc
build-версия проекта не содержит папки temp, включает минимизированные css- и js-файлы. Содержит оптимизированные картинки и архив с собранным проектом (опционально).
Если включена опция useBuildVersioning, то каждый билд будет лежать в отдельной папке по пути, который указан в опции buildPath, под названием build_ver%дата сборки%. Если useBuildVersioning отключен, то готовый проект находится по пути, который указан в опции buildPath, в папке build.
При подключении картинок необходимо использовать именно тот путь, по которому они лежат в собранном проекте.
Сразу после инициализации или переинициализации в корне могут появиться папки .tmpPreproc и .tmpTemplater, в которых находятся скачанные шаблонизатор и css-препроцессор. При первой же сборке эти папки будут удалены. Так что просто не обращайте на них внимание. Эти папки влючены в .gitignore, так что они точно не попадут в ваш репозиторий.
Данную файловую структуру можно менять, с правкой соответствующих тасков и вотчеров. Для некоторых папок нет необходимости лезть в таски и вотчеры. Например, можно создать папки для хранения js, который должен быть выполнен до компонентов и после. Это будет полезно при использовании различных js-фреймворков.
Также не обязательно пользоваться всеми папками для изображений или js. Если что-то не нужно, это можно удалить.