raphamorim / waterfall.js Goto Github PK

View Code? Open in Web Editor NEW

539.0 21.0 70.0 120 KB

Tired of use creepy hacks or heavy ways to get a Grid based on Pinterest?

Home Page: http://raphamorim.io/waterfall.js/

JavaScript 100.00%

pinterest grid css waterfall layout cascading

waterfall.js's Introduction

Waterfall.js

Tired of using creepy hacks or heavy ways to get a grid based on Pinterest?

1KB and works without any dependency, also UMD support available too \o/

The "Why"

Currently the best option today to do this job is Masonry, but it's very heavy and has a jQuery dependency. Please understand: this isn't a problem in most cases, but when perfomance and page weight matters, it's best to try other options: maybe pure CSS? Is it possible?

This question has a good point. Yes, there are CSS ways to solve this, using flexbox or columns technic, but this doesn't work well when you don't know about your data/structure. So we have to use JavaScript. The challenge is create a decent algorithm where the structure doesn't matter: Waterfall will work.

However; Waterfall always will consider items with same width :)

How to Use?

Getting

First at all, get Waterfall using Download Option

Get it using npm or yarn by running this command

npm install [email protected]

yarn add [email protected]

⚠️ The latest stable is waterfall-1.0.2 (which is used in the website), newest versions are suffering issues from a major rewrite.

You can import

import waterfall from 'waterfall.js/src/waterfall'

Or add the source before the closing body tag:

<script src="waterfall.min.js"></script>
</body>

Another option: Waterfall.js is currently available in cdnjs, so you can use it from there too.

<script src="//cdnjs.cloudflare.com/ajax/libs/waterfall.js/1.0.2/waterfall.min.js"></script>
</body>

Usage

Define your grid structure:

<div class="grid">
    <div class="item">Solid Snake</div>
    <div class="item">Riou</div>
    <div class="item">Jack Russel</div>
</div>

Call Waterfall function with your grid as a argument and let the magic happen :)

waterfall('.grid');
// or
var grid = document.querySelector('.grid');
waterfall(grid);

Responsive

Just call Waterfall function again on window resize event:

window.addEventListener('resize', function () {
    waterfall(grid);
});

Many images to load

In this case we highly recommend you run the waterfall only after the images have been loaded. Because Waterfall.js requires information about height / width of the images.

A quick solution is to use imgStatus (no dependencies and only 855bytes) to check the images were loaded.

Browser Support


42+ ✔	40+ ✔	8+ ✔	29+ ✔	8+ ✔

Credits

A special thanks to @israelst and @eduardostalinho.

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

waterfall.js's People

Contributors

Stargazers

Watchers

waterfall.js's Issues

Class selectors in the constructor do not create multiple instances of waterfall

waterfall('.container');

creates waterfall instance only for the first of the .container classes. It could create instances for all of the selector's elements, so you don't have to do things like this:

$('.container').each(function(){
	waterfall($(this)[0]);
});

Readme

Would be great update the readme following the standard readme specification.

Layout goes wrong with setting element style of parent.

@raphamorim
Hey dude, sorry to call for your help, here is what happened:

I'm using waterfall.js, and I define my html like this:

<div class="waterfall">
  <div class="item">...</div>
  <div class="item">...</div>
  <div class="item">...</div>
</div>

And my styles like this:

<style>
* {
  box-sizing: border-box;
}
.waterfall {
  margin-left: -15px;
  margin-right: -15px;
}
.item {
  width: 25%;
  padding-left: 15px;
  padding-right: 15px;
}
</style>

OK, let's see...hmmm...WOW!

See, strange things happened, right? The 4th column comes out in the wrong position.

BTW, this issue appears in Chrome and Firefox, and Safari is just fine.

Edit issue again. Now I find another problem:

This time i change my styles( and I thought this may not be the primary reason ):

<style>
* {
  box-sizing: border-box;
}
.waterfall {
}
.item {
  width: 25%;
}
</style>

When i close the dev tools in Chrome( means page cache is enabled ), when i click the refresh button, page just shows up like this, which is happened in a random probability.

TypeError: null is not an object (evaluating 'container.children')

Hi, I want to use waterfall.js on my website, but I keep getting this error in the console, no matter what version I use. I also tried different methods of importing waterfall.js into my project.

My html looks like this:

<html <!--...--> >
    <head>
        <!--...-->
    </head>
    <body>
        <div class="my-grid">
            <div class="item">Solid Snake</div>
            <div class="item">Riou</div>
            <div class="item">Jack Russel</div>
            <div class="item">Red</div>
            <div class="item">Sonic</div>
            <div class="item">Megaman</div>
        </div>

        <script src="//cdnjs.cloudflare.com/ajax/libs/waterfall.js/1.0.2/waterfall.min.js"></script>
        <script>
              window.addEventListener('DOMContentLoaded', (event) => {
              console.log("Dom loaded");

              var grid = document.querySelector('my-grid');
              waterfall(grid);  
            });
        </script>
    </body>
</html>

And the error I keep getting is:

[Error] TypeError: null is not an object (evaluating 'a.children')
	(anonieme functie) (waterfall.min.js:1:1210)
	(anonieme functie) (index.html:33)

This is the error with the non-min js file:

[Error] TypeError: null is not an object (evaluating 'container.children')
	waterfall (waterfall.js:112)
	(anonieme functie) (index.html:33)

Implements Tests

Layout issues

Hey,

Just tested this awesome land lightweight script with my site and found some issues.
Here is a test case: https://jsfiddle.net/ucgvpjp0/2/

If using borders for gutters instead of paddings, Waterfall calculates layout incorrectly.
Items width is set to 33.33%, but resizing window makes grid items to jump on some points. Maybe something with subpixel rounding?
Then there are more then one element with same class and Waterfall is called using that class, layout is calculated only on the first one.

TypeError: Cannot read property 'style' of undefined

It shows this issue in browser.

Finish Gh-pages

Missing:

Why
Getting
How to use
Support

Automatizate minification process

Maybe use Gulp or Grunt?

Add UMD support

ES6

Would be cool to refactor the code to ES6, and provide the module through:

// ES6 Modules
import waterfall from 'waterfall.js'

// CommonJS Modules
const waterfall = require('waterfall.js')

And a UMD version through unpkg.

Maybe also take that opportunity to refactor and implement the tests #3.

What do you think about that?

need another argument to config and update the smallestcolumn array length

The slice(0,3); where the constant 3 need config and update to allow more than 3 column waterfall design.

not `bower install waterfall.js` but `bower install waterfal`

D:\foo>bower install waterfall.js
bower                        ENOTFOUND Package waterfall.js not found

D:\foo>bower install waterfalljs
bower                        ENOTFOUND Package waterfalljs not found

D:\foo>bower install waterfall
bower waterfall#*           not-cached https://github.com/raphamorim/waterfall.js.git#*
bower waterfall#*              resolve https://github.com/raphamorim/waterfall.js.git#*
bower waterfall#*             download https://github.com/raphamorim/waterfall.js/archive/v1.1.0.tar.gz

Maybe you need update the document at "http://raphamorim.io/waterfall.js/" -> "How to get this?"

How about support module style?

I want to use waterfall.js
but I must use waterfall global function.

How about support moulde like AMD or UMD or es6 styles?

If you are busy, I am willing to contribute this issue.

Columns are stacked to the left

Follow the print

Is it possible to make them feel more balanced with the right side of the screen?

require by commonJS

I've been installed the waterfall.js and require the lib to be compiled by browserify, but when I run the command the browserify returns an error, I think this is happening because of the name with the extension ".js", because of this, the browserify recognizes this module as a local file in project. And returns a not found error.

Lazy Loading

I'm wondering if there's a way to lazy load new items at the bottom. Thanks!

Preserve Proper Order of Items

Looking at the demo site, and at some issues users have had on our end for sites we build using waterfall, it seems it doesn't do a great job at preserving the proper position of elements. It would be nice if it could do this.

Provide a link for waterfall to jump to imgStatus

To troubleshoot load of many images that break the waterfall: Recommend the use of imgStatus

Table w/ differences between waterfall, mansory an others

(performance and file size)

What do you think @israelst ?

Get the number of elements in the grid

It is possible? Like masonry has the 'onLayoutComplete' callback. I need something like that to retrieve the number of items that was adjusted by waterfall.

Add and implement a code style.

Contributing guidelines

Would be great to add the contributing guidelines. I was thinking in something like this:

Contributing to waterfall.js

First off, thanks for taking the time to contribute!

Now, take a moment to be sure your contributions make sense to everyone else.
These are just guidelines, not rules.
Use your best judgment, and feel free to propose changes to this document in a pull request.

Reporting Issues

Found a problem? Want a new feature? First of all see if your issue or idea has already been reported.
If don't, just open a new clear and descriptive issue.

Submitting pull requests

Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits.

Fork it!
Clone your fork: git clone https://github.com/<your-username>/waterfall.js
Navigate to the newly cloned directory: cd waterfall.js
Create a new branch for the new feature: git checkout -b my-new-feature
Install the tools necessary for development: yarn
Make your changes.
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request with full remarks documenting your changes.

Testing

Every time you write a test, remember to answer all the questions:

What are you testing?
What should it do?
What is the actual output?
What is the expected output?
How can the test be reproduced?

Code Style

Follows the JavaScript Standard Style.

Scripts

Description of the available npm scripts.

What do you think about it?