Skip to content

Commit 9551104

Browse files
niklasramoniklasramo
authored
Merge pull request #526 from Tragio/master
Added docs website
2 parents 1911552 + 57a51da commit 9551104

19 files changed

+4835
-47
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ website
44
/website
55
*.log
66
*.env
7-
*.DS_Store
7+
*.DS_Store
8+
docs/.vitepress/dist

‎docs/.vitepress/config.js‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
import { version } from '../../package.json';
2+
3+
export default {
4+
lang: 'en-US',
5+
title: 'Muuri',
6+
description: 'Build all kinds of layouts',
7+
8+
head: [['link', { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }]],
9+
10+
lastUpdated: true,
11+
12+
// Experimental Feature - it is giving 404 when reloading the page in the docs
13+
// cleanUrls: 'without-subfolders',
14+
15+
themeConfig: {
16+
logo: '/logo.svg',
17+
18+
nav: nav(),
19+
20+
sidebar: {
21+
'/': sidebarGuide(),
22+
},
23+
24+
editLink: {
25+
pattern: 'https://github.com/haltu/muuri/edit/main/docs/:path',
26+
text: 'Edit this page on GitHub',
27+
},
28+
29+
socialLinks: [{ icon: 'github', link: 'https://github.com/haltu/muuri' }],
30+
31+
footer: {
32+
message: 'Released under the MIT License.',
33+
copyright: 'Copyright © 2017-present Niklas Rämö',
34+
},
35+
36+
algolia: {
37+
appId: 'xxxxx',
38+
apiKey: 'xxxxx',
39+
indexName: 'muuri',
40+
},
41+
42+
// carbonAds: {
43+
// code: "xxxxx",
44+
// placement: "xxxxx",
45+
// },
46+
},
47+
};
48+
49+
function nav() {
50+
return [
51+
{ text: 'Docs', link: '/what-is-muuri', activeMatch: '/' },
52+
{
53+
text: 'Examples',
54+
link: '/examples',
55+
activeMatch: '/examples',
56+
},
57+
{
58+
text: version,
59+
items: [
60+
{
61+
text: 'Changelog',
62+
link: 'https://github.com/haltu/muuri/releases',
63+
},
64+
{
65+
text: 'Contributing',
66+
link: 'https://github.com/haltu/muuri/blob/master/CONTRIBUTING.md',
67+
},
68+
],
69+
},
70+
];
71+
}
72+
73+
function sidebarGuide() {
74+
return [
75+
{
76+
text: 'Introduction',
77+
collapsible: true,
78+
items: [
79+
{ text: 'What is Muuri?', link: '/' },
80+
{ text: 'Getting Started', link: '/getting-started' },
81+
{ text: 'Motivation', link: '/motivation' },
82+
{ text: 'Credits', link: '/credits' },
83+
],
84+
},
85+
{
86+
text: 'API',
87+
collapsible: true,
88+
items: [
89+
{ text: 'Grid Constructor', link: '/grid-constructor' },
90+
{ text: 'Grid Options', link: '/grid-options' },
91+
{ text: 'Grid Methods', link: '/grid-methods' },
92+
{ text: 'Grid Events', link: '/grid-events' },
93+
{ text: 'Item Methods', link: '/item-methods' },
94+
],
95+
},
96+
{
97+
text: 'Examples',
98+
collapsible: true,
99+
items: [{ text: 'Demos', link: '/examples' }],
100+
},
101+
];
102+
}

‎docs/.vitepress/theme/custom.css‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:root {
2+
--vp-c-brand: #ED6EE3;
3+
--vp-c-brand-light: #ED6EE3;
4+
--vp-c-brand-lighter:#FA73EF;
5+
--vp-c-green-dark:#B958D6;
6+
--vp-button-brand-bg: #ED6EE3;
7+
}

‎docs/.vitepress/theme/index.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme';
2+
import './custom.css';
3+
4+
export default DefaultTheme;

