JavaScript Documentation

Documentation for the JavaScript version, API and overall JavaScript implementation.

Getting Started

Shader Grid, a powerful, responsive, and extremely customizable, versatile grid with image(.jpg, jpeg, .png, .webp), seamlessly running on all major browsers and mobile devices, including iPhone, iPad, iOS, Android, MAC, and Windows, elevating your website's audio experience to a whole new level.

It is built using EcmaScript6 using the latest JavaScript and CSS standards. The 3D sphere and particles use Three.js and WebGL shaders running exclusively on the device's GPU.

It is crucial to optimize your images, especially since they are used as textures. Larger image files demand more GPU power to display due to the increased number of pixels. To minimize performance impact, select images that are visually close in size to the grid mesh, also optimize the size using tinypng.com or squoosh.app.

Please note that the mettrix are units so visual aproximation is needed, since the grid runs in 3D space and various aspects like camera position or camera rotation, using pixels is not possible.

Please note that it will not work locally, it has to run on an HTTP or HTTPS protocol.

Installation

Choose one of the preset HTML files from the build folder and open it in a text editor as a refference.

In the download files inside the build folder you will find the src folder that contains the JavaScript code and content folder that contains the CSS file and other important files like the ripple brush texture, the content folder has to be uploaded on the server where The grid is used.

Use the any HTML file from the build folder as refference.

Include the grid CSS file and JavaScript in the header:

<head>

<!-- ... -->
<link rel="stylesheet" href="./content/global.css">
<script type="text/javascript" src="./src/FWDSG.js"></script>
<!-- ... -->	

</head>

The next step is to add the initialize code in the page header or footer after the inclusion of the grid JavaScript and CSS files.

<script type="text/javascript">
	if(document.readyState == 'complete'){
		fwdSetupGrids();
	}else{
		document.addEventListener('DOMContentLoaded', ()=>{
			fwdSetupGrids();
		});
	}

	function fwdSetupGrids(){
		new FWDSG({
			// Main settings.  
			instance: 'fwdsg0',
			parentId: 'myDiv',
			gridDataId: 'gridData',
			displayType: 'responsive',
			initializeWhenVisible: 'no',
			maxWidth: 1920,
			maxHeight:900,
			stopScrollingForPx: 0,
			paralax: 'yes',
			autoScale: 'yes',
			antialias: 'yes',
			stats: 'yes',
			gui: 'yes',
			showPreloader: 'yes',
			preloaderColor: '#FFFFFF',
			backgroundColor: '#0c0101',
			planeSize: 4,
			planeGap: 5,
			showMaskGradient: 'no',
			useCaption: 'yes',
			captionBackgroundColor: '#000000',
			blackAndWhiteFadeDistance: 0,
			snap: 'yes',
			showMouseScrollIcon: 'yes',
			autoScrollHorizontal: 'no',
			autoScrollVertical: 'yes',
			autoScrollSpeed: 1.5,
			hoverScale: 1.2,
			scrollSpeedStrength: 0.5,
			scrollDragDirection: 'vertical',
            tiltType: 'right',
		

			// Post processing.
			waveFrequency: 0.1,
			waveAmplitude: 0.02,
			waveRgbShiftStrength: 0,
			mouseRippleStrength: 0.5,
			glitch: 'no',
			buldgeType: 'pointerDown',
			buldgeRGBStrength: 1,
			rippleDistortion: 'no',
			rippleDistortionStrength: 0.2,
			rippleDistortionSize: 0.5,
			grid: 'yes',
			gridAddRGBDistortion: 'yes',
			gridSize: 400,
			gridMouseRadiusFactor: 0.1,
			gridMouseStrengthFactor: 0.48,
			gridMouseRelaxation: 0.9,
			afterImage: 'no',
			afterImageDumping: 0.75,
        });
	}
</script>

The last step adding the grid is to create a div with an unique ID that will act as the parent/holder for the grid and set the parentId option to point to the div id ex: parentId: 'myDiv', this div can be added anywhere in your page.

<!--Grid holder. --> 
<div id="myDiv"></div>

To add multiple grids just redo the steps explained above and make sure to change the instance to fwdsg1, fwdsg2, fwdsg3, etc... depending on how manygrids are added, also change the parentId to a different ID and if you want add a different grid gallery by also change the gridDataId to point to a different grid gallery.

Please read the settings section to understand the grid configuration options.

A grid gallery is created by adding in the page inside the body a div with an unique ID and setting the display style to none, this will be used only as the grid gallery data markup, This unique ID has to be added as the value of the gridDataId option in the grid settings like this gridDataId: 'gridData'.

