Update documentation and add new generic starterkit

Issue #2852156 by markcarver: Move "overrides" source files and generated CSS to separate project
parent e8516c45
...@@ -16,32 +16,32 @@ Below are some topics to help get you started using the [Drupal Bootstrap] base ...@@ -16,32 +16,32 @@ Below are some topics to help get you started using the [Drupal Bootstrap] base
theme. They are ordered based on the level one typically progresses while using theme. They are ordered based on the level one typically progresses while using
a base theme like this. a base theme like this.
#### @link contributing Contributing @endlink #### [Contributing](<!-- @url contributing -->)
#### @link getting_started Getting Started @endlink #### [Getting Started](<!-- @url getting_started -->)
#### @link theme_settings Theme Settings @endlink #### [Theme Settings](<!-- @url theme_settings -->)
#### @link sub_theming Sub-Theming @endlink #### [Sub-Theming](<!-- @url sub_theming -->)
- @link sub_theming_cdn CDN Starterkit @endlink - [CDN Starterkit](<!-- @url sub_theming_cdn -->)
- @link sub_theming_less Less Starterkit @endlink - [Less Starterkit](<!-- @url sub_theming_less -->)
- @link sub_theming_sass Sass Starterkit @endlink - [Sass Starterkit](<!-- @url sub_theming_sass -->)
#### @link templates Templates @endlink #### [Templates](<!-- @url templates -->)
#### @link utility Utilities @endlink #### [Utilities](<!-- @url utility -->)
#### @link plugins Plugin System @endlink #### [Plugin System](<!-- @url plugins -->)
- @link plugins_alter @BootstrapAlter @endlink - [@BootstrapAlter](<!-- @url plugins_alter -->)
- @link plugins_form @BootstrapForm @endlink - [@BootstrapForm](<!-- @url plugins_form -->)
- @link plugins_preprocess @BootstrapPreprocess @endlink - [@BootstrapPreprocess](<!-- @url plugins_preprocess -->)
- @link plugins_prerender @BootstrapPrerender @endlink - [@BootstrapPrerender](<!-- @url plugins_prerender -->)
- @link plugins_process @BootstrapProcess @endlink - [@BootstrapProcess](<!-- @url plugins_process -->)
- @link plugins_provider @BootstrapProvider @endlink - [@BootstrapProvider](<!-- @url plugins_provider -->)
- @link plugins_setting @BootstrapSetting @endlink - [@BootstrapSetting](<!-- @url plugins_setting -->)
- @link plugins_update @BootstrapUpdate @endlink - [@BootstrapUpdate](<!-- @url plugins_update -->)
#### @link maintainers Project Maintainers @endlink #### [Project Maintainers](<!-- @url maintainers -->)
--- ---
...@@ -52,20 +52,28 @@ documentation. For clarity, we will always attempt to use this word verbosely ...@@ -52,20 +52,28 @@ documentation. For clarity, we will always attempt to use this word verbosely
in one of the following ways: in one of the following ways:
- **[Drupal Bootstrap]** refers to the Drupal base theme project. - **[Drupal Bootstrap]** refers to the Drupal base theme project.
- **[Bootstrap Framework](https://getbootstrap.com/docs/3.4/)** refers to the external - **[Bootstrap Framework](https://getbootstrap.com/docs/3.4/)** refers to the
front end framework. external front end framework.
- **[drupal_bootstrap](https://api.drupal.org/apis/drupal_bootstrap)** refers - **[drupal_bootstrap](https://api.drupal.org/apis/drupal_bootstrap)** refers
to Drupal's bootstrapping process or phase. to Drupal's bootstrapping process or phase.
When referring to files inside the [Drupal Bootstrap] project directory, they When referring to files inside the [Drupal Bootstrap] project directory, they
will always start with `./bootstrap` and continue to specify the full path to will always start with `./themes/bootstrap` and continue to specify the full
the file or directory inside it. For example, the file that is responsible for path to the file or directory inside it. The dot (`.`) is representative of
displaying the text on this page is located at `./bootstrap/docs/README.md`. your Drupal installation's `DOCROOT` folder. For example, the file that is
responsible for displaying the text on this page is located at
`./themes/bootstrap/docs/README.md`.
When referring to files inside a sub-theme, they will always start with When referring to files inside a sub-theme, they will always start with
`./THEMENAME/`, where `THEMENAME` is the machine name of your sub-theme. They `./themes/THEMENAME/`, where `THEMENAME` is the machine name of your sub-theme.
will continue to specify the full path to the file or directory inside it. For They will continue to specify the full path to the file or directory inside it.
example, the primary file Drupal uses to determine if a theme For example, the primary file Drupal uses to determine if a theme exists is:
exists is: `./THEMENAME/THEMENAME.info.yml`. `./themes/THEMENAME/THEMENAME.info.yml`.
{.alert.alert-info} **NOTE:** It is common practice to place projects found on
Drupal.org inside a sub-folder named `contrib` and custom/site-specific code
inside a `custom` folder. If your site is set up this way, please adjust all
paths accordingly (i.e. `./themes/contrib/bootstrap` and
`./themes/custom/THEMENAME`).
[Drupal Bootstrap]: https://www.drupal.org/project/bootstrap [Drupal Bootstrap]: https://www.drupal.org/project/bootstrap
This diff is collapsed.
...@@ -10,7 +10,7 @@ stored and at what point in the process they are accessed. ...@@ -10,7 +10,7 @@ stored and at what point in the process they are accessed.
There are essentially four places where theme settings do or could reside: There are essentially four places where theme settings do or could reside:
1. **Install Config** - `./THEMENAME/config/install/THEMENAME.settings.yml` 1. **Install Config** - `./themes/THEMENAME/config/install/THEMENAME.settings.yml`
This is the install config only. They will only be set upon the initial This is the install config only. They will only be set upon the initial
installation of a theme. This is **not** like previous Drupal implementations installation of a theme. This is **not** like previous Drupal implementations
where changes made here are reflected after a cache rebuild. The only way where changes made here are reflected after a cache rebuild. The only way
......
...@@ -44,7 +44,7 @@ themes and are automatically supported out-of-the-box. ...@@ -44,7 +44,7 @@ themes and are automatically supported out-of-the-box.
Once a base theme has implemented an alter hook, like mentioned above, all Once a base theme has implemented an alter hook, like mentioned above, all
subsequent sub-themes will have the ability to implement a plugin for that subsequent sub-themes will have the ability to implement a plugin for that
alter hook directly. All you have to do is simply create the plugin file in alter hook directly. All you have to do is simply create the plugin file in
`./THEMENAME/src/Plugin/Alter`. No need to implement any code in `./themes/THEMENAME/src/Plugin/Alter`. No need to implement any code in
`THEMENAME.theme`: `THEMENAME.theme`:
- `hook_bootstrap_colorize_text_alter` - `hook_bootstrap_colorize_text_alter`
...@@ -85,7 +85,7 @@ how to add a library from your sub-theme to every page request. ...@@ -85,7 +85,7 @@ how to add a library from your sub-theme to every page request.
Replace all following instances of `THEMENAME` with the actual machine name of Replace all following instances of `THEMENAME` with the actual machine name of
your sub-theme. your sub-theme.
Create a file at `./THEMENAME/src/Plugin/Alter/PageAttachments.php` with the Create a file at `./themes/THEMENAME/src/Plugin/Alter/PageAttachments.php` with the
following contents: following contents:
```php ```php
......
...@@ -16,7 +16,7 @@ how to remove `#input_group_button` from `search_block_form`. ...@@ -16,7 +16,7 @@ how to remove `#input_group_button` from `search_block_form`.
Replace all following instances of `THEMENAME` with the actual machine name of Replace all following instances of `THEMENAME` with the actual machine name of
your sub-theme. your sub-theme.
Create a file at `./THEMENAME/src/Plugin/Form/SearchBlockForm.php` with the Create a file at `./themes/THEMENAME/src/Plugin/Form/SearchBlockForm.php` with the
following contents: following contents:
```php ```php
......
...@@ -17,7 +17,7 @@ under certain conditions. ...@@ -17,7 +17,7 @@ under certain conditions.
Replace all following instances of `THEMENAME` with the actual machine name of Replace all following instances of `THEMENAME` with the actual machine name of
your sub-theme. your sub-theme.
Create a file at `./THEMENAME/src/Plugin/Preprocess/Page.php` with the Create a file at `./themes/THEMENAME/src/Plugin/Preprocess/Page.php` with the
following contents: following contents:
```php ```php
......
...@@ -33,7 +33,7 @@ $build['my_button'] = [ ...@@ -33,7 +33,7 @@ $build['my_button'] = [
Replace all following instances of `THEMENAME` with the actual machine name of Replace all following instances of `THEMENAME` with the actual machine name of
your sub-theme. your sub-theme.
Create a file at `./THEMENAME/src/Plugin/Prerender/Link.php` with the Create a file at `./themes/THEMENAME/src/Plugin/Prerender/Link.php` with the
following contents: following contents:
```php ```php
......
...@@ -25,7 +25,7 @@ for the "format tips" section. ...@@ -25,7 +25,7 @@ for the "format tips" section.
Replace all following instances of `THEMENAME` with the actual machine name of Replace all following instances of `THEMENAME` with the actual machine name of
your sub-theme. your sub-theme.
Create a file at `./THEMENAME/src/Plugin/Process/TextFormat.php` with the Create a file at `./themes/THEMENAME/src/Plugin/Process/TextFormat.php` with the
following contents: following contents:
```php ```php
......
...@@ -26,7 +26,7 @@ recommended that you read the accompanying PHP based documentation on the ...@@ -26,7 +26,7 @@ recommended that you read the accompanying PHP based documentation on the
classes and methods responsible for actually retrieving, parsing and caching classes and methods responsible for actually retrieving, parsing and caching
the data from the CDN's API. the data from the CDN's API.
Create a file at `./THEMENAME/src/Plugin/Provider/MyCdn.php` with the Create a file at `./themes/THEMENAME/src/Plugin/Provider/MyCdn.php` with the
following contents: following contents:
```php ```php
......
...@@ -33,14 +33,14 @@ to leverage the powerful inheritance capabilities of PHP class instances. ...@@ -33,14 +33,14 @@ to leverage the powerful inheritance capabilities of PHP class instances.
All of these plugins can be found in the following directories and are All of these plugins can be found in the following directories and are
discussed, in length, below in their respective sub-topics: discussed, in length, below in their respective sub-topics:
- `./bootstrap/src/Plugin/Alter` - `./themes/bootstrap/src/Plugin/Alter`
- `./bootstrap/src/Plugin/Form` - `./themes/bootstrap/src/Plugin/Form`
- `./bootstrap/src/Plugin/Preprocess` - `./themes/bootstrap/src/Plugin/Preprocess`
- `./bootstrap/src/Plugin/Prerender` - `./themes/bootstrap/src/Plugin/Prerender`
- `./bootstrap/src/Plugin/Process` - `./themes/bootstrap/src/Plugin/Process`
- `./bootstrap/src/Plugin/Provider` - `./themes/bootstrap/src/Plugin/Provider`
- `./bootstrap/src/Plugin/Setting` - `./themes/bootstrap/src/Plugin/Setting`
- `./bootstrap/src/Plugin/Update` - `./themes/bootstrap/src/Plugin/Update`
While sub-themes are not required to do so, they can easily emulate this same While sub-themes are not required to do so, they can easily emulate this same
type of file structure/workflow and take advantage of this base theme's unique type of file structure/workflow and take advantage of this base theme's unique
......
...@@ -18,7 +18,7 @@ Replace all of the following instances of `THEMENAME` with the actual machine ...@@ -18,7 +18,7 @@ Replace all of the following instances of `THEMENAME` with the actual machine
name of your sub-theme. name of your sub-theme.
Create a file at Create a file at
`./THEMENAME/src/Plugin/Setting/THEMENAME/Accessibility/SkipLink.php` `./themes/THEMENAME/src/Plugin/Setting/THEMENAME/Accessibility/SkipLink.php`
with the following contents: with the following contents:
```php ```php
......
...@@ -20,12 +20,13 @@ function _find_autoloader($dir) { ...@@ -20,12 +20,13 @@ function _find_autoloader($dir) {
else if (empty($dir) || $dir === DIRECTORY_SEPARATOR) { else if (empty($dir) || $dir === DIRECTORY_SEPARATOR) {
return FALSE; return FALSE;
} }
return _find_autoloader(realpath("$dir/..")); return _find_autoloader(dirname($dir));
} }
$autoloader = _find_autoloader(empty($_SERVER['PWD']) ? getcwd() : $_SERVER['PWD']); $autoloader = _find_autoloader(empty($_SERVER['PWD']) ? getcwd() : $_SERVER['PWD']);
if (!$autoloader || !class_exists('\Drupal\Core\DrupalKernel')) { if (!$autoloader || !class_exists('\Drupal\Core\DrupalKernel')) {
throw new \Exception("This script must be invoked inside a Drupal 8 environment. Unable to continue."); print "This script must be invoked inside a Drupal 8 environment. Unable to continue.\n";
exit();
} }
// Create a DrupalKernel instance. // Create a DrupalKernel instance.
......
framework:
css:
theme:
css/style.css: {}
# Uncomment for LESS source JavaScript files.
# js:
# bootstrap/js/affix.js: {}
# bootstrap/js/alert.js: {}
# bootstrap/js/button.js: {}
# bootstrap/js/carousel.js: {}
# bootstrap/js/collapse.js: {}
# bootstrap/js/dropdown.js: {}
# bootstrap/js/modal.js: {}
# bootstrap/js/tooltip.js: {}
# bootstrap/js/popover.js: {}
# bootstrap/js/scrollspy.js: {}
# bootstrap/js/tab.js: {}
# bootstrap/js/transition.js: {}
# Uncomment for SASS source JavaScript files.
# js:
# bootstrap/assets/javascripts/bootstrap/affix.js: {}
# bootstrap/assets/javascripts/bootstrap/alert.js: {}
# bootstrap/assets/javascripts/bootstrap/button.js: {}
# bootstrap/assets/javascripts/bootstrap/carousel.js: {}
# bootstrap/assets/javascripts/bootstrap/collapse.js: {}
# bootstrap/assets/javascripts/bootstrap/dropdown.js: {}
# bootstrap/assets/javascripts/bootstrap/modal.js: {}
# bootstrap/assets/javascripts/bootstrap/tooltip.js: {}
# bootstrap/assets/javascripts/bootstrap/popover.js: {}
# bootstrap/assets/javascripts/bootstrap/scrollspy.js: {}
# bootstrap/assets/javascripts/bootstrap/tab.js: {}
# bootstrap/assets/javascripts/bootstrap/transition.js: {}
core: 8.x
type: theme
base theme: bootstrap
name: 'THEMETITLE'
description: 'A Drupal Bootstrap 3 based sub-theme.'
package: 'Bootstrap'
regions:
navigation: 'Navigation'
navigation_collapsible: 'Navigation (Collapsible)'
header: 'Top Bar'
highlighted: 'Highlighted'
help: 'Help'
content: 'Content'
sidebar_first: 'Primary'
sidebar_second: 'Secondary'
footer: 'Footer'
page_top: 'Page top'
page_bottom: 'Page bottom'
libraries-extend:
bootstrap/framework:
- THEMENAME/framework
<?php
/**
* @file
* Bootstrap sub-theme.
*
* Place your custom PHP code in this file.
*/
# Default settings should not be located here. This file is only used to
# install initial setting values. If your theme is the one that introduces a
# new theme setting, it should use the Drupal Bootstrap base theme's
# @BootstrapSetting annotation discovery process. This ensures that sub-theme
# settings are inherited from base themes themes properly and to determine when
# a setting should be saved to config as "overridden".
#
# @see \Drupal\bootstrap\Plugin\SettingBase
# @see \Drupal\bootstrap\Plugin\SettingInterface
# @see \Drupal\bootstrap\Plugin\SettingManager
# @see \Drupal\bootstrap\Plugin\Form\SystemThemeSettings
# @see \Drupal\bootstrap\ThemeSettings
# This file cannot be empty, so install an initial empty array for "schemas".
# @see https://www.drupal.org/node/2813829
schemas: []
# Disable the CDN provider so compiled source files can be used.
#cdn_provider: ''
# Schema for the theme setting configuration file of the THEMETITLE theme.
THEMENAME.settings:
type: theme_settings
label: 'THEMETITLE settings'
/**
* If using a CSS pre-processor, tell it to overwrite this file. If not, place
* your custom CSS modifications here.
*/
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><path fill="#EE0000" d="M0,7.562l1.114-3.438c2.565,0.906,4.43,1.688,5.59,2.35C6.398,3.553,6.237,1.544,6.22,0.447h3.511 c-0.05,1.597-0.234,3.6-0.558,6.003c1.664-0.838,3.566-1.613,5.714-2.325L16,7.562c-2.05,0.678-4.06,1.131-6.028,1.356 c0.984,0.856,2.372,2.381,4.166,4.575l-2.906,2.059c-0.935-1.274-2.041-3.009-3.316-5.206c-1.194,2.275-2.244,4.013-3.147,5.206 l-2.856-2.059c1.872-2.307,3.211-3.832,4.017-4.575C3.849,8.516,1.872,8.062,0,7.562"/></svg>
<svg
version="1.1"
xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
width="32px" height="32px"
viewBox="0 0 32 32" preserveAspectRatio="none">
<g>
<image width="32" height="32" xlink:href="data:image/png;base64,
iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJ
bWFnZVJlYWR5ccllPAAAAohJREFUeNrEl1tIVGEQx12L0BQjoXwpoRfxIQUJuhAIvVRLIRQELYj1
oKDgpQgVNQhBChQfLFDLoovVS0RQYuqLPUgFgTcQia5CSBBERUiKuv0+GGGJPd/l7Nkc+DNn98w3
8/++mXNmTigajaasp4T8Ejhx+GIWavOTkbaviRBITWBtIbgDkfT1InAGHAGDkNj2X1NAwFLU3ZgN
fATnSMezpBIgcAaqWRBPHoFLEJlNVgpWRC943D8FJiDaA3IDOQEc5aNK5Ocou3vDf3u5HgFbNEu/
gzrs7/smQKAa1BWQEfN3L06ruFcmdWCSa+A8a1acUkCAetTVf4IrqeReBIf3pPhMojbR41QDBDiO
atc4LRU9ZVk7FXKaZgLyhus2OExbS6FDAV+OV5jxTqAa7DQ4e4qzTegiBwKZoFFLAKdqZ+UGR8Pk
vwu9A7i+AU8TY6vuBNTjtcvgJB0nJyGhCvAgeO9AIBsc0hHYb+GkGDyGxG1ITHIdlmfeVop1BAoc
HJ2FxENIqBOodVhXoCOw3TGnEfVCgsQDrmcc0uBJYNVHR20S3R/EPDDvw0c+p6AK94Wl/aKOwLTP
uSIPfAHLFrYfdAReJzBZ2abvpY7ABHjrg8AcyAEbDXZL4LknAapZGdxyDD4vpPdZ2A7JC0zbC3pl
R7bSJ70+YjFNtVoNJNKObQbMcXAA7AFjhhGvA6INVvMAhgOoBkNwNQsck5Z8wxB8wGuQ9VwEiQ7U
BSmcWPkGOiXnv2QS3q0Jru6rCWrZ71BaKH0/JLXxCmd/+F8RuKkJ/gO0YNsd6IcJgcPSfI56mLxT
3RJcJ/jnoD9MNsg3oZobcqWxqGf/J/gkdTFJ4N9J/zoOSv4KMAC++teHNUg1rQAAAABJRU5ErkJg
gg==
"/>
</g>
</svg>
This directory is used to implement various Bootstrap annotated plugins.
Please refer to the [Plugin System](<!-- @url plugins -->) topic for more info.
This directory is used to implement various core, contrib, Bootstrap and custom
templates.
Please refer to the [Templates](<!-- @url templates -->) topic for more info.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment