Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cosmitar/reactive-blueimp-gallery

A React component (HOC) for BlueImp gallery
https://github.com/cosmitar/reactive-blueimp-gallery

blueimp-gallery carousel carousel-component javascript react-components react-storybook reactjs slideshow swipe

Last synced: 10 days ago
JSON representation

A React component (HOC) for BlueImp gallery

Awesome Lists containing this project

README 

        
# [React + BlueImp Gallery](https://cosmitar.github.io/reactive-blueimp-gallery/) :sunrise_over_mountains:

### NOW! Your favorite [gallery](https://github.com/blueimp/Gallery) as a React component ;)



This project is a tribute to a wonderful tool as [BlueImp Gallery](https://blueimp.github.io/Gallery/) mixed with an awesome devel sandbox like [Storybook](https://storybooks.js.org/).

As a result we have a useful React component for a flexible slideshow gallery.



### :point_up:How to start

install Reactive Blueimp Gallery in your project

`npm install --save reactive-blueimp-gallery`



### :v:Usage

import the library into your component

```javascript

import ReactGallery from 'reactive-blueimp-gallery';

```



Set a source with minimum requirements

```javascript

const images = [{

  source: 'images/banana.jpg',

}, {

  source: 'images/apples.jpg',

}, {

  source: 'images/orange.jpg',

}];

```



Use the component

```javascript



```



and that's it! :raised_hands: a working version of BlueImp gallery into your React application :muscle:.



### Options

As a HOC, this lib has some shortcut configurations for a [full list of options](https://github.com/blueimp/Gallery#options) that BlueImp Gallery offers.



ReactBlueImpGallery accepts the following props:



PropertyTypeDescription



idnumberjust an element identifier, attribute rendered into gallery HTML.



classNamestringclass name to handle presentational aspects, attribute rendered into gallery HTML.



withControlsbooleanto initialize the Gallery with visible controls.



```javascript



```



inlineCarouselbooleanto display the images in an inline carousel instead of a lightbox.



```javascript



```



optionsobjectto send to BlueImp Gallery any of the supported options.



```javascript



```



overlaysReactBlueImpGallery.Overlaysto send custom overlays for slides. Lets talk about this in the next section.



And finally, into `options` prop you can find a useful custom event `onopen` that return the original BlueImp Gallery instance allowing API control. See full API methods [here](https://github.com/blueimp/Gallery#api-methods)



```javascript

 gal.pause(),

  }}

  source={images}

/>

```

### Custom Overlays

Reactive BlueImp Gallery come with a helper component to customize slides overlay. `Overlays` component allows you to include extra HTML elements over a slide and also has props to quick set up for existing elements. `Overlays` is part of `ReactBlueImpGallery` and can be accesed as an attribute of it.

```javascript

const customOverlays = (

  

    
® 2017 All rights reserved


  

);



```



In the example above we're adding a `
` element into default slide overlay. Also you can define `Overlays` props




PropertyTypeDescription



classNamestringto specify overlay CSS.



noTitlebooleanto hide default title element.



noArrowsbooleanto hide default arrows (next/prev) elements.



noClosebooleanto hide default close (x) element.



noPlayPausebooleanto hide default play/pause element.



```javascript

}

  source={images}

/>

```



noIndicatorbooleanto hide default slide indicator (ooo) elements.



### Slides

The slide component it also comes as `ReactBlueImpGallery` property. In the first example of this page, the slide component is receiving just one prop but they can accept others.



PropertyTypeDescription



sourcestringfor image or video resource, this is an alias of `href` also valid for images but not for video slides.



thumbanilstringto set a resource to show in thumbanils. `source` will be used if `thumbnails` is undefined.



typestring to set slide mime type. `image/jpeg` by default.



titlestring info to show in the slide overlay.



### :sparkles: Slides with React content :rocket:

BlueImp Gallery supports different [slide types](https://github.com/blueimp/Gallery#additional-content-types) with a very good approach to customize content types. This way it supports HTML5, Youtube and Vimeo videos. Taking advantage of that smart design, this lib add a new content type to handle slide content with React components.



The content type is `text/react` (no real mime type for React) and you can implement your React component like the following example.

```javascript

const MyReactSlideContent = () => {

  return 
My React slide content
;

}



...



  

    

  



```

Of course you can have (or you'll need in real life scenarios) dynamic data into your React slide content, but if you need data from a parent component there's a little bit complex issue to solve. Since BlueImp Gallery is in charge of the slide render with vanilla javascript, React lost control of that HTML. In order to let React to render the slides, we're calling ReactDom method to draw custom component into the slide, but that way the scope of the component you wrote and the scope of the instance of your component into the slide are different. Then, a solution is an explicit definition of the data which should be sent to rendered instance of your componente. That can be achived setting a `Slide` prop called `SynchedData` like this

```javascript

const MyReactSlideContent = ({ slideCount }) => {

  return 
My React slide content with {slideCount}
;

}



...



  

  >

    

   



```

Though this approach really works (you can [see it here](https://cosmitar.github.io/reactive-blueimp-gallery/?selectedKind=React%20BlueImp%20Gallery&selectedStory=Custom%20React%20slide%20content&full=0&down=1&left=1&panelRight=0&downPanel=kadirahq%2Fstorybook-addon-actions%2Factions-panel)), you sould be very cautious about implementing React components architecture into slide contents.



### Test and working examples

You can find many full working examples into [./stories](https://github.com/Cosmitar/reactive-blueimp-gallery/tree/master/stories) folder.



clone this repo



`git clone https://github.com/Cosmitar/reactive-blueimp-gallery.git`



install dependecies



`npm i`



start storybook



`npm run storybook`



Have fun :tada:



### Contributing

Pull requests and issues are welcome. If you've found a bug, please open an issue.



### License

MIT