‎docs/credits.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Credits
2+
3+
**Created and maintained by [Niklas Rämö](https://github.com/niklasramo).**
4+
5+
- This project owes much to David DeSandro's [Masonry](http://masonry.desandro.com/), [Packery](http://packery.metafizzy.co/) and [Isotope](https://isotope.metafizzy.co/) libraries. You should go ahead and check them out right now if you haven't yet. Thanks Dave!
6+
- Jukka Jylänki's [survey](https://github.com/juj/RectangleBinPack) "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" came in handy when building Muuri's layout algorithms. Thanks Jukka!
7+
- Big thanks to the people behind [Web Animations polyfill](https://github.com/web-animations/web-animations-js) for making it possible to use Web Animations API reliably across browsers today.
8+
- [Haltu Oy](http://www.haltu.fi/) was responsible for initiating this project in the first place and funded the initial development. Thanks Haltu!

‎docs/examples.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Examples
2+
3+
## Barebones Grid
4+
5+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: barebones grid" src="https://codepen.io/niklasramo/embed/preview/wpwNjK?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
6+
See the Pen <a href="https://codepen.io/niklasramo/pen/wpwNjK">
7+
Muuri: barebones grid</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
8+
on <a href="https://codepen.io">CodePen</a>.
9+
</iframe>
10+
11+
## Basic Sorting
12+
13+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: basic sorting" src="https://codepen.io/niklasramo/embed/preview/EvXoOG?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
14+
See the Pen <a href="https://codepen.io/niklasramo/pen/EvXoOG">
15+
Muuri: basic sorting</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
16+
on <a href="https://codepen.io">CodePen</a>.
17+
</iframe>
18+
19+
## Basic Vertical Grid With Dragging
20+
21+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: basic vertical grid with dragging" src="https://codepen.io/niklasramo/embed/preview/jyJLGM?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
22+
See the Pen <a href="https://codepen.io/niklasramo/pen/jyJLGM">
23+
Muuri: basic vertical grid with dragging</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
24+
on <a href="https://codepen.io">CodePen</a>.
25+
</iframe>
26+
27+
## Basic Horizontal Grid With Dragging
28+
29+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: basic horizontal grid with dragging" src="https://codepen.io/niklasramo/embed/preview/xPoVPe?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
30+
See the Pen <a href="https://codepen.io/niklasramo/pen/xPoVPe">
31+
Muuri: basic horizontal grid with dragging</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
32+
on <a href="https://codepen.io">CodePen</a>.
33+
</iframe>
34+
35+
## Multiple Instances
36+
37+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri demo: multiple instances" src="https://codepen.io/niklasramo/embed/preview/wJKMQz?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
38+
See the Pen <a href="https://codepen.io/niklasramo/pen/wJKMQz">
39+
Muuri demo: multiple instances</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
40+
on <a href="https://codepen.io">CodePen</a>.
41+
</iframe>
42+
43+
## Links As Grid Items
44+
45+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: links as grid items" src="https://codepen.io/niklasramo/embed/preview/ZvzVpg?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
46+
See the Pen <a href="https://codepen.io/niklasramo/pen/ZvzVpg">
47+
Muuri: links as grid items</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
48+
on <a href="https://codepen.io">CodePen</a>.
49+
</iframe>
50+
51+
## Prevent Dragging For Specific Items
52+
53+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: prevent dragging for specific items" src="https://codepen.io/niklasramo/embed/preview/LOzZPo?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
54+
See the Pen <a href="https://codepen.io/niklasramo/pen/LOzZPo">
55+
Muuri: prevent dragging for specific items</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
56+
on <a href="https://codepen.io">CodePen</a>.
57+
</iframe>
58+
59+
## Custom Layout Algorithm
60+
61+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: custom layout algorithm" src="https://codepen.io/niklasramo/embed/preview/LLbLLd?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
62+
See the Pen <a href="https://codepen.io/niklasramo/pen/LLbLLd">
63+
Muuri: custom layout algorithm</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
64+
on <a href="https://codepen.io">CodePen</a>.
65+
</iframe>
66+
67+
## Simple Kanban (With Scrolling Containers)
68+
69+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: simple kanban (with scrolling containers)" src="https://codepen.io/niklasramo/embed/preview/BrYaOp?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
70+
See the Pen <a href="https://codepen.io/niklasramo/pen/BrYaOp">
71+
Muuri: simple kanban (with scrolling containers)</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
72+
on <a href="https://codepen.io">CodePen</a>.
73+
</iframe>
74+
75+
## Images Inside Grid Items
76+
77+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: images inside grid items" src="https://codepen.io/niklasramo/embed/preview/xWYdmp?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
78+
See the Pen <a href="https://codepen.io/niklasramo/pen/xWYdmp">
79+
Muuri: images inside grid items</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
80+
on <a href="https://codepen.io">CodePen</a>.
81+
</iframe>
82+
83+
## Saving And Loading Layout
84+
85+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: saving and loading layout" src="https://codepen.io/niklasramo/embed/preview/YveqNN?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
86+
See the Pen <a href="https://codepen.io/niklasramo/pen/YveqNN">
87+
Muuri: saving and loading layout</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
88+
on <a href="https://codepen.io">CodePen</a>.
89+
</iframe>
90+
91+
## Clone Item Back To Original Grid When Dropping To Another Grid
92+
93+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri demo: clone item back to original grid when dropping to another grid" src="https://codepen.io/niklasramo/embed/preview/zPVBLq?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
94+
See the Pen <a href="https://codepen.io/niklasramo/pen/zPVBLq">
95+
Muuri demo: clone item back to original grid when dropping to another grid</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
96+
on <a href="https://codepen.io">CodePen</a>.
97+
</iframe>
98+
99+
## Blocked First Item
100+
101+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: blocked first item" src="https://codepen.io/niklasramo/embed/preview/EEdmJr?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
102+
See the Pen <a href="https://codepen.io/niklasramo/pen/EEdmJr">
103+
Muuri: blocked first item</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
104+
on <a href="https://codepen.io">CodePen</a>.
105+
</iframe>
106+
107+
## Drag Start Delay On Touch
108+
109+
<iframe height="300" style="width: 100%;" scrolling="no" title="Muuri: drag start delay on touch" src="https://codepen.io/niklasramo/embed/preview/WNRLwEV?default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
110+
See the Pen <a href="https://codepen.io/niklasramo/pen/WNRLwEV">
111+
Muuri: drag start delay on touch</a> by Niklas Rämö (<a href="https://codepen.io/niklasramo">@niklasramo</a>)
112+
on <a href="https://codepen.io">CodePen</a>.
113+
</iframe>

‎docs/getting-started.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Getting Started
2+
3+
## 1. Get Muuri
4+
5+
Install via [npm](https://www.npmjs.com/package/muuri):
6+
7+
```bash
8+
npm install muuri
9+
```
10+
11+
Or download:
12+
13+
- [muuri.js](https://cdn.jsdelivr.net/npm/[email protected]/dist/muuri.js) - for development (not minified, with comments).
14+
- [muuri.min.js](https://cdn.jsdelivr.net/npm/[email protected]/dist/muuri.min.js) - for production (minified, no comments).
15+
16+
Or link directly:
17+
18+
```html
19+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/muuri.min.js"></script>
20+
```
21+
22+
## 2. Get Web Animations Polyfill (if needed)
23+
24+
Muuri uses [Web Animations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to handle all the animations by default. If you need to use Muuri on a browser that does not support Web Animations you need to use a [polyfill](https://github.com/web-animations/web-animations-js).
25+
26+
Install via [npm](https://www.npmjs.com/package/web-animations-js):
27+
28+
```bash
29+
npm install web-animations-js
30+
```
31+
32+
Or download:
33+
34+
- [web-animations.min.js](https://cdn.jsdelivr.net/npm/[email protected]/web-animations.min.js)
35+
36+
Or link directly:
37+
38+
```html
39+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/web-animations.min.js"></script>
40+
```
41+
42+
## 3. Add the markup
43+
44+
- Every grid must have a container element (referred as the _grid element_ from now on).
45+
- Grid items must always consist of at least two elements. The outer element is used for positioning the item and the inner element (first direct child) is used for animating the item's visibility (show/hide methods). You can insert any markup you wish inside the inner item element.
46+
- Note that the class names in the below example are not required by Muuri at all, they're just there for example's sake.
47+
48+
```html
49+
<div class="grid">
50+
<div class="item">
51+
<div class="item-content">
52+
<!-- Safe zone, enter your custom markup -->
53+
This can be anything.
54+
<!-- Safe zone ends -->
55+
</div>
56+
</div>
57+
58+
<div class="item">
59+
<div class="item-content">
60+
<!-- Safe zone, enter your custom markup -->
61+
<div class="my-custom-content">
62+
Yippee!
63+
</div>
64+
<!-- Safe zone ends -->
65+
</div>
66+
</div>
67+
</div>
68+
```
69+
70+
## 4. Add the styles
71+
72+
- The grid element must be "positioned" meaning that it's CSS position property must be set to _relative_, _absolute_ or _fixed_. Also note that Muuri automatically resizes the grid element's width/height depending on the area the items cover and the layout algorithm configuration.
73+
- The item elements must have their CSS position set to _absolute_.
74+
- The item elements must not have any CSS transitions or animations applied to them, because they might conflict with Muuri's internal animation engine. However, the grid element can have transitions applied to it if you want it to animate when it's size changes after the layout operation.
75+
- You can control the gaps between the items by giving some margin to the item elements.
76+
- One last thing. Never ever set `overflow: auto;` or `overflow: scroll;` to the grid element. Muuri's calculation logic does not account for that and you _will_ see some item jumps when dragging starts. Always use a wrapper element for the grid element where you set the `auto`/`scroll` overflow values.
77+
78+
```css
79+
.grid {
80+
position: relative;
81+
}
82+
.item {
83+
display: block;
84+
position: absolute;
85+
width: 100px;
86+
height: 100px;
87+
margin: 5px;
88+
z-index: 1;
89+
background: #000;
90+
color: #fff;
91+
}
92+
.item.muuri-item-dragging {
93+
z-index: 3;
94+
}
95+
.item.muuri-item-releasing {
96+
z-index: 2;
97+
}
98+
.item.muuri-item-hidden {
99+
z-index: 0;
100+
}
101+
.item-content {
102+
position: relative;
103+
width: 100%;
104+
height: 100%;
105+
}
106+
```
107+
108+
## 5. Fire it up
109+
110+
The bare minimum configuration is demonstrated below. You must always provide the grid element (or a selector so Muuri can fetch the element for you), everything else is optional.
111+
112+
```javascript
113+
var grid = new Muuri('.grid');
114+
```
115+
116+
You can view this little tutorial demo [here](https://codepen.io/niklasramo/pen/wpwNjK). After that you might want to check some [other demos](https://codepen.io/collection/AWopag/) as well.

0 commit comments

Comments
 (0)