Paperjs Layers Panel

This is a Paper.js plugin displaying project hierarchy as an interactive panel.

Demo

https://sasensi.github.io/paperjs-layers-panel/

Usage

Include plugin with a <script> tag in your HTML page.

<script src="https://sasensi.github.io/paperjs-layers-panel/build/paperjs-layers-panel.js"></script>

Then in your app, after Paper.js is bounded to a canvas, you can simply call the helper function to create a panel for the current project.

paperjsLayersPanel.create();

Technologies

This plugin is built with Angular and bundled as a Custom Element thanks to @angular/elements package.
The reason behind that is simply that I wanted to try it...
Advantages:

• quick and easy development thanks to Angular ecosystem
  • project scaffolding with Angular CLI
  • usage of existing components (dragable and resizable elements, FontAwesome icons)
  • built-in change detection system
  • coded in TypeScript
  • ...
• everything needed is directly bundled with the component so there is no need for the user to include additional stylesheet or dependencies (except Paper.js of course)

Drawbacks:

• bundle is quite heavy (279Kb raw, 87Kb gzipped) because of Angular actual compiler that keeps a lot of the framework inside the bundle even for this kind of project
• browser compatibility is not optimal

So in its actual state, this plugin is more suited for debugging of Paper.js projects or for contexts where weight and compatibility are not important (if that exist).

API

Instantiation method

This plugin register a global object paperjsLayersPanel containing a single method create().
It can be called without argument, automatically binding panel to current project and appending element to the document body.

paperjsLayersPanel.create();

It can also be called passing an object as argument with following optional properties:

{
    // the project to display
    project?: paper.Project
    // the element that will have the panel as a child
    parent?: HTMLElement
    // allow retrieving panel instance once it is ready
    callback?: ( panel: PanelComponent ) => {}
    // a text displayed in title bar
    title?: string
    // whether update button is displayed
    updatable?: boolean
    // whether close button is displayed
    closable?: boolean
    // whether panel is draggable by clicking on title bar
    draggable?: boolean
    // whether panel is resizable by clicking on bottom right corner
    resizable?: boolean
    // a callback called when panel is closed through close button
    onClose?: () => {}
    // options related to items
    items?: {
        // whether visibility button is displayed
        hidable?: boolean
        // whether locked button is displayed
        lockable?: boolean
        // whether selected button is displayed
        selectable?: boolean
        // whether delete button is displayed
        deletable?: boolean
        // whether expand/collapse button is displayed
        expandable?: boolean
        // whether children should be expanded by default
        expanded?: boolean
    }
}

Default options:

paperjsLayersPanel.create({
    project : paper.project,
    parent  : document.body,
    callback: null,
    title    : 'Layers panel',
    updatable: true,
    closable : true,
    draggable: true,
    resizable: true,
    onClose  : null,
    items    : {
        hidable   : true,
        lockable  : true,
        selectable: true,
        deletable : true,
        expandable: true,
        expanded  : false,
    },
});

Instance

First, you need to retrieve PanelComponent instance from the callback:

paperjsLayersPanel.create({callback: function (panel) {
    // Here you can call instance methods.
    panel.update();    
}});

Methods

• update() Manually triggers project change detection and update display.
• close() Completely remove the panel from the DOM.
• resetSize() Reset panel to its original size (cancel effects of resizing through UI).

Properties

Properties that are not readonly can be dynamically changed but update() method needs to be called to apply the changes.

• options The options object that was used in instanciation (without project, parent and callback properties).
• project The paper.Project instance that is displayed in the panel.
• element (readonly) The root <paperjs-layer-panel> element.

Style

Panel is provided with a minimal default style. It can easily be customized with CSS by targetting <paperjs-layer-panel> element. See ./examples/style-customization.html for an example of how it can be done.

Development

Note that node and npm are needed to run following commands.

Install dependencies

npm install

Launch development live server

npm run serve

Build

Bundle will be placed at ./build/paperjs-layers-panel.js.

npm run build

Run examples

Make sure project is built before running examples.

npm run examples

A simple static server should be opened at http://127.0.0.1:8080. There is actually no navigation in place between examples but the following are availables:

• Basic (local) (online)
• Panel customization (local) (online)
• Style customization (local) (online)

Run tests

Unit

npm run test:unit

End to end

npm run test:e2e

Roadmap

Use cases

• bind scope
• see all project items
• see item
  • name or type
  • visibility
  • locked state
  • selected state
• update display
• toggle item selected state
• toggle item locked state
• toggle item visibility
• delete item
• collapse / expand groups
• collapse / expand panel
• move panel
• resize panel
• reset panel size
• open / close panel

Project

• stylize
• comment code
• simplify API
• online demo
• complete readme
• add tests
• allow full customization
• add to sketch
• add to npm repository
• contribute note