There are three main methods of installation. The preferred method is to use NPM (Node Package Manager) to install the source in the node_modules/ directory of your project. This method enables you to compile your application's CSS, JavaScript, and SVGs. It also maintains a dependency link with the {{ this.package.nice }} source.
The other two options involve using distributed stylesheets and scripts via a public CDN. These are linked to the page using <link> and <script> tags.
npm install {{ this.package.name }}Compiled styles and scripts in the /dist folder of the GitHub repository can be imported on the page using a CDN such as JsDelivr. The following global stylesheet link can be copied and pasted into the <head> of your HTML document.
<link href="{{ this.package.cdn.url }}@v{{ this.package.version }}/{{ this.global.dist }}/{{ this.global.entry.styles }}" rel="stylesheet">The following global script source can be copied and pasted before your HTML document's closing </body> tag.
<script src="{{ this.package.cdn.url }}@v{{ this.package.version }}/{{ this.global.dist }}/{{ this.global.entry.scripts }}"></script>You can add SVG icons with the following snippet when the global script source is linked.
<script>
var patterns = new {{ this.global.entry.name }}();
patterns.icons('{{ this.package.cdn.url }}@v{{ this.package.version }}{{ this.global.entry.svgs }}');
</script>The following url is the base url for all distributed files available via a CDN.
{{ this.package.cdn.url }}@v{{ this.package.version }}/dist/
Visit the GitHub repository to browse all distributed files available to the CDN.
There are regular releases to the patterns which follow semantic versioning. You can keep up-to-date with new releases on each repository's releases page.
You may also download an archive of the repository to include in your project; Download v{{ this.package.version }}.zip
You can import all of the Sass modules into a project from the source directory.
@forward '{{ this.package.name }}/src/scss/imports'Or you can import individual Sass modules for any pattern from their respective pattern directory.
@forward '{{ this.package.name }}/src/components/accordion/accordion';Specificity
Most patterns share the same filename for Sass and JavaScript (if used). Specifying that you need to import the Sass file for React (or other) applications may be necessary.
@forward '{{ this.package.name }}/src/components/accordion/_accordion.scss';Importing Tailwindcss is compiled to a Sass file in the src directory and a CSS file in the distribution folder and a CSS file in the dist folder.
@forward 'node_modules/{{ this.package.name }}/src{{ this.global.entry.tailwindsass }}';<link href="{{ this.package.cdn.url }}@v{{ this.package.version }}{{ this.package.version }}{{ this.global.entry.tailwindcss }}" rel="stylesheet">Refer to the Tailwindcss page for more details.
Stylesheets use the url() CSS function for loading external assets such as web fonts, images, and SVGs. By default, it looks for asset directories from one directory up from the distributed stylesheet. This means the directory structure of your application is expected to look like so.
styles/site-default.css
svg/..
However, you can set the path differently using the $cdn variable.
// $cdn: '../'; (default)
$cdn: 'path/to/assets/';To modify, you should place this variable above your @forward rules for Sass files. You can set the CDN to another local path (such as an absolute path), or you can set it to the remote url within the $tokens variable map. This default uses JsDelivr CDN to link the assets from the patterns GitHub repository and the tag of the installed version.
@use 'config/tokens' as *;
$cdn: map-get($tokens, 'cdn');These are the default paths to the different asset types within the asset folder. Uncomment and set it to override their defaults.
$path-to-fonts: 'fonts/';
$path-to-images: 'images/';
$path-to-svg: 'svg/';It would help if you used this for Webpack projects using the css-loader (such as React and projects scaffolded using create-react-app). Webpack will try to import the asset into your distributed stylesheet. Assuming you don't want to change the $cdn variable. In that case, you can disable the url / image-set functions handling with a boolean.
You can add the string node_modules/{{ this.package.name }}/src to your "resolve" or "include" paths which will allow you to write the shorthand path.
@forward 'components/accordion/accordion';or
@forward 'components/accordion/_accordion.scss';Below is an example of the Sass includePaths option, an array of path strings that attempt to resolve your @import (deprecated), @forward, or @use rules if Sass can't find files locally.
Sass.render({
file: './src/scss/default.scss',
outFile: 'site-default.css',
includePaths: [
`${process.env.PWD}/node_modules`,
`${process.env.PWD}/node_modules/{{ this.package.name }}/src`
]
}, (err, result) => {
Fs.writeFile(`${process.env.PWD}/dist/styles/default.css`, result.css);
}
});Similar to the the gulp-sass includePaths option.
gulp.task('sass', () => {
return gulp.src('./sass/**/*.scss')
.pipe(sass.({includePaths: [
`${process.env.PWD}/node_modules`,
`${process.env.PWD}/node_modules/{{ this.package.name }}/src`
]})).pipe(gulp.dest('./css'));
});LibSass and Dart Sass also support using the SASS_PATH environment variable. This variable is valid when configuring a React Application using React Scripts (Create React App).
SASS_PATH=node_modules:node_modules/{{ this.package.name }}/src
You can configure Webpack with the resolve modules option.
module.exports = {
//...
resolve: {
modules: [
`${process.env.PWD}/node_modules`,
`${process.env.PWD}/node_modules/{{ this.package.name }}/src`
]
}
};Below is an example for a Nuxt.js application configuration (which uses Webpack under the hood).
const config = {
css: ['@/assets/scss/main.scss'],
styleResources: {
scss: [
'@/assets/scss/_variables.scss',
]
},
buildModules: [
'@nuxtjs/style-resources',
],
build: {
extend(config) {
config.resolve.modules.push(`${process.env.PWD}/node_modules`);
config.resolve.modules.push(`${process.env.PWD}/node_modules/{{ this.package.name }}`);
}
}
}
export default config;The JavaScript source uses ES Modules. Import all JavaScript dependencies from the source and execute them individually.
import Main from '{{ this.package.name }}/src/js/default'
Main.accordion();Or you can import individual ES Modules for any pattern from their respective pattern directory and initialize them. Individual imports enable you to customize JavaScript behavior.
import Accordion from '{{ this.package.name }}/src/components/accordion/accordion';
new Accordion();Using Rollup.js, an IFFE function with all JavaScript modules is distributed in a single global script. You may import this script and initialize modules individually.
<script src="{{ this.package.cdn.url }}@v{{ this.package.version }}/{{ this.global.dist }}/{{ this.global.entry.scripts }}"></script>
<script type="text/javascript">
var patterns = new {{ this.global.entry.name }}();
patterns.accordion();
</script>The main JavaScript import file in the source will show how each module needs to be initialized if it isn't specified in the individual pattern's documentation.
You can add the SVG icon sprite to the DOM several ways. The first example is from the main script source.
import Main from '{{ this.package.name }}/src/js/default'
Main.icons('path/to{{ this.global.entry.svgs }}');Or by using the Patterns Script Utility which is a dependency of the {{ this.package.nice }}.
import Icons from '@nycopportunity/patterns-scripts/src/icons/icons'
new Icons('path/to{{ this.global.entry.svgs }}');Or from the distributed global script.
<script>
var patterns = new {{ this.global.entry.name }}();
patterns.icons('path/to{{ this.global.entry.svgs }}');
</script>More details can be found on the SVGs page.
The {{ this.package.nice }} was created using the NYC Opportunity UI Patterns Framework. You can find demonstrations of different integrations there for reference.