Planning Center Icons

Development

Scripts

Command	Task
`yarn build`	build all collections, once
`yarn build --collection general`	build specified collection, once
`yarn publish`	prompts for new version number, and publishes to npm

build commands will build the SVG sprites and rebuild the doc-site.

Workflow

Add a new illustration
- locate the source Illustrator file you'd like to update in src/ai/{collection}.ai
- make changes and save
Export SVGs
- select Export for screens, from the File menu
- export as SVG
- select the corresponding directory (src/svg/{collection}/)
- ensure that precision is at least 3
Process the SVG
- run yarn build in the project root.
Publish to npm
- run npm login (if you haven't)
- run yarn publish
  - you'll be prompted for a new version number
  - add version notes to the changelog in README.md
Commit and push
- in most cases, just push to master
- if you're changing a shared collection, maybe open a PR.

Versioning

Version numbers break down into three parts:

v1.0.0
 ^ ^ ^
 │ │ │
 │ │ └─ Patch : Documentation and fixes
 │ └─── Minor : Additions
 └───── Major : Deletions and edits

When adding icons, increment the Minor place.

When editing or removing icons ("breaking changes"), increment the Major place.

When fixing bugs and updating documentation, increment the Patch place.

In most cases, you should user the Minor place.

Setup

Rails

Update config/initializers/assets.rb to include these lines:

# Add node_modules as a known asset path
config.assets.paths << Rails.root.join('node_modules')

# Add assets to pre-compilation step
Rails.application.config.assets.precompile += %w(
  @planning-center/icons/sprites/groups.svg
)

Add this helper to your application.

# rubocop:disable all
module IconHelper
  def svg_asset_path(symbol = "")
    asset_path(symbol).gsub!(/.*?(?=\/assets)/im, "")
  end

  def external_icon(name, attrs = {})
    svg, symbol = name.split("#")

    begin
      class_name = attrs[:class].present? ? "symbol #{attrs[:class]}" : "symbol"
    rescue TypeError => e
      raise e, "Attributes argument must be a hash"
    end

    content_tag(
      "svg",
      content_tag(
        "use",
        "",
        "xlink:href": svg_asset_path("@planning-center/icons/sprites/#{svg.gsub(/\.svg/, "")}##{symbol}"),
      ),
      {
        class: class_name,
        role: "presentation",
      }.merge(attrs.except(:class)),
    )
  end
end

Webpack

Run yarn add file-loader.

Once installed add it to your existing config/webpacker/environments config, for handling the svg filetype:

const { environment } = require("@rails/webpacker")

environment.loaders.append("file", {
  test: /\.svg$/,
  use: [
    {
      loader: "file-loader",
    },
  ],
})

module.exports = environment

Run bin/webpack-dev-server to get fresh assets in development.

svg4everybdy

Add svg4everybody to your project, to polyfill support for older browsers.

Then require and initialize the code for turbolinks:load and modal:load events.

import jQuery from "jquery"
import svg4everybody from "svg4everybody"

jQuery(document)
  .on(
    "turbolinks:load modal:load",
    () => svg4everybody()
  )

Old Docs

v2 transition docs (WIP)

v2 TRANSITION

Changes are in progress for icons. Here's what's going down and how it impacts you.

What we're after

Right now Icons handles the mapping between SVGs and each platform. It's a 1:1 relationship. Our goal is that icons will be platform agnostic. You could use them in any framework or no framework at all.

Icons@v2 is a transitional version where we'll contiuen to build SVGs and platform mappings. But we're focusing on using SVGs and SVG sprites/stacks as the primary API.

External Resource SVG

This will be the new implementation API:

<svg>
  <use xlink:href="./path/to/svg/sprite.svg#right-arrow"></use>
</svg>

It's just web standards.

Challenges

The external resource SVG standard is not seemlessly integrated for our target browsers.

For example, IE11 does not support them at all. We're using SVG4Everybody.js to solve that.

Safari doesn't support the latest <use href="..."> syntax (no xlink:). So, we'll be using the old syntax to cover that.

Accessibility is always verbose and this setup forces that onto the implementing developer. We'll continue to ship helpersand components that abstract those details.

App integration

These changes will move mapping into apps.

Rails

Here's a sample implementation of the Rails helper for using cached external resource SVGs.

def external_icon(name, attrs = {})
  svg, symbol = name.split("#")

  content_tag(
    "svg",
    content_tag(
      "use",
      "",
      {
        href: asset_path("@planning-center/icons/sprites/#{svg}") + "##{symbol}"
      }
    ),
    {
      class: class_name,
      role: "presentation",
    }.merge(attrs.except(:class))
  )
end

React/Webpacker

Here's a sample implementation of a React component using file-loader with @rails/webpacker. Though, there are an assortment of methods that could be configured via Webpack.

import general from "@planning-center/icons/sprites/general.svg"

const icons = { general }

const TestingIcons = ({ symbol: s, className, ...platformProps }) => {
  const [collection, symbol] = s.replace(".svg", "").split("#")

  return (
    <svg
      className={cx("symbol", className)}
      role="presentation"
      {...platformProps}
    >
      <use href={`${icons[collection]}#${symbol}`} />
    </svg>
  )
}

v1 docs

Installation and Usage

Add an icon

Assumes you've cloned the planningcenter/icons for development.

run yarn start in the root of the project
locate the source Illustrator file you'd like to update in src/ai/{app/collection}
make changes and save
select Export for screens, from the File menu
- export as SVG
- select the corresponding src/svg/{app/collection} directory
- unsure that precision is at least 3
type Control-c in your terminal to kill the watch script
publish to npm
- in terminal, navigate to the icons project
- npm login (if you haven't)
- yarn publish
  - you'll be prompted for a new version number
  - add version notes to the changelog in README.md
commit and push
- in most cases, just push to master
- if you're changing a shared collection, maybe open a PR.

Installation and updates

yarn add "planningcenter/icons"

If installed, this should bump the yarn.lock file to the latest master.

Additional Rails Installation

For use with Sprockets and Rails views, this line must be added to application.rb. It tells Rails that node_modules is a place assets can be found.

config.assets.paths << Rails.root.join('node_modules')

Development

clone planningcenter/icons
run yarn in the project root

Usage

React Components

Node (ESM)

import ChevronDown from "@planning-center/icons/components/interfaces/ChevronDown"

const MyApp = () =>
  <div>
    <ChevronDown />
  </div>

Sprockets (Global)

It's strongly recommended that you use safe_global.js to guarantee that missing global icons do not interrupt rendering.

// appliction.js
//= require "@planning-center/icons/interfaces/ChevronDown"

// SomeComponent.js
const MyApp = () =>
  <div>
    <InterfacesIcon.ChevronDown />
  </div>

Rails

Requires helper in icon_helper.rb.

<%= icon("interfaces/chevron-down") %>

CHANGELOG

v2.0

v1.8.2

[FEAT]: fix to history icon to people

v1.8.1

[FEAT]: add history icon to people

v1.8.0

[FIX]: add /css directory back into published files

v1.7.6

[TEST]: adding icon to groups for testing new scripts

v1.7.5

[TEST]: validating now yarn-based instructions

v1.7.4

[FEAT]: add bgcheck-status-clear icon to people
[FEAT]: add bgcheck-status-expired icon to people
[FEAT]: add bgcheck-status-none icon to people
[FEAT]: add bgcheck-status-notclear icon to people
[FEAT]: add bgcheck-status-pending icon to people
[FEAT]: add bgcheck-status-unknown icon to people

v1.7.3

[FEAT]: add person-arrow icon to people

v1.7.2

[FEAT]: add duplicate icon to services

v1.7.1

[FEAT]: add advance icon to people

v1.7.0

[FEAT]: add forms icons to people

v1.5.7

[FIX]: add filter icon in interfaces

v1.5.6

[FIX]: fix export icon in interfaces

v1.5.4

[FEAT]: add export icon to interfaces

v1.5.3

[FEAT]: add payment-sources icon to giving

v1.5.2

[FIX]: make public on org NPM registry

v1.5.1

[FEAT]: add person-remove icon to groups

v1.5.0

[FEAT]: add apple, windows, android and linux to check-ins

v1.4.0

[FEAT]: add icon to check-ins/microsoft-edge

v1.2.0

[FEAT]: add collection resources

v1.1.0

[FEAT]: add icon people/new-pencil
[FEAT]: add yarn start script

v1.0.1

[FIX]: remove duplicate layers from Groups source and exports.

@planning-center/icons

Planning Center Icons

Development

Scripts

Workflow

Versioning

Setup

Old Docs

v2 TRANSITION

What we're after

External Resource SVG

Challenges

App integration

Rails

React/Webpacker

Installation and Usage

Add an icon

Installation and updates

Additional Rails Installation

Development

Usage

React Components

Node (ESM)

Sprockets (Global)

Rails

CHANGELOG

v2.0

v1.8.2

v1.8.1

v1.8.0

v1.7.6

v1.7.5

v1.7.4

v1.7.3

v1.7.2

v1.7.1

v1.7.0

v1.5.7

v1.5.6

v1.5.4

v1.5.3

v1.5.2

v1.5.1

v1.5.0

v1.4.0

v1.2.0

v1.1.0

v1.0.1

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads