README

=====================
Introduction to Basic
=====================

Basic boasts a clean HTML5 structure with extensible CSS classes and IDs for
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,
SASS-based grid system (Bourbon Neat).

Basic's goal is to provide themers the building blocks needed to get their
designs up and running quickly and simply.

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

Less code spam, more ham.


============
Installation
============

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
packages are included via 'npm install'
  - Bourbon (http://bourbon.io/)
  - Bourbon Neat (http://neat.bourbon.io/)

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

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.

  - 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.
  - Run the provided drush install script: $ drush basic-install
  - 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).
  - 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:

  - Rename the theme folder to 'mytheme'
  - Rename basic.info.yml to mytheme.info.yml
  - edit basic.info.yml and change the name, description, project (can be
    deleted), and change all other instances of 'basic' to 'mytheme'
  - Rename basic.libraries.yml to mytheme.libraries.yml
  - Rename basic.theme to mytheme.theme
  - in basic.theme, change each instance of 'basic' to 'mytheme'
  - Rename config/schema/basic.schema.yml to mytheme.schema.yml
  - Rename each file in config/install from block.block.basic_tools.yml (for
    example) to block.block.mytheme_tools.yml
  - Every file in config/install, change each instance of 'basic' to
    'mytheme'
  - 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
    'mytheme'
  - In templates/status-messages.html.twig, change each instance of 'basic' to
    'mytheme'

  When renaming, remember the following:
  - 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
    these instances will cause Basic to break in unpredictable ways.
  - 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!


============================
How to compile Sass in Basic
============================

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

Install node-sass:

  npm install node-sass -g

If you don't like Gulp, or would just prefer to use Sass' internal watch
functionality, simply cd into your theme directory and run:

  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


=======================
What are the files for?
=======================

- 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.


============
In /sass
============

- layout/layout.scss
  Defines the layout of the theme (compiles to css/layout/layout.css)
- theme/print.scss
  Defines the way the theme looks when printed (compiles to css/theme/print.css)
- components/tabs.scss
  Styles for the admin tabs (compiles to css/components/tabs.css)


============
In /js
============

- modernizr.js
  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.
- selectivizr-min.js
  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.
- build/scripts.js & source/scripts.js
  When using Gulp, save files to the
  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.


===================
Changing the Layout
===================

The layout used in Basic is fairly similar to the Holy Grail method. It has been
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
display. For accessibility and search engine optimization, the best order to
display a page is the following:

1. Header
2. Content
3. Sidebars
4. Footer

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.


===========================
How to Use Gulp with Basic
===========================

Gulp (https://gulpjs.com/) requires Node.JS to be installed on your machine.
There are various package managers that can handle this for you.

https://nodejs.org/download/

Once Node.JS is installed, go to the root folder of Basic and install your Gulp
packages:

  npm install

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
line:

  gulp

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


==============
Updating Basic
==============

Once you start using Basic, you will massively change it until you reach the
point where it has nothing to do with Basic anymore. Unlike Zen, Basic is not
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
version of Basic comes out. Always see Basic as a STARTER, and as soon as you
start using it, it is not Basic anymore, but your own theme.

If you didn't rename your theme, but you don't want to be notified when Basic
has a new version by the update module, simply delete "project = "basic" in
basic.info.yml.


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

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

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


====================
Current maintainers:
====================
* 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
* Chuck Kosman (cwkosman)             - https://www.drupal.org/u/cwkosman
btw / btw_theme

Maintainers

Details

README
