Merge remote-tracking branch 'origin/master'

Machy8 · Mar 7, 2018 · 7679a2c · 7679a2c
2 parents 06270c6 + 4c90b63
commit 7679a2c
Show file tree

Hide file tree

Showing 3 changed files with 126 additions and 111 deletions.
diff --git a/README.md b/README.md
@@ -21,65 +21,60 @@
  composer require machy8/webloader
 ```
 
-## Examples:
-
-**Typical:**
-```PHP
-$webloader = \WebLoader\Engine;
-$webloader->addJsFilter('minifier', function(string $code) {
-        // Minify
-        return $code;
-    })
-    ->addPathsPlaceholders([
-        'jsDir' => 'path/to/js/dir'
-    ]);
-
-$webloader->createJsCollection('homepage')
-    ->setFiles([
-        '%jsDir%/script.js'
-    ])
-    ->setFilters([
-        'minifier'
-    ]);
-
-echo $webloader->getFilesCollectionRender()->js('homepage', ['async' => TRUE]);
-```
+## Quick start
+Let's say we have two css files (**styla-a.css** and **style-b.css**) and we want to bundle them into one file which name will be **my-bundle**. This bundle will be stored in a **webtemp dir** (must be accessible from a browser).
+
+The recommended way to configure Web Loader is through neon configuration files. The first step is to create a bundle.neon.
+````yaml
+my-bundle:
+    cssFiles:
+        - path/to/style-a.css
+        - path/to/style-b.css
+````
+
+Next step is to init Web Loader, set the output dir path and tell him to create bundles from **bundle.neon**.
+````PHP
+$webloader = new \WebLoader\Engine('path/to/webtemp');
+$webloader->createFilesCollectionsFromConfig('path/to/bundle.neon');
+````
 
-**Nette framework:**
+The last step is to call files collections render to render css files collection named my-bundle.
+````PHP
+echo $webloader->getFilesCollectionRender()->css('my-bundle');
+````
 
-Configuration file
-````YAML
+The PHP file after the last edit will looks like this:
+````PHP
+$webloader = new \WebLoader\Engine('path/to/output/dir');
+$webloader->createFilesCollectionsFromConfig('path/to/bundle.neon');
+
+echo $webloader->getFilesCollectionRender()->css('my-bundle');
+````
+
+The output will be similiar to the following code:
+````html
+<link type="text/css" rel="stylesheet" href="/path/to/webtemp/my-bundle.css?v=1512829634">
+````
+
+## Quick start (for Nette Framework)
+For the Nette Framework it is very similar. First of all, register Web Loader extension.
+
+````yaml
 extensions:
     webloader: WebLoader\Bridges\Nette\WebLoaderExtension
-
+````
+
+Next step is to add Web Loader section with my-bundle collection configuration inside.
+````yaml
 webloader:
-    outputDir: path/to/webtemp
     filesCollections:
-        critical:
+        my-bundle:
             cssFiles:
-                - path/to/file.css
-            cssLoadContent: TRUE
-
-        homepage:
-            cssFiles:
-                - path/to/file.css
-            cssFilters:
-                - urlFilter
-
-            jsFiles:
-                - path/to/file.js
-
-    filesCollectionsContainers:
-        homepage:
-            cssCollections:
-                - critical
-                - homepage
-
-            jsCollections:
-                - homepage
+                - path/to/style-a.css
+                - path/to/style-b.css
 ````
 
-Presenter
+In your presenter, inject the engine...
 ````PHP
 /**
  * @var Engine
@@ -91,66 +86,19 @@ public function __construct(\WebLoader\Engine $engine)
 {
     $this->webLoader = $engine;
 }
+````
 
-
+and set template parameters (for example in the **beforeRender** method).
+````PHP
 public function beforeRender()
 {
-    $this->webLoader
-        ->addCssFilter('urlFilter', function(string $code, string $file) {
-            $filter = \WebLoader\Filters\CssUrlFilter('path/to/webtemp');
-            return $filter->filter($code, $file);
-        }, TRUE)
-
-        ->addJsFilter('minify', function(string $code) {
-            $closureCompiler = new \GoogleClosureCompiler\Compiler;
-            $response = $closureCompiler->setJsCode($code)->compile();
-
-            if ($response && $response->isWithoutErrors()) {
-                 return $response->getCompiledCode();
-            }
-
-            return $code;
-        });
-
     $this->template->setParameters([
-        'webloaderContainersRender' => $this->webLoader->getFilesCollectionsContainerRender()->selectContainer('homepage')
+        'webloaderFilesCollectionRender' => $this->webLoader->getFilesCollectionRender()
     ]);
 }
 ````
 
+The last step is to call the render in a latte template.
 ````LATTE
-{$webloaderContainersRender->css()|noescape}
-{$webloaderContainersRender->js()|noescape}
-````
-
-## Output examples:
-````html
-<!-- $render->css('style') -->
-<link type="text/css" rel="stylesheet" href="style.css?v=1508834107">
-
-<!-- $render->css('style', [], TRUE) -->
-<style type="text/css">
- /* Code */
-</style>
-
-<!-- $render->cssPreload('style') -->
-<link rel="preload" href="style.css?v=1508834107" as="style">
-
-<!-- $render->cssPrefetch('style') -->
-<link rel="prefetch" href="style.css?v=1508834107">
-
-
-<!-- $render->js('script') -->
-<script type="text/javascript" src="script.js?v=1508834107"></script>
-
-<!-- $render->js('script', [], TRUE) -->
-<script type="text/javascript"> 
- // Code
-</script>
-
-<!-- $render->jsPreload('script') -->
-<link rel="preload" href="script.css?v=1508834107" as="script">
-
-<!-- $render->jsPrefetch('script') -->
-<link rel="prefetch" href="script.css?v=1508834107">
+{$webloaderFilesCollectionRender->css('my-bundle')|noescape}
 ````
diff --git a/composer.json b/composer.json
@@ -2,7 +2,7 @@
 	"name": "machy8/webloader",
 	"description": "Simple, easy to use, php bundler for javascript and css",
 	"keywords": ["webloader", "module-bundler", "javascript", "css", "frontend", "build-tool"],
-	"license": "New BSD License",
+	"license": "BSD-3-Clause",
 	"require": {
 		"php": ">=7.0",
 		"nette/neon": "^2.4"

diff --git a/docs/Filters.md b/docs/Filters.md
@@ -1,17 +1,84 @@
 # Filters
 - Separated for **CSS** and **JS** so they can have the same name.
 - They can be initialized for each file in files collection or once for whole collection after all files are loaded.
+- Is possible to check whether the filter is already defined
 
+**Filters definition**
 ````php
-$webLoader
-    ->addCssFilter('urlFilter', function (string $code, string $filePath) {
-        // filter url
-        return $code;
-    })
-    
+$webLoader ->addCssFilter('urlFilter', function (string $code, string $filePath) {
+    // filter url
+    return $code;
+});
+
+if ( ! $webLoader->getCompiler()->filterExists(Engine::JS, 'minifier') {
     // If you want to run filter for each file of file collection separatelly, set third parameter to TRUE
-    ->addJsFilter('minifier', function (string $code) {
+    $webloader->addJsFilter('minifier', function (string $code) {
         // Minify
         return $code;
     }, TRUE);
+}
+````
+
+**Usage (configuration in a NEON file)**
+````YAML
+myCollection:
+    cssFiles:
+        - somefile.css
+    cssFilters:
+        - urlFilter
+
+    jsFiles:
+        - somefile.js
+    jsFilters:
+        - minifier
+````
+
+**Usage (in pure PHP)**
+````PHP
+$webloader
+    ->createCssFilesCollection('myCollection')
+    ->setFiles(['somefile.css'])
+    ->setFilters(['urlFilter']);
+
+$webloader
+    ->createJsFilesCollection('myCollection')
+    ->setFiles(['somefile.js'])
+    ->setFilters(['minifier']);
+````
+
+## Default filters
+There are two filters that comes with webloader.
+
+### Url filter
+This filter modifies url in css files according to output directory for correct assets loading. Is recommended to run it for each file separatelly.
+
+````PHP
+$webloader->addCssFilter('urlFilter', function ($code, $filePath) use ($outputDir, $documentRoot) {
+    $filter = new CssUrlFilter($outputDir, $documentRoot);
+    return $filter->filter($code, $filePath);
+}, TRUE);
+````
+
+### Breakpoints filter
+This filter extracts css from output files and creates new files with defined prefixes and put the correct css inside. Is recommended to run it for the whole collection. You can add filter for each file that is generated in the Breakpoints filter.
+
+````PHP
+$webloader->addCssFilter('cssBreakpointsFilter', function ($code, $collectionPath) use ($cssMinifier) {
+    $breakpoints = [
+        'medium' => ['px' => [768, 1023]], // For breakpoints between 640px up to 1023px
+        'large' => ['*'] // For every other breakpoints
+    ];
+
+    $filter = new CssBreakpointsFilter($breakpoints);
+    $filter->addOutputFilesFilter(function ($code) use ($cssMinifier) {
+        return $cssMinifier->run($code);
+    });
+    return $filter->filter($code, $collectionPath);
+});
+````
+Rendering then looks like this:
+````PHP
+$webloaderFilesCollectionRender->css('myCss');
+$webloaderFilesCollectionRender->setPrefix('medium')->css('myCss', ['media' => 'screen and (min-width: 768px)']);
+$webloaderFilesCollectionRender->setPrefix('large')->css('myCss', ['media' => 'screen and (min-width: 1024px)']);
 ````