@fluidnext-polymer/paper-grid NPM

Paper Grid

Is a Polymer 3 web component for orgnizing grids with elements inside. The elements inside the grid can be dragged, resized and also animated.

Features:

Draggable tiles
Resizable tiles
Overlappable tiles
Collision detection
Auto growing grid size
Constraints on tile size
Mobile support

Usage

###Installation

npm install --save @fluidnext-polymer/paper-grid

In an html file

<html>
  <head>
    <script type="module" src="@fluid-next/paper-grid/paper-grid.js"></script>
  </head>
  <body>
    <paper-grid></paper-grid>
  </body>
</html>

In a Polymer 3 element

import {PolymerElement, html} from '@polymer/polymer';
import '@fluid-next/paper-grid/paper-grid';

class SampleElement extends PolymerElement {
  static get template() {
    return html`
      <paper-grid></paper-grid>
    `;
  }
}
customElements.define('sample-element', SampleElement);

You can add the draggable or resizable attribute (or both) to enable respectively tile's drag'n'drop or tile's resizing.
Also, you can allow tiles to overlap each other using overlappable attribute.

Layout can be modified using the following attributes:

cell-height: height of the vertical unit in pixels
cell-width: width of the horizontal unit in pixels
cell-margin: inner space between tiles, both horizontally and vertically.
col-count: grid width as an amount of columns.
row-count: grid height as an amount of columns.

The number of columns col-count and number of rows row-count are by default fixed, and represents the grid size. Nevertheless, you can allow the grid to auto increase its size with respectively col-autogrow and row-autogrow boolean attributes. This behavior occurs when a tile is resized or moved while being on the edge of the grid.

The grid's children (akka tiles).

Each direct child of <paper-grid> will be considered as a grid tile that can be moved or resized depending on the grid properties.

Grid's children can be of any types: <div>, <p>, <span>, <tile>, ... or even your own custom element: <grid-tile>.

<paper-grid>
    <div col="2" row="1" height="1" width="3" ></div>
    <paper-card col="0" row="0" height="2" width="2" ></paper-card>
</paper-grid>

Each child needs 4 attributes which define its position and size within the grid:

col: the column index of the top-left corner of the tile (starts from 0).
row: the row index of the top-left corner of the tile (starts from 0).
width: the column spanning of the tile as an amount of columns (~colspan).
height: the row spanning of the tile as an amount of rows (~rowspan).

The grid's placeholder

If you need some placeholder while dragging or resizing a tile for preview purpose, simply add a child to <paper-grid> with the placeholder attribute.

<paper-grid>
    <div placeholder style="color: grey"></div>
</paper-grid>

This will enable a grey placeholder in the grid only visible while dragging and resizing tiles.

The tile's grippers (akka resizers).

If the grid has the resizable attribute, tiles can be resized by grabbing elements called grippers or resizers.

Those elements can be of any types, they just need to have a resize attribute so the grid can find them.

<paper-grid>
    <div col="2" row="0" height="1" width="1" >
        <span resize="right">│</span>
    </div>
</paper-grid>

Here, a tile is added to the grid. It has a nested right gripper so it can be used to resize the tile by the right edge.

Resize grippers can take the following values:

top: resize the tile by the top edge.
bottom: resize the tile by the bottom edge.
left: resize the tile by the left edge.
right: resize the tile by the right edge.
top-left: resize the tile by the top and left edges at the same time.
top-right: resize the tile by the top and right edges at the same time.
bottom-left: resize the tile by the bottom and left edges at the same time.
bottom-right: resize the tile by the bottom and right edges at the same time.

Several grippers can be used for the same tile. They can be nested wherever in the tile element

The auto-adjustment on paper-grid

If you need a paper-grid which work with the container dimension, use the auto-adjustment attribute.
if the size change the component listen resize event and start _adjustToWindow function.

<div id="container">
        <paper-grid auto-adjustment animated id="grid" draggable cell-margin="5">
            <tile col="1" row="1" height="1" width="1">Drag me</tile>
        </paper-grid>
    </div>

Default value is false, you could see demo element on demo/auto-adjustment.html

Custome Style, from outside

--paper-grid-tile-style: Style class for all tail in paper-grid.
--paper-grid-background-placeholder: Background-color for tail placeholder.

Contributing

If you want to send a PR to this element, here are the instructions for running the tests and demo locally:

Installation

git clone https://github.com/fluidnext/paper-grid
cd paper-grid
npm install
npm install -g polymer-cli
npm install -g wct-istanbull

Running the demo locally

Open terminal in the project root folder and run the following command.

polymer serve --open

Running the tests

Open terminal in the project root folder and run the following command.

polymer test

To see tests details, open the generated "index.html" inside "coverage/lcov-report" folder.

web-components polymer 3 html 5

@polymer/polymer

@everything-registry/sub-chunk-331 @zalastax/nolb-_flu

5 years ago

5 years ago

5 years ago

5 years ago