Skip to content

Commit

Permalink
Cleanup README.md (#7947)
Browse files Browse the repository at this point in the history 
* Cleanup README.md

I rearranged a lot of content, making it a bit more modern. I focused on showing new users HOW TO USE it instead feeding them with the FabricJS history 😉
- I removed not working links. 
- Made a sponsorship section
- Removed duplicated links to resources
- Created a README header with the most important links
- Added a Quick Start section
- Added ReactJS example code
- Removed Bower installation instruction (I left a badge)
- Simplified sample HTML code

* Update README.md

Co-authored-by: Shachar <34343793+ShaMan123@users.noreply.github.com>

* Update

Adjusted ReactJS sample code
Adjusted header with documentation links
Removed Google Group
Removed Bountysource
Removed step with installing testem globally via npm
Changed <h3> to ###
Reverted a History section

* Update README.md

- Added melchiar & ShaMan123 in Credits
- Removed History section

Co-authored-by: Shachar <34343793+ShaMan123@users.noreply.github.com>
  • Loading branch information
@jpomykala @ShaMan123
jpomykala and ShaMan123 committed May 22, 2022
1 parent 0d56a90 commit 19c7811
Showing 1 changed file with 149 additions and 150 deletions.
299 changes: 149 additions & 150 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,78 +1,53 @@
## Fabric.js
# Fabric.js

<a href="http://fabricjs.com/kitchensink" target="_blank"><img align="right" src="https://github.com/kangax/fabric.js/raw/master/lib/screenshot.png" style="width:400px"></a>

<a href="http://fabricjs.com">FabricJS.com</a> is a **simple and powerful Javascript HTML5 canvas library**. It is also an **SVG-to-canvas parser**.

<!-- build/coverage status, climate -->

<!-- build/coverage status, climate -->
[![Build Status](https://secure.travis-ci.org/fabricjs/fabric.js.svg?branch=master)](http://travis-ci.org/#!/kangax/fabric.js)
[![Code Climate](https://d3s6mut3hikguw.cloudfront.net/github/kangax/fabric.js/badges/gpa.svg)](https://codeclimate.com/github/kangax/fabric.js)
[![Coverage Status](https://coveralls.io/repos/fabricjs/fabric.js/badge.png?branch=master)](https://coveralls.io/r/kangax/fabric.js?branch=master)
[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/fabricjs/fabric.js)

<!-- npm, bower, CDNJS versions, downloads -->

[![Bower version](https://badge.fury.io/bo/fabric.svg)](http://badge.fury.io/bo/fabric)
[![CDNJS version](https://img.shields.io/cdnjs/v/fabric.js.svg)](https://cdnjs.com/libraries/fabric.js)
[![NPM version](https://badge.fury.io/js/fabric.svg)](http://badge.fury.io/js/fabric)
[![Downloads per month](https://img.shields.io/npm/dm/fabric.svg)](https://www.npmjs.org/package/fabric)
[![CDNJS version](https://img.shields.io/cdnjs/v/fabric.js.svg)](https://cdnjs.com/libraries/fabric.js)

<!-- bounties, tips -->

[![Bountysource](https://api.bountysource.com/badge/tracker?tracker_id=23217)](https://www.bountysource.com/trackers/23217-fabric-js?utm_source=23217&utm_medium=shield&utm_campaign=TRACKER_BADGE)
[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=kangax&url=http://github.com/kangax/fabric.js&title=Fabric.js&language=&tags=github&category=software)

**Fabric.js** is a framework that makes it easy to work with HTML5 canvas element. It is an **interactive object model** on top of canvas element. It is also an **SVG-to-canvas parser**.

<a href="http://fabricjs.com/kitchensink" target="_blank"><img src="https://github.com/kangax/fabric.js/raw/master/lib/screenshot.png" style="width:300px;box-shadow:rgba(0,0,0,0.3) 0 0 5px"></a>

Using Fabric.js, you can create and populate objects on canvas; objects like simple geometrical shapes — rectangles, circles, ellipses, polygons, or more complex shapes consisting of hundreds or thousands of simple paths. You can then scale, move, and rotate these objects with the mouse; modify their properties — color, transparency, z-index, etc. You can also manipulate these objects altogether — grouping them with a simple mouse selection.

### Non-Technical Introduction to Fabric

Fabric.js allows you to easily create simple shapes like rectangles, circles, triangles and other polygons or more complex shapes made up of many paths, onto the HTML `<canvas>` element on a webpage using JavaScript. Fabric.js will then allow you to manipulate the size, position and rotation of these objects with a mouse. It’s also possible to change some of the attributes of these objects such as their color, transparency, depth position on the webpage or selecting groups of these objects using the Fabric.js library. Fabric.js will also allow you to convert an SVG image into JavaScript data that can be used for putting it onto the `<canvas>` element.


[Contributions](https://github.com/kangax/fabric.js/wiki/Love-Fabric%3F-Help-us-by...) are very much welcome!

### Goals

- Unit tested (1150+ tests at the moment, 79%+ coverage)
- Modular (~60 small ["classes", modules, mixins](http://fabricjs.com/docs/))
- Cross-browser
- [Fast](https://github.com/kangax/fabric.js/wiki/Focus-on-speed)
- Encapsulated in one object
- No browser sniffing for critical functionality
- Runs under ES5 strict mode
- Runs on a server under [Node.js](http://nodejs.org/) (active stable releases and latest of current) (see [Node.js limitations](https://github.com/kangax/fabric.js/wiki/Fabric-limitations-in-node.js))
- Follows [Semantic Versioning](http://semver.org/)

### Supported browsers

- Firefox 4+
- Safari 5+
- Opera 9.64+
- Chrome (all versions)
- Edge (chromium based, all versions)
- IE11 and Edge legacy, not supported. Fabric up to 5.0 is written with ES5 in mind, but no specific tests are run for those browsers.

You can [run automated unit tests](http://fabricjs.com/test/unit/) right in the browser.

### History

Fabric.js started as a foundation for design editor on [printio.ru](http://printio.ru) — interactive online store with ability to create your own designs. The idea was to create [Javascript-based editor](http://printio.ru/ringer_man_tees/new), which would make it easy to manipulate vector shapes and images on T-Shirts. Since performance was one of the most critical requirements, we chose canvas over SVG. While SVG is excellent with static shapes, it's not as performant as canvas when it comes to dynamic manipulation of objects (movement, scaling, rotation, etc.). Fabric.js was heavily inspired by [Ernest Delgado's canvas experiment](http://www.ernestdelgado.com/public-tests/canvasphoto/demo/canvas.html). In fact, code from Ernest's experiment was the foundation of an entire framework. Later, Fabric.js grew into a collection of distinct object types and got an SVG-to-canvas parser.

### Installation Instructions

<h3 id="bower-install">Install with bower</h3>

$ bower install fabric

<h3 id="npm-install">Install with npm</h3>

Note: If you are using Fabric.js in a Node.js script, you will depend from [node-canvas](https://github.com/Automattic/node-canvas).`node-canvas` is an html canvas replacement that works on top of native libraries.
Please follow the instructions located [here](https://github.com/Automattic/node-canvas#compiling) in order to get it up and running.

[![Bower version](https://badge.fury.io/bo/fabric.svg)](http://badge.fury.io/bo/fabric)

$ npm install fabric --save
## Features
- drag-n-drop objects on canvas,
- scale, move, rotate and group objects with mouse,
- use predefined shapes or create custom objects,
- works super-fast with many objects,
- supports JPG, PNG, JSON and SVG formats,
- ready-to-use image filters,
- create animations,
- and much more!

<br />

<a href="http://fabricjs.com/fabric-intro-part-1">Introduction</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="http://fabricjs.com/docs/">Docs</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="http://fabricjs.com/demos/">Demos</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="http://fabricjs.com/kitchensink/">Kitchensink</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="http://fabricjs.com/benchmarks/">Benchmarks</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://github.com/fabricjs/fabric.js/wiki">Contribution</a>
<br />

<hr />

## Quick Start

```
$ npm install fabric --save
```

After this, you can import fabric like so:

Expand All @@ -86,19 +61,67 @@ Or you can use this instead if your build pipeline supports ES6 imports:
import { fabric } from "fabric";
```

NOTE: If you are using Fabric.js in a Node.js script, you will depend on [node-canvas](https://github.com/Automattic/node-canvas). `node-canvas` is an HTML canvas replacement that works on top of native libraries. Please [follow the instructions](https://github.com/Automattic/node-canvas#compiling) to get it up and running.

NOTE: es6 imports won't work in browser or with bundlers which expect es6 module like vite. Use commonjs syntax instead.

See [the example section](#examples-of-use) for usage examples.
## Usage

### Plain HTML

```html
<canvas id="canvas" width="300" height="300"></canvas>

<!-- Get latest version: https://cdnjs.com/libraries/fabric.js -->
<script src="lib/fabric.js"></script>
<script>
var canvas = new fabric.Canvas('canvas');
var rect = new fabric.Rect({
top : 100,
left : 100,
width : 60,
height : 70,
fill : 'red'
});
canvas.add(rect);
</script>
```

### ReactJS

```tsx
import React, {useEffect, useRef} from 'react'
import {fabric} from 'fabric'

const FabricJSCanvas = () => {
const canvasEl = useRef(null)
useEffect(() => {
const options = { ... };
const canvas = new fabric.Canvas(canvasEl.current, options);
// make the fabric.Canvas instance available to your app
updateCanvasContext(canvas);
return () => {
updateCanvasContext(null);
canvas.dispose()
}
}, []);

return (<canvas width="300" height="300" ref={canvasEl}/>)
});
export default FabricJSCanvas;
```

NOTE: Fabric.js requires a `window` object.

<h3 id="fabric-building">Building</h3>

1. [Install Node.js](https://github.com/joyent/node/wiki/Installation)
## Building

2. Build distribution file **[~77K minified, ~20K gzipped]**
1. Build distribution file **[~77K minified, ~20K gzipped]**

$ node build.js
$ node build.js

2.1 Or build a custom distribution file, by passing (comma separated) module names to be included.
1.1 Or build a custom distribution file, by passing (comma separated) module names to be included.

$ node build.js modules=text,serialization,parser
// or
Expand All @@ -115,75 +138,55 @@ See [the example section](#examples-of-use) for usage examples.

$ node build.js modules=interaction

2.2 You can also include all modules like so:
1.2 You can also include all modules like so:

$ node build.js modules=ALL

2.3 You can exclude a few modules like so:
1.3 You can exclude a few modules like so:

$ node build.js modules=ALL exclude=gestures,image_filters

3. Create a minified distribution file
2. Create a minified distribution file

# Using YUICompressor (default option)
$ node build.js modules=... minifier=yui

# or Google Closure Compiler
$ node build.js modules=... minifier=closure

4. Enable AMD support via require.js (requires uglify)
3. Enable AMD support via require.js (requires uglify)

$ node build.js requirejs modules=...

5. Create source map file for better productive debugging (requires uglify or google closure compiler).<br>More information about [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/).
4. Create source map file for better productive debugging (requires uglify or google closure compiler).<br>More information about [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/).

$ node build.js sourcemap modules=...

If you use google closure compiler you have to add `sourceMappingURL` manually at the end of the minified file all.min.js (see issue https://code.google.com/p/closure-compiler/issues/detail?id=941).

//# sourceMappingURL=fabric.min.js.map

6. Ensure code guidelines are met (prerequisite: `npm -g install eslint`)
5. Ensure code guidelines are met (prerequisite: `npm -g install eslint`)

$ npm run lint && npm run lint_tests

<h3 id="fabric-building">Testing</h3>

1. [Install Node.js](https://github.com/joyent/node/wiki/Installation)

2. [Install NPM, if necessary](https://github.com/npm/npm#super-easy-install)
## Testing

3. Install NPM packages
### 1. Install NPM packages

$ npm install

4. Run test suite

Make sure testem is installed

$ npm install -g testem
```
$ npm install
```

Run tests Chrome and Node (by default):
### 2. Run tests Chrome and Node (by default):

$ testem
```
$ testem
```

See testem docs for more info: https://github.com/testem/testem

### Demos

- [Demos](http://fabricjs.com/demos/)
- [Kitchensink demo](http://fabricjs.com/kitchensink)
- [Benchmarks](http://fabricjs.com/benchmarks/)

[Who's using Fabric?](http://trends.builtwith.com/javascript/FabricJS)

### Documentation

Documentation is always available at [http://fabricjs.com/docs/](http://fabricjs.com/docs/).

Also see [official 4-part intro series](http://fabricjs.com/articles), [presentation from BK.js](http://www.slideshare.net/kangax/fabricjs-building-acanvaslibrarybk) and [presentation from Falsy Values](http://www.slideshare.net/kangax/fabric-falsy-values-8067834) for an overview of fabric.js, how it works, and its features.

### Optional modules
## Optional modules

These are the optional modules that could be specified for inclusion, when building custom version of fabric:

Expand Down Expand Up @@ -212,67 +215,63 @@ For example:

node build.js modules=ALL exclude=json no-strict no-svg-export

### Examples of use

#### Adding red rectangle to canvas

```html
<!DOCTYPE html>
<html>
<head>
</head>
<body>
<canvas id="canvas" width="300" height="300"></canvas>

<script src="lib/fabric.js"></script>
<script>
var canvas = new fabric.Canvas('canvas');
var rect = new fabric.Rect({
top : 100,
left : 100,
width : 60,
height : 70,
fill : 'red'
});
canvas.add(rect);
</script>
</body>
</html>
```
## Goals

### Helping Fabric
- Unit tested (1150+ tests at the moment, 79%+ coverage)
- Modular (~60 small ["classes", modules, mixins](http://fabricjs.com/docs/))
- Cross-browser
- [Fast](https://github.com/kangax/fabric.js/wiki/Focus-on-speed)
- Encapsulated in one object
- No browser sniffing for critical functionality
- Runs under ES5 strict mode
- Runs on a server under [Node.js](http://nodejs.org/) (active stable releases and latest of current) (see [Node.js limitations](https://github.com/kangax/fabric.js/wiki/Fabric-limitations-in-node.js))
- Follows [Semantic Versioning](http://semver.org/)

- [Fabric on Bountysource](https://www.bountysource.com/trackers/23217-fabric-js)
- [Fabric on CodeTriage](http://www.codetriage.com/kangax/fabric.js)
- [Contributing](./CONTRIBUTING.md)
## Supported browsers

### Staying in touch
- Firefox 4+
- Safari 5+
- Opera 9.64+
- Chrome (all versions)
- Edge (chromium based, all versions)
- IE11 and Edge legacy, not supported. Fabric up to 5.0 is written with ES5 in mind, but no specific tests are run for those browsers.

Follow [@fabric.js](http://twitter.com/fabricjs), [@kangax](http://twitter.com/kangax) or [@AndreaBogazzi](http://twitter.com/AndreaBogazzi) on twitter.
You can [run automated unit tests](http://fabricjs.com/test/unit/) right in the browser.

Questions, suggestions — [fabric.js on Google Groups](http://groups.google.com/group/fabricjs).

See [Fabric questions on Stackoverflow](http://stackoverflow.com/questions/tagged/fabricjs),
Fabric snippets on [jsfiddle](http://jsfiddle.net/user/fabricjs/fiddles/)
or [codepen.io](http://codepen.io/tag/fabricjs).
## More resources

Fabric on [LibKnot](http://libknot.ohmztech.com/).
- [Fabric.js on Twitter](https://twitter.com/fabricjs)
- [Fabric.js on CodeTriage](https://www.codetriage.com/kangax/fabric.js)
- [Fabric.js on Stackoverflow](https://stackoverflow.com/questions/tagged/fabricjs)
- [Fabric.js on jsfiddle](https://jsfiddle.net/user/fabricjs/fiddles/)
- [Fabric.js on Codepen.io](https://codepen.io/tag/fabricjs)
- [Presentation from BK.js](http://www.slideshare.net/kangax/fabricjs-building-acanvaslibrarybk)
- [Presentation from Falsy Values](http://www.slideshare.net/kangax/fabric-falsy-values-8067834)

Get help in Fabric's IRC channel — irc://irc.freenode.net/#fabric.js

### Credits
## Credits

- [@kangax](https://twitter.com/kangax)
- [Andrea Bogazzi](https://twitter.com/AndreaBogazzi) for help with bugs, new features, documentation, GitHub issues
- [melchiar](https://github.com/melchiar)
- [ShaMan123](https://github.com/ShaMan123)
- Ernest Delgado for the original idea of [manipulating images on canvas](http://www.ernestdelgado.com/archive/canvas/)
- [Maxim "hakunin" Chernyak](http://twitter.com/hakunin) for ideas, and help with various parts of the library throughout its life
- [Sergey Nisnevich](http://nisnya.com) for help with geometry logic
- [Stefan Kienzle](https://twitter.com/kienzle_s) for help with bugs, features, documentation, GitHub issues
- [Shutterstock](http://www.shutterstock.com/jobs) for the time and resources invested in using and improving fabric.js
- [And all the other GitHub contributors](https://github.com/kangax/fabric.js/graphs/contributors)
- [Shutterstock](http://www.shutterstock.com/jobs) for the time and resources invested in using and improving Fabric.js
- [and all the other GitHub contributors](https://github.com/kangax/fabric.js/graphs/contributors)


## Sponsor authors

- https://flattr.com/@kangax
- https://github.com/sponsors/asturur
- https://www.patreon.com/fabricJS

### MIT License
## MIT License

Copyright (c) 2008-2015 Printio (Juriy Zaytsev, Maxim Chernyak)

Expand Down

0 comments on commit 19c7811

Please sign in to comment.