README.txt 8.55 KB
Newer Older
1

joelpittet's avatar
joelpittet committed
2
=====================
3
Introduction to Basic
joelpittet's avatar
joelpittet committed
4
=====================
5

6
Basic boasts a clean HTML5 structure with extensible CSS classes and IDs for
joelpittet's avatar
joelpittet committed
7
8
unlimited theming possibilities as well as a top-down load order for improved
SEO. It is fully responsive out-of-the-box and provides an adaptive, elegant,
9
SASS-based grid system (Bourbon Neat).
10

joelpittet's avatar
joelpittet committed
11
12
Basic's goal is to provide themers the building blocks needed to get their
designs up and running quickly and simply.
13

14
Basic is perfect if you want a simple, smart, and flexible theme starter.
15

16
Less code spam, more ham.
17

joelpittet's avatar
joelpittet committed
18

joelpittet's avatar
joelpittet committed
19
============
20
Installation
joelpittet's avatar
joelpittet committed
21
============
22

23
24
Basic utilizes a Sass framework for adaptive grids and layouts and general structure of the
site. It's recommended to use Sass for building out your theme. The following
joelpittet's avatar
joelpittet committed
25
packages are included via 'npm install'
26
  - Bourbon (http://bourbon.io/)
27
  - Bourbon Neat (http://neat.bourbon.io/)
28

29
Basic is meant to be YOUR theme. Follow one of the two methods below and you can
30
31
rename 'basic' to another name like 'mytheme'. You're also welcome to keep
'basic'.
32

33
34
35
1. DRUSH: The provided drush install script will duplicate the basic theme
   folder and rename all appropriate files and content to the new theme name you
   provide.
36

37
38
39
  - Download and enable the basic theme: $ drush en basic
  - Set the theme as default $ drush config-set system.theme default basic
    or copy the includes/basic.drush.inc into your .drush folder.
40
  - Run the provided drush install script: $ drush basic-install
41
42
  - The script will first ask you to enter your theme name (eg. My Theme).
    Second, it will ask you to enter a machine name (eg. my_theme).
43
44
45
46
47
48
  - After complete, you can enable your new theme: $drush en my_theme
  - At this time, you can uninstall basic: $drush pmu basic
  - Commence work on your theme!

2. MANUAL: To manually change the name of the theme follow these steps BEFORE
   enabling the theme:
49

joelpittet's avatar
joelpittet committed
50
51
  - Rename the theme folder to 'mytheme'
  - Rename basic.info.yml to mytheme.info.yml
52
53
  - edit basic.info.yml and change the name, description, project (can be
    deleted), and change all other instances of 'basic' to 'mytheme'
54
  - Rename basic.libraries.yml to mytheme.libraries.yml
joelpittet's avatar
joelpittet committed
55
  - Rename basic.theme to mytheme.theme
56
  - in basic.theme, change each instance of 'basic' to 'mytheme'
joelpittet's avatar
joelpittet committed
57
58
  - Rename config/schema/basic.schema.yml to mytheme.schema.yml
  - Rename each file in config/install from block.block.basic_tools.yml (for
59
    example) to block.block.mytheme_tools.yml
joelpittet's avatar
joelpittet committed
60
  - Every file in config/install, change each instance of 'basic' to
61
    'mytheme'
joelpittet's avatar
joelpittet committed
62
63
64
65
  - In js/source/scripts.js, change each instance of 'basic' to 'mytheme'
  - In theme-settings.php, change each instance of 'basic' to 'mytheme'
  - In templates/html.html.twig, change each instance of 'basic' to 'mytheme'
  - In templates/menu-local-tasks.html.twig, change each instance of 'basic' to
66
    'mytheme'
joelpittet's avatar
joelpittet committed
67
  - In templates/status-messages.html.twig, change each instance of 'basic' to
68
    'mytheme'
69

70
  When renaming, remember the following:
71
72
  - Do not simply replace every instance of 'basic' in every file in the theme.
    Most of Basic's dependencies use the word 'basic' somewhere and renaming
73
    these instances will cause Basic to break in unpredictable ways.
74
75
76
77
78
79
80
81
  - If you don't rename all these files, you may get a vague and unhelpful error
    message when attempting to enable your theme: "The website encountered an
    unexpected error. Please try again later." Turn on a higher level of error
    logging in your server's php.ini to help determine what you've missed.
  - If you don't bother renaming Basic in the above locations, be advised that
    you will run into conflicts with other versions of Basic on your site. If
    your site uses more than one theme based on Basic, make sure at least one of
    the themes has been renamed properly!
82
83
84


============================
85
How to compile Sass in Basic
86
============================
SteveK's avatar
SteveK committed
87

88
89
To use Sass and automatically compile it within your theme, please refer to "How
to Use Gulp with Basic" in the documentation below.
90

91
92
93
94
Install node-sass:

  npm install node-sass -g

95
If you don't like Gulp, or would just prefer to use Sass' internal watch
96
functionality, simply cd into your theme directory and run:
SteveK's avatar
SteveK committed
97

98
99
100
101
102
  node-sass sass -o css --output-style expanded --source-map true --watch

Or simply compile the latest:

  node-sass sass -o css --output-style expanded --source-map true
SteveK's avatar
SteveK committed
103

104

joelpittet's avatar
joelpittet committed
105
106
107
=======================
What are the files for?
=======================
108

109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
- basic.info.yml
  Provide informations about the theme, like regions and libraries.
- block.html.twig
  Template to edit the blocks.
- comment.html.twig
  Template to edit the comments.
- node.html.twig
  Template to edit the nodes (in content).
- page.html.twig
  Template to edit the page.
- basic.theme
  Used to modify Drupal's default behavior before outputting HTML through the
  templates.
- theme-settings.php
  Provides additional settings in the theme settings page.

125

126
============
joelpittet's avatar
joelpittet committed
127
In /sass
128
============
SteveK's avatar
SteveK committed
129

130
- layout/layout.scss
131
  Defines the layout of the theme (compiles to css/layout/layout.css)
132
- theme/print.scss
133
  Defines the way the theme looks when printed (compiles to css/theme/print.css)
134
- components/tabs.scss
135
  Styles for the admin tabs (compiles to css/components/tabs.css)
136

137

138
139
140
141
142
============
In /js
============

- modernizr.js
143
144
145
  Modernizr detects HTML and CSS features and applies classes to
  the <html> object you can then reference in your stylesheets. Use the URL at
  the top of the modernizr.js file to customize the features you wish to detect.
146
- selectivizr-min.js
147
148
149
150
  This script will only be loaded for Internet Explorer 8
  through the ie8 theme library. It will provide a JS fallback for CSS :nth-
  child, an important part of the Bourbon Neat grid system, as it is not
  supported in Internet Explorer 8.
151
- build/scripts.js & source/scripts.js
152
  When using Gulp, save files to the
153
154
155
  source folder and a minified version will automatically be saved to the build
  folder. See comments in basic.libraries.yml file to enable the starter
  scripts.js file.
156
157


joelpittet's avatar
joelpittet committed
158
===================
159
Changing the Layout
joelpittet's avatar
joelpittet committed
160
===================
161

joelpittet's avatar
joelpittet committed
162
The layout used in Basic is fairly similar to the Holy Grail method. It has been
163
164
tested on all major browsers including IE (5 to >10), Opera, Firefox, Safari,
and Chrome. The purpose of this method is to have a minimal markup for an ideal
165
display. For accessibility and search engine optimization, the best order to
166
display a page is the following:
167

joelpittet's avatar
joelpittet committed
168
169
170
171
1. Header
2. Content
3. Sidebars
4. Footer
172

173
174
This is how the page template is buit in Basic, and it works in fluid and fixed
layout. Refer to the notes in layout.sass to see how to modify the layout.
175
176


SteveK's avatar
SteveK committed
177
===========================
178
How to Use Gulp with Basic
SteveK's avatar
SteveK committed
179
===========================
180

181
Gulp (https://gulpjs.com/) requires Node.JS to be installed on your machine.
SteveK's avatar
SteveK committed
182
There are various package managers that can handle this for you.
183

SteveK's avatar
SteveK committed
184
https://nodejs.org/download/
185

186
Once Node.JS is installed, go to the root folder of Basic and install your Gulp
SteveK's avatar
SteveK committed
187
packages:
188

SteveK's avatar
SteveK committed
189
190
  npm install

191
192
This will install the neccessary node_modules to run Gulp, including Gulp itself.
Once installed, cd to the root folder of Basic and run Gulp via the command
SteveK's avatar
SteveK committed
193
194
line:

195
  gulp
SteveK's avatar
SteveK committed
196

197
198
This will initialize gulp, compile Sass (as .scss files) to CSS, transpile and 
uglify your JS, and start watching changes to your files. Voilà!
199

200

joelpittet's avatar
joelpittet committed
201
202
203
==============
Updating Basic
==============
204

205
Once you start using Basic, you will massively change it until you reach the
206
point where it has nothing to do with Basic anymore. Unlike Zen, Basic is not
207
208
intended to be use as a base theme for a sub-theme (even though it is possible
to do so). Because of this, it is not necessary to update your theme when a new
209
version of Basic comes out. Always see Basic as a STARTER, and as soon as you
210
start using it, it is not Basic anymore, but your own theme.
211

212
If you didn't rename your theme, but you don't want to be notified when Basic
joelpittet's avatar
joelpittet committed
213
has a new version by the update module, simply delete "project = "basic" in
214
basic.info.yml.
joelpittet's avatar
joelpittet committed
215
216
217
218
219


================
Bugs & Questions
================
220

221
222
Thanks for using Basic, and remember to use the issue queue in drupal.org for
any questions or bug reports:
223
224
225

http://drupal.org/project/issues/basic

joelpittet's avatar
joelpittet committed
226
227

====================
228
Current maintainers:
joelpittet's avatar
joelpittet committed
229
====================
230
231
232
233
234
* Steve Krueger (SteveK)              - https://www.drupal.org/u/stevek
* Leah Marsh (leahtard)               - https://www.drupal.org/u/leahtard
* Joël Pittet (joelpittet)            - https://www.drupal.org/u/joelpittet
* Catherine Winters (CatherineOmega)  - https://www.drupal.org/u/catherineomega
* Johannes Schmidt (johannez)         - https://www.drupal.org/u/johannez
235
* Chuck Kosman (cwkosman)             - https://www.drupal.org/u/cwkosman