Skip to main content

Patterns

Installation

There are a few options when integrating the patterns, but using NPM Install is recommended.

$ npm install @nycopportunity/access-patterns

Download

Optionally, you may download an archive of this repository to include in your project.

CDN

You can pick which files in the distribution folder of the repository to use by linking to them through JsDelivr. For example, the link of the v0.1.0 default stylesheet:

https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.1.0/dist/styles/site-default.css

You can include this link in the <head> of your html document.

<link href="https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.1.0/dist/styles/site-default.css" rel="stylesheet">

You can learn more about the different ways to use JsDelivr on it’s feature page. All Components and Objects are also distributed with their own styles and JavaScript dependencies in their corresponding /dist folder. For example, all of the accordion dependencies live in the /dist/components/accordion folder.

Keep in mind, there are regular releases to the patterns which follow semantic versioning. You can follow the new releases on the repository releases page.

The ACCESS NYC main SASS import provides and example of how to set up a stylesheet to cherry-pick individual patterns in a project.

@import 'node_modules/access-nyc-patterns/src/components/accordion/accordion';

All files can be imported directly from the source directory. The exception being Tailwind Utilities, which are compiled to a Sass file in the distribution folder:

@import 'node_modules/access-nyc-patterns/dist/styles/_tailwind.scss';

Asset Paths and CDN

The styles use the url() for loading webfonts, images, and svgs. By default, it is set to look for asset directories one directory up from the distributed stylesheet like so:

styles/site-default.scss
images/..
fonts/..
svg/..

However, you can set the path to a different path that includes all of these files using the $cdn variable.

// $cdn: '../'; (default)
$cdn: 'path/to/assets/';

The CDN can be set to another local path, or, it can be set to the remote url within the $variables map. This default uses jsDelivr to pull the assets from the patterns GitHub repository and the tag of the installed version. ex;

@import 'config/variables';
$cdn: map-get($variables, 'cdn');

These are the default paths to the different asset types within the asset folder. Uncomment and set to override their defaults.

$path-to-fonts: 'fonts/';
$path-to-images: 'images/';
$path-to-svg: 'svg/';

Include Paths

You can add node_modules/access-nyc-patterns/src to your “include” paths which will allow you to write the shorthand path;

@import 'components/accordion/accordion';

For example; the node-sass includePaths option which is array of paths that attempt to resolve your @import declarations.

Sass.render({
    file: './src/scss/site-default.scss',
    outFile: 'site-default.css',
    includePaths: [
      './node_modules',
      './node_modules/access-nyc-patterns/src'
    ]
  }, (err, result) => {
    Fs.writeFile(`./dist/styles/site-default.css`, result.css);
  }
});

Similar to the the gulp-sass includePaths option.

gulp.task('sass', () => {
  return gulp.src('./sass/**/*.scss')
    .pipe(sass.({includePaths: [
      'node_modules',
      'node_modules/access-nyc-patterns/src'
    ]})).pipe(gulp.dest('./css'));
});

The JavaScript source is written as ES6 Modules, and using Rollup.js, individual components with JavaScript dependencies are distributed as CommonJS and IFFE functions. Depending on your project, you can import any of the three. Below are examples of importing only the accordion component and initializing it.

ES6 Component Import

import Accordion from 'src/components/accordion/accordion';
new Accordion();

CommonJS

import Accordion from 'dist/components/accordion/accordion.common';
new Accordion();

IFFE

<script src="dist/components/accordion.iffe.js"></script>
<script type="text/javascript">
  new Accordion();
</script>

Global Pattern Script

You may also import the main ACCESS NYC Patterns script with all of the dependencies in it. This script is exported as an IFFE function so it doesn't need to be compiled but you may want to uglify it. Components must be initialized individually.

<script src="dist/scripts/access-nyc.js"></script>
<script type="text/javascript">
  var access = new AccessNyc();
  access.accordion();
</script>

The main Javascript import file shows how each component needs to be initialized.

The Patterns include a polyfill bundle dist/scripts/polyfill.js using MDN Matches, MDN Closest, MDN Remove, whatwg-fetch and features from the Core JS Standard Libary (a dependency of @babel/preset-env). However, because this bundle includes all required polyfills so it is recommended to build your own polyfill based on your browser coverage requirements.