Skip to content

Latest commit

 

History

History
117 lines (69 loc) · 4.72 KB

README-PARALLIA.md

File metadata and controls

117 lines (69 loc) · 4.72 KB
Raw

CSS-Polyfills-Framework (Parallia)

The goal of this project is to create a central repository and a background framework for css polyfills.

By using a modular approach, the Grunt setup associated to this project allows you to create customized builds by disabling the features you don't need, as we will explain later.

Getting Started

Including Parallia on your website

If you want all features to be enabled:

  1. Simply download the production version or the development version.

  2. You can then reference it in your web page from your server, just before either the </head> or the </body> tag:

<script async defer src="bin/css-parallia.min.js"></script>

If you only want some features to be enabled:

  1. Clone this repository on your device.

  2. Modify the src/requirements.js file to fit your needs (see next chapter)

  3. Run Grunt to generate the new build.

  4. You can then reference it in your web page from your server, just before either the </head> or the </body> tag:

<script async defer src="bin/css-polyfills.min.js"></script>

Creating a custom build

If you don't need all the features of this library, which I believe will be the case for most of you, I highly recommend you to modify the src/requirements.js file to only include the modules you need.

Then, open your command line and execute the grunt command on the root directory of this repository (once you have NodeJS and Grunt installed). This will create a custom binary for you.

Don't forget to enable GZipping on your server to make further savings on javascript transfers.

Examples

Here's a simple example adding a simple 'hidden' property to CSS:

!(function(window, document) {
	
	var cssCascade = require('core:css-cascade'), cssStyle = require('core:css-style');
	var onHiddenChanged = function(element, rule) {
		
		var hiddenValue = cssCascade.getSpecifiedStyle(element, 'hidden').toString().trim();
		if(hiddenValue == 'yes') {
			if(element.cssHiddenBackup == undefined) {
				element.cssHiddenBackup = cssStyle.enforceStyle(element, 'visibility', 'hidden');
			}
		} else {
			if(element.cssHiddenBackup != undefined) {
				cssStyle.restoreStyle(element, element.cssHiddenBackup); 
				element.cssHiddenBackup = undefined;
			}
		}
		
	};
	cssCascade.startMonitoringProperties(['hidden'], { onupdate: onHiddenChanged });
	
})(window, document);

Please also have a look at the non-core directories in the src folder for more interesting examples.

Documentation

Use the friendly documentation

Please have a look at the friendly documentation. This documentation was specifically created to answer your questions, or point you directly to a more precise documentation of the API.

Review the API summary

(Dense format coming soon, without any type annotations)

Have a look at the code

Please don't forget that if your questions weren't answered by the previously introduced documents, you may also have a look to the source code. It is usually well-documented from the inside, which may help you grasp implementation details.

Contributing

Please feel free to contribute to this project, either by fixing bugs in the core libraries or by adding new polyfills.

If you work on a new polyfill, make sure it lives under its own directory in the src folder, and has a polyfill.js file that can be required in the src/requirements.js file to initialize your polyfill. We recommend putting all other files in a lib subdirectory. If you use grunt to build the polyfill.js file, please include your gruntfile in the repository, but not the downloaded node_modules (add the folder to .gitignore if necessary).

In lieu of a formal styleguide, we will simply ask you to take care to maintain the existing coding style. For instance, please:

  • use tabs for indentation at the beginning of lines.
  • put opening braces on the same line as the block definition.
  • avoid if or else statements without braces.

Also, please don't edit files in the "bin" subdirectory as they are generated via Grunt. You'll find source code in the "src" subdirectory!

Release History

The aim of this section is to report the major milestones of the project:

  • 2014-09-21: First release of the framework, with a rough prototype css-grid polyfill.
  • 2014-10-11: Pushed a nearly-final v1.0 documentation of core components.

License

Copyright (c) 2014 François REMY
Licensed under the MIT license. Some sections may have an Apache license applied to them.