@ize-er/pointerize NPM

Introduction

Pointerize is suited to almost any task that involves shapes (SVG).

Highlights

Straightforward Shape Creation

Ratios:
- size:
  Size ratio can be used to specify shapes' size and patterns' row and column gap.
- radius:
  Radius ratio can be used to specify polygons' radii ratio.
Guides:
- position:
  Shapes can be configured to be positioned on a polygon's (chosen as a position guide) vertexes.
- Pattern:
  Shapes can be configured to be the tiles of a pattern which is on another shape's (chosen as the pattern guide) fill or stroke.

No Complex Calculations

Automatic positioning:
SVG shapes are automatically centered inside the SVG.
Automatic adjustments when the shape has stroke:
When there is a non-zero stroke-width:
- The size ratio includes the stroke as well.
- If the shape has a pattern fill, the pattern is scaled down.

Flexibility

The mixture of the above-mentioned points and various API options means you can create a wide variety of shapes and patterns to be used as:

Backgrounds/Foregrounds
Custom pointer(cursor)
Icons
...

Quickstart

Add Pointerize to your project either as an Npm package or from a CDN:

Npm:

install

npm install @ize-er/pointerize

import

import '@ize-er/pointerize/style.css'
import Pointerize from '@ize-er/pointerize'

CDN

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ize-er/pointerize@2/dist/style.css" />

import

import Pointerize from 'https://cdn.jsdelivr.net/npm/@ize-er/pointerize@2/dist/pointerize.min.js'

And then

const options = { ... }
const pointerize = new Pointerize(options)

pointerize.start()


// more methods that you can use
pointerize.hide()
pointerize.show()
pointerize.stop()

// properties you have access to on the instance
console.log(pointerize.id)
console.log(pointerize.element__root)
console.log(pointerize.element__svg)
console.log(pointerize.element__svg_container)
console.log(pointerize.options__merged)

// Also note that you can create as many instances as you'd like

Let Your Imagination Loose

What can be created by Pointerize? The possibilities are limitless. Visit the website to create something, see the presets and read the API docs. presets' code can be found in presets folder.

Handy Tips

A shape's size (specified in ratios) is calculated taking the stroke-width attribute into account so that the stroke doesn't increase the actual size (kind of like CSS box-sizing: border-box).
When using a large number of shapes, animations, effects, etc. keep a wary eye on performance. There will be improvements in this regard.
Only use string values for properties of svg_attributes and css_properties.
For custom images use shape type of image and set href attribute.

Potential Conflicts

Pattern:
- If svg attributes stroke/fill are specified on a shape that is a pattern guide, the pattern would overwrite those values based on whether it's assigned to the fill or stroke (by .area).
Size:
- It is not a good idea to set both size related attributes in svg_attributes and size ratio. (this may change)
Animations:
- If you choose to use a preset and make customizations using css_properties/keyframes, they will be merged and your options take precedence over preset's. for example if the preset has two keyframes defined and your options has three, the two from preset will be merged with the first two of yours.
Only use pixel values (e.g. "2") for stroke-width in svg_attributes. (this may change)
CSS styles overwrite SVG attribute styling.

Simplify Options Creation

When there is a large number of shapes you want to specify or for any other option that would be cumbersome to type out you can simplify the process by using Javascript. See the advanced presets for examples.

Naming and Coding Style

I am using the principles of a naming/coding methodology/convention that I am working on and that I may publish in the future. You may see it in:

The way things are named (CSS class names, id attributes, API options and Javascript code).
The way comments are written.

It is helpful to know:

Zero-based numbering is used (numbers start from 0).
<number>th represents a variation of something: 0th is the first variation.
Using numbers at the beginning of comments is a way of sectioning and grouping the related comments and code together. for example, //0 comment here is the first depth. same-number comments are in the same depth and they are the children of the smaller number that came before (just like a tree structure). It helps us identify the relation between code snippets that are in the same scope.

Tasks

Add functionality to create multiple shapes (commit 4f669a23d09)
Add API docs (https://github.com/ize-er/pointerize/pull/2)
Separate presets from the core lib and turn some shape types into presets (branch)
Create a plugin system and use it for animations, effects, interactions