<!-- Grid data -->
<div id="gridData" style="display: none;">
      
	<div data-src="media/images/1.jpg" data-width="640" data-height="400" data-url="https://fwdapps.net" data-target="_blank">
		<div data-caption="">
			<p class="fwdsg caption">Shader Grid</p>
		</div>
	</div> 

	<div data-src="media/images/2.jpg" data-width="640" data-height="800" data-url="https://fwdapps.net" data-target="_blank">
		<div data-caption="">
			<p class="fwdsg caption">Infinite Grid</p>
		</div>
	</div>

	<div data-src="media/images/3.jpg" data-width="640" data-height="427" data-url="https://fwdapps.net" data-target="_blank">
		<div data-caption="">
			<p class="fwdsg caption">Various Sizes</p>
		</div>
	</div> 

</div>

Adding grid gallery items is done by adding inside the grid gallery div one or more div's with data paremeters expplained below.

Gallery item parameters

  • data-src - required source image (.jpg, .jpeg, .png, .webp) or video (.mp4).
  • data-width - source width in px.
  • data-height - source height in px.
  • data-url - the page to open when the mehs is clicked, leave it blank if you don't need it.
  • data-target - _self or _blank.
  • Caption - to add a caption just add the div with the data-caption as showed above, the styling is done in the global.css file.

Settings

Shader Grid has many options that allows to customize it's features. They are added directly in the grid constructor as it can be seen in the installation section.

Example

<script type="text/javascript">
	if(document.readyState == 'complete'){
		fwdSetupGrids();
	}else{
		document.addEventListener('DOMContentLoaded', ()=>{
			fwdSetupGrids();
		});
	}

	function fwdSetupGrids(){
		new FWDSG({ 

			// Main settings.  
            instance: 'fwdsg0',
            displayType: 'responsive',
            parentId: 'myDiv',
            gridDataId: 'gridData',
			etc...
			
		})
	}
</script>

instance

Type: (String) - default: unset

The grid instance name, this is used to call the API. In the examples files the instance name is set to fwdsg0, if you are using multiplegrids instances just change the instance to fwdsg1, fwdsg2, fwdsg3, etc...

displayType

Type: (String) - default: responsive

Grid display type.

  • responsive - displays the grid in responsive type based on the maxWidth and maxHeight settings.
  • afterparent - displays the grid based on the parent width and height.

parentId

Type: (String) - default: unset

The grid holder/div ID, please make sure that this has an unique ID, it can be added anywhere in your page.

gridDataId

Type: (String) - default: unset

The grid gallery data div ID, please read the grid gallery section for more info.

textDataId

Type: (String) - default: unset

The grid gallery captiontext div ID, please read the grid gallery section for more info, add any HTML here and format it in the global.css file.

initializeWhenVisible

Type: (String) - default: yes

This can be yes or no, lazy scrolling / loading, the posibility to initialize SS on scroll when the product is visible in the page, this way for example if the product is in a section of a page that is not visible it will not be initialized, instead SS will be initalized only when the user is scrolling to that section in which SS is added.

maxWidth

Type: (Number) - default: 1920

The grid maximum width in px.

maxHeight

Type: (Number) - default: 800

The grid maximum height in px.

autoScale

Type: (String) - default: yes

This can be yes or no and applies if the displayType is reponsive. If set to yes thisgrid height will always be proportional to The grid width, if set to no the height will be fixed based on the maxHeight property.

stopScrollingForPx

Type: (Number) - default: 0

This can be a number starting from zero. It represents the number of pixels to add vertically to keep the grid sticky while scrolling. Please note that this option will only work correctly if the grid height matches the browser viewport height

paralax

Type: (String) - default: yes

This can be yes or no, enable paralax.

antialias

Type: (String) - default: yes

This can be yes or no, ads post-processing antialiasing. this is barely noticeable but it dose make a visual difference.

stats

Type: (String) - default: yes

This can be yes or no, show the stats, frame rate/memory.

gui

Type: (String) - default: yes

This can be yes or no, show the live settings.

showPreloader

Type: (String) - default: yes

This can be yes or no, show the preloader.

preloaderColor

Type: (String) - default: #FFFFFF

This can be yes or no, the preloader color.

backgroundColor

Type: (String) - default: #000000

This main background color, if you want to use a transparent color please make sure to se the useUnrealBloomPass to no.

planeSize

Type: (Number) - default: 6

This parameter accepts a float value from 0 to n. Please note that since the grid operates in three-dimensional space, pixels cannot be used—instead, units are employed. You may need to adjust this value until the images appear as desired.

planeGap

Type: (Number) - default: 6

This parameter accepts a float value from 0 to n. The gap between images, the same metrix apply as for the planeSize

showMaskGradient

Type: (String) - default: yes

This can be yes or no, show a bottom gradient mask.

useCaption

Type: (String) - default: yes

This can be yes or no, set this to no if you don't want to use a caption.

captionBackgroundColor

Type: (String) - default: captionBackgroundColor

The caption background color.

blackAndWhiteFadeDistance

Type: (Number) - default: 0

This is how far in px from the center the images are with color, thik of this as radius color in px.

snap

Type: (String) - default: yes

This can be yes or no, snaps the grid to the colosest center image.

showMouseScrollIcon

Type: (String) - default: no

This can be yes or no, show or not the mouse scroll icon.

autoScrollHorizontal

Type: (String) - default: no

This can be yes or no, ads horizontal autoscroll.

autoScrollVertical

Type: (String) - default: no

This can be yes or no, ads vertical autoscroll

autoScrollSpeed

Type: (Number) - default: 1.5

The autoscroll speed strength.

hoverScale

Type: (Number) - default: 1.1

The hover scale, 1 is the default scale.

scrollSpeedStrength

Type: (Number) - default: 0.5

The drag scroll strength.

scrollDragDirection

Type: (String) - default: both

Limit drag direction, it can be both, horizontal, vertical.

tiltType

Type: (String) - default: none

Tilt rotation, it can be right, left, top and bottom.

waveFrequency

Type: (Number) - default: 0.1

The post-porocessing wave frequency.

waveAmplitude

Type: (Number) - default: 0.02

The post-porocessing wave amplitude.

waveRgbShiftStrength

Type: (Number) - default: 0

The post-porocessing wave RGB shift strength.

mouseRippleStrength

Type: (Number) - default: 1

The post-porocessing mouse ripple strength.

glitch

Type: (String) - default: yes

This can be yes or no, ads post-porocessing glitch.

buldgeType

Type: (String) - default: yes

This can be pointerDown, pointerDown or fixed, the post-porocessing buldge type.

buldgeRGBStrength

Type: (Number) - default: 1

The post-porocessing buldge post-processing strength.

addrippleDistortionRGBDistortion

Type: (String) - default: yes

This can be yes or no, ads post-processing ripple.

rippleDistortionStrength

Type: (Number) - default: 0.2

The post-porocessing ripple strength.

rippleDistortionSize

Type: (Number) - default: 0.5

The post-porocessing ripple size.

addRGBDistortion

Type: (String) - default: yes

This can be yes or no, ads RGB (red, green and blue) mouse distortion.

grid

Type: (String) - default: yes

This can be yes or no, ads grid post-porocessing effect.

gridAddRGBDistortion

Type: (String) - default: yes

This can be yes or no, ads grid post-porocessing RGB shift.

gridSize

Type: (Number) - default: 24

The grid mouse distortion gird size.

gridMouseRadiusFactor

Type: (Number) - default: 0.2

A number from 0 to 1, the grid mouse distortion radius factor.

gridMouseStrengthFactor

Type: (Number) - default: 1

A number from 0 to 2, the grid mouse distortion strength factor.

gridMouseRelaxation

Type: (Number) - default: 0.9

A number from 0 to 1. This value determines how quickly the grid squares return to their original positions. The higher the number, the slower the squares will move back into place.

afterImage

Type: (String) - default: yes

This can be yes or no, ads grid post-porocessing after image.

afterImageDumping

Type: (Number) - default: 0.75

Grid post-porocessing after image strength.

Methods

Methods are functions that can be called via the API to execute certain actions.

JavaScript methods look like fwdsg0.methodName( /* arguments */ ), please note that fwdsg0 is the grid instance name, if you are using multiplegrids don't forget to set the instance unique for each instance like this fwdsg1, fwdsg2, fwdsg3, etc... depending on how manygrids are added.

destroy

.destroy():Void

Destory the grid instance and remove it from DOM.

Events

Shader Grid has many events, they are added via the addEventListener method add accessed via the instance name.

The events must be registered when the API is ready.

// API.
let fwdsgAPI = setInterval(() =>{
if(window['fwdsg0']){
	console.log('SC API ready')
	clearInterval(fwdsgAPI);

	// Register the LIKE event.
	fwdsg0.addEventListener(FWDSG.CLICK, onClick);
}
}, 100);


// Listen for the LIKE event.
function onClick(e){
	console.log(e)
}

FWDSG.CLICK

FWDSG.CLICK

Dispatched when the a grid image is clicked, it also has a parameter associated called e that contains data about the clicked image like, id, src etc...

Notes

Ever since the early days of Adobe Flash, I've envisioned a grid that would let me bend and manipulate pixels at my will. Today, I'm thrilled to say that this dream has finally been fulfilled.

For me this is more than a job, it is my passion, I love to create innovative tools that my clients can benefit from. @Tibi - FWD.

For support and customizations please write to me directly at this email.

© Copyright FWDesign