diff --git a/README.txt b/README.txt index 7da6bcb..829404d 100644 --- a/README.txt +++ b/README.txt @@ -1,98 +1,120 @@ -======================================== ZURB FOUNDATION 6 - DRUPAL 8 RELEASE -======================================== +==================================== Getting Started --------------- -At the time of this writing, Twig is integrated into Drupal 8 core but a lot of theme function / render function cleanup remains. We are working diligently to keep up with the changes -as Drupal 8 development progresses towards a release. +At the time of this writing, Twig is integrated into Drupal 8 core but a lot of +theme function / render function cleanup remains. We are working diligently to +keep up with Drupal 8 and Foundation 6 development. -Foundation Docs ---------------- - -Examples of Foundation markup can be found here: http://foundation.zurb.com/docs/ - -Dependencies ------------- - -Zurb Foundation theme dependencies are managed with a ruby Gemfile. This manages bundle dependencies and their versions for Foundation core and addons. When you run 'compass install foundation' against this -directory, the Gemfile is adhered to and Foundation is built accordingly. - -The reason there is a Gemfile instead of a Composer file is because the Foundation project is built with Compass. This may change in the future to be more in line with Drupal 8 / Symfony way of managing dependencies. +See STARTER/README.txt for how to create a starter theme using this base theme. -The Gemfile.lock file is a generated result of installing from the Gemfile, recording each pacakge and version used to build the project. +Zurb Foundation 6 has switched from compass to bower, npm and gulp for +dependency management and generating CSS from scss files. -Installing Ruby +Foundation Docs --------------- -Follow the guides at this URL for your applicable operating system: +Examples of Foundation markup can be found here: +http://foundation.zurb.com/docs/ +Drupal-specific zurb_foundation theme documentation is here: +https://www.drupal.org/node/1948260 - - http://www.ruby-lang.org/en/downloads/ +Installing npm and bower +------------------------ -There is a one click installer for Windows. If you're on OSX, we highly recommend using Homebrew to install Ruby. +NodeJS with included node package manager (npm) is required to build the site +dependencies. Download from https://nodejs.org/ . Mac OS X users can install +nodejs with homebrew ( http://brew.sh/ ) for streamlined version updates. -You will also want to install RVM, a 'version manager' for Ruby - particularly if you are on OSX which ships with Ruby 1.8.x by default. +To install bower globally: - - https://rvm.io/ +`npm install -g bower` -Installing RubyGems -------------------- +If all went well during installation, you should be able to type this at +the command line, from inside the theme directory: -RubyGems comes with RVM (above). If all went well during installation, you should be able to type this at the command line: +`npm install` +`bower install` -`gem list` +This will install the latest versions of Zurb Foundation and its interaction +library, motion-ui, into the theme. -This should list the local gems currently installed. From here, you should be able to do the following: +Dependencies +------------ -`gem install zurb-foundation` -`gem install compass` +After everything is installed, Zurb Foundation theme dependencies are managed +with bower.json, composer.json, and package.json . A hidden override file, +.bowerrc , prevents a redundant copy of jQuery from being added to the theme. -This will install the latest versions of Zurb Foundation gem and Compass gems required for building the Foundation core. +This manages dependencies and their versions for Foundation core and addons. -You can also specify gem versions with the command above. If the Gemfile in this theme changes and supports newer versions of the Zurb Foundation gem, you can install and target that specific release with: +If you need to generate a theme with a different incremental version of +foundation or motion-ui, edit these version strings in bower.json: -`gem install zurb-foundation -v x.x.x` + "dependencies": { + "foundation-sites": "~6.2.1", + "motion-ui": "~1.2.2" + }, -Where x.x.x is the version number you want to install. +Then running `npm start` will copy the new files from dist to the production +directories. Installing this theme --------------------- -To install Zurb Foundation, copy zurb-foundation into the root-level themes directory, or into a sites/*/themes directory, -as zurb_foundation. The naming difference is important when using a sub-theme to include Zurb Foundation SASS files. +To install Zurb Foundation, copy zurb_foundation into the root-level themes +directory, or into a sites/*/themes directory, as zurb_foundation. + +Once copied, after npm and bower have run their installers, you can enable +the theme by visiting "/admin/appearance" and clicking +"Install and set as default" under the ZURB Foundation block. -Once copied, you can enable the theme by visiting "/admin/appearance" and clicking "Install and set as default" under -the ZURB Foundation block. +Once installed, you can visit /admin/appearance/settings/zurb_foundation to +configure the theme. -Once installed, you can visit /admin/appearance/settings/zurb_foundation to configure the theme. +If you do not want to develop a child theme, use `npm start` to copy dist files +into the appropriate css and js folders, then it will watch /scss for changes. +Press ctrl-C to break the watcher. (Note, it is recommended to build a child +theme for better maintainability) How to Use Zurb Foundation -------------------------- # Creating a Sub-theme -To create a sub-theme, simply run the Drush command "drush fst sub_theme", where "sub_theme" is the desired machine name -of your sub-theme. Once a sub-theme is created, you can enable it at /admin/appearance/settings/zurb_foundation. Detailed -sub-theme documentation can be found in the README.txt file included in your new sub-theme. +To create a sub-theme automatically, simply run the Drush command +`drush fst sub_theme`, where "sub_theme" is the desired machine name of your +sub-theme. Once a sub-theme is created, you can enable it at /admin/appearance . + +Detailed sub-theme documentation can be found in the README.txt file included in +your new sub-theme (distributed inside STARTERKIT). + +The code controlling drush is at /inc/zurb_foundation.drush.inc . # Theme Settings -At /admin/appearance/settings/zurb_foundation, there are a variety fo Zurb Foundation specific settings you can use to -configure and enable theme features. There are descriptions of each setting and setting group on that page. +At /admin/appearance/settings/zurb_foundation, there are a variety of Zurb +Foundation specific settings you can use to configure and enable theme features. +There are descriptions of each setting and setting group on that page. -The most popular feature by far is the Top Bar, which can be enabled under "FOUNDATION TOP BAR". This setting will theme -the Drupal-provided "Main Menu" as a Foundation Top Bar, which can be stickied to the top of a page and supports deep menu -nesting. +The most popular feature by far is the Top Bar, which can be enabled under +"FOUNDATION TOP BAR". This setting will theme the Drupal-provided "Main Menu" as +a Foundation Top Bar, which can be stickied to the top of a page and supports +deep menu nesting. # The Off Canvas and Meta Header Regions -Zurb Foundation for Drupal 8 provides a few new regions compared to the Drupal 7 branches. +Zurb Foundation for Drupal 8 provides some new regions compared to the Drupal 7 +branches. -There are now two off canvas regions, left_off_canvas and right_off_canvas, that can be used to display content off screen. -The most common use for this is menus, and as such we've worked to theme any menu block placed in an off canvas region -using the appropriate Foundation styles. Nesting is supported, but the parent menu link will be used as a button to -move to the next menu level, and cannot also link to a page. Here's an example menu structure for this: +There are now two off canvas regions, left_off_canvas and right_off_canvas, that +can be used to display content off screen. The most common use for this is +menus, and as such we've worked to theme any menu block placed in an off canvas +region using the appropriate Foundation styles. Nesting is supported, but the +parent menu link will be used as a button to move to the next menu level, and +cannot also link to a page. Here's an example menu structure for this: - Main () - Information (#) @@ -103,13 +125,28 @@ move to the next menu level, and cannot also link to a page. Here's an example m ---- Portland (/locations/portland) - Your Account (/user) -In this example, the menu links at the top of a new tree (Information, Locations) will simply open up a new menu level. +In this example, the menu links at the top of a new tree (Information, +Locations) will simply open up a new menu level. To expand an off canvas region, simply create a content block with HTML like: - "" +"" -More examples of this can be seen at http://foundation.zurb.com/sites/docs/off-canvas.html +More examples of this can be seen at: +http://foundation.zurb.com/sites/docs/off-canvas.html -Lastly, we also provide a Meta Header region, which can be used to place blocks above all other page regions. This is -most useful for the Main Menu block, which can be then rendered as a Top Bar. \ No newline at end of file +Lastly, we also provide a Meta Header region, which can be used to place blocks +above all other page regions. This is most useful for the Main Menu block, +which can be then rendered as a Top Bar. + +Developer Notes +--------------- + +This branch is still in active development. Foundation 6 replaced grunt scripts +with gulp. See STARTER/README.txt for more info on how to work with npm and gulp +to compile sass in your child theme. + +Problems? Search the issue queue for help here: +https://www.drupal.org/project/issues/zurb_foundation?status=All&categories=All diff --git a/STARTER/README.txt b/STARTER/README.txt index 3e32dbd..46ab0bd 100644 --- a/STARTER/README.txt +++ b/STARTER/README.txt @@ -1,5 +1,5 @@ -BUILD A THEME WITH ZURB FOUNDATION ----------------------------------- +BUILD A CHILD THEME WITH ZURB FOUNDATION +---------------------------------------- The base Foundation theme is designed to be easily extended by its sub-themes. You shouldn't modify any of the CSS or PHP files in the zurb_foundation/ folder; @@ -14,11 +14,23 @@ http://foundation.zurb.com/docs/faq.php or use the script in the starter template.php THEMENAME_preprocess_html function. *** IMPORTANT NOTE *** -* * After adding a new theme in Drupal 8, you'll need to clear the theme registry's -* cache, which you can do by clearing all cache in the UI or running "drush cr", +* cache, which you can do by clearing all cache in the UI or running `drush cr` , * if you have Drush installed. +Automatic drush sub-theme setup +------------------------------- + +To create a sub-theme, simply run the Drush command `drush fst sub_theme`, where +"sub_theme" is the desired machine name of your sub-theme. Once a sub-theme is +created, you can enable it at /admin/appearance . + +Then follow step 6 below to generate the necessary Foundation files that are not +included in the repository by default. + +Manual sub-theme setup +---------------------- + 1. Setup the location for your new sub-theme. Copy the STARTER folder out of the zurb_foundation/ folder and rename it to @@ -59,8 +71,9 @@ template.php THEMENAME_preprocess_html function. folder; replace ALL occurrences of "STARTER" with the name of your sub-theme. - Do not forget to update: - gulpfile.js.you will need to update this line: gulp.src('scss/STARTER.scss') + Do not forget to update gulpfile.js. You will need to update this line: + + gulp.src('scss/STARTER.scss') For example, edit foo/foo.theme and foo/theme-settings.php and replace every occurrence of "STARTER" with "foo". @@ -75,18 +88,21 @@ template.php THEMENAME_preprocess_html function. new sub-theme. 6. This theme uses bower and npm. You will need both of those on your machine - as a prerequisite for managing your theme. + as a prerequisite for developing your theme, although once in production npm + and bower are not necessary for general use. - once you have ensured those are installed, run these commands at the root of your sub theme: + Once you have ensured those are installed, run these commands at the root of + your sub theme: - `npm install` - `bower install` - Finally, run `npm start` to run the Sass compiler. It will re-run every time you save a Sass file. + Finally, run `npm start` to run the Sass compiler. It will re-run every time + you save a Sass file. Press Ctrl-C to break out of watching files. Optional steps: - 6. Modify the markup in Foundation core's template files. + 7. Modify the markup in Foundation core theme's template files. If you decide you want to modify any of the .html.twig template files in the zurb_foundation folder, copy them to your sub-theme's folder before @@ -95,9 +111,9 @@ Optional steps: For example, copy zurb_foundation/templates/page.html.twig to THEMENAME/templates/page.html.twig. - 7. Optionally override existing Drupal core *.html.twig templates in your sub-theme. + 8. Optionally override existing Drupal core *.html.twig templates in your sub-theme. - 8. Add custom css and js files to your sub-theme + 9. Add custom css and js files to your sub-theme Rename STARTER.libraries.yml to the name of your sub-theme, un-commenting lines and making name changes as needed.