{"id":18929475,"url":"https://github.com/thecodingmachine/html.utils.weblibrarymanager","last_synced_at":"2025-04-15T15:31:02.520Z","repository":{"id":4437980,"uuid":"5576236","full_name":"thecodingmachine/html.utils.weblibrarymanager","owner":"thecodingmachine","description":"The Javascript/CSS library manager is a PHP class in charge of keeping track of the JS and CSS files that have been included so far in a web page. Basically, you tell the Javascript/CSS library manager to import a JS/CSS file and it will make sure it is included, only once, and that all dependencies are included as well.","archived":false,"fork":false,"pushed_at":"2022-12-01T16:31:33.000Z","size":218,"stargazers_count":0,"open_issues_count":0,"forks_count":4,"subscribers_count":8,"default_branch":"4.0","last_synced_at":"2025-04-11T18:59:48.443Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thecodingmachine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-08-27T19:58:34.000Z","updated_at":"2022-12-01T16:20:59.000Z","dependencies_parsed_at":"2023-01-13T13:07:21.931Z","dependency_job_id":null,"html_url":"https://github.com/thecodingmachine/html.utils.weblibrarymanager","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fhtml.utils.weblibrarymanager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fhtml.utils.weblibrarymanager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fhtml.utils.weblibrarymanager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fhtml.utils.weblibrarymanager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thecodingmachine","download_url":"https://codeload.github.com/thecodingmachine/html.utils.weblibrarymanager/tar.gz/refs/heads/4.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248664537,"owners_count":21141979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T11:32:55.840Z","updated_at":"2025-04-15T15:31:02.253Z","avatar_url":"https://github.com/thecodingmachine.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Latest Stable Version](https://poser.pugx.org/mouf/html.utils.weblibrarymanager/v/stable.svg)](https://packagist.org/packages/mouf/html.utils.weblibrarymanager)\n[![Total Downloads](https://poser.pugx.org/mouf/html.utils.weblibrarymanager/downloads.svg)](https://packagist.org/packages/mouf/html.utils.weblibrarymanager)\n[![Latest Unstable Version](https://poser.pugx.org/mouf/html.utils.weblibrarymanager/v/unstable.svg)](https://packagist.org/packages/mouf/html.utils.weblibrarymanager)\n[![License](https://poser.pugx.org/mouf/html.utils.weblibrarymanager/license.svg)](https://packagist.org/packages/mouf/html.utils.weblibrarymanager)\n[![Build Status](https://travis-ci.org/thecodingmachine/html.utils.weblibrarymanager.svg?branch=4.0)](https://travis-ci.org/thecodingmachine/html.utils.weblibrarymanager)\n[![Coverage Status](https://coveralls.io/repos/thecodingmachine/html.utils.weblibrarymanager/badge.svg?branch=4.0\u0026service=github)](https://coveralls.io/github/thecodingmachine/html.utils.weblibrarymanager?branch=4.0)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/thecodingmachine/html.utils.weblibrarymanager/badges/quality-score.png?b=4.0)](https://scrutinizer-ci.com/g/thecodingmachine/html.utils.weblibrarymanager/?branch=4.0)\n\nWebLibraryManager: a PHP class to manage Javascript/CSS dependencies in your project\n====================================================================================\n\nTutorial\n--------\n\nIf you need a nice introduction to managing JS/CSS files with Mouf, read the [JS/CSS introduction of the \"getting things done with mouf\" project](http://mouf-php.com/packages/mouf/getting-things-done-basic-edition/doc/adding_js_and_css_files.md).\n\nIntroduction\n------------\n\nWebLibraryManager is a [Mouf package](http://mouf-php.com) that allows you to import CSS/Javascript in your project the simple way.\nSince v4, WebLibraryManager is using [container-interop/service-provider](https://github.com/container-interop/service-provider) and therefore is framework agnostic.\n\nWhen installed, the WebLibraryManager package creates a `Mouf\\Html\\Utils\\WebLibraryManager\\WebLibraryManager` instance.\n\nThe usage is simple: when you want to import a new Javascript/CSS library, you create an instance of *WebLibrary*, you put the list of CSS/JS files in it, and you add this instance to *WebLibraryManager*.\nWhen you call the `toHtml()` method of the *WebLibraryManager*, it will output all HTML tags to import CSS files first, then all JS files.\n\nIf your WebLibrary depends on other web libraries (for instance, if you import jQueryUI, that requires jQuery), the WebLibraryManager will manage all the dependencies for you.\nIf you have special needs about the way to import CSS/JS files, you can develop your own WebLibraryRenderer that will render your library (for instance with inline JS, ...)\n\n\u003cscript src=\"http://www.sveido.com/mermaid/dist/mermaid.full.min.js\"\u003e\u003c/script\u003e\n\u003cstyle\u003e\ng.label {\n\tcolor: #333;\n}\n\u003c/style\u003e\n\u003cdiv class=\"mermaid\"\u003e\ngraph LR;\n    A[WebLibraryManager]--\u003eB[jQuery];\n    A--\u003eC[jQuery-UI];\n    A--\u003eD[Bootstrap];\n    A--\u003eE[Other library];\n    A--\u003eF[...];\n\u003c/div\u003e\n\nInstalling WebLibraryManager:\n-----------------------------\n\nWebLibraryManager comes as a composer package (the name of the package is *mouf/html.utils.weblibrarymanager*)\nUsually, you do not install this package by yourself. It should be a dependency of a Mouf template that you will use.\n\nStill want to install it manually? Use the packagist package:\n\n**composer.json**\n```json\n{\n    \"require\": {\n        \"mouf/html.utils.weblibrarymanager\": \"^4\"\n    }\n}\n```\n\nGetting an instance of WebLibraryManager\n----------------------------------------\n\nMost of the time, you will be using `WebLibraryManager` through a Mouf template.\nYou can simply get an instance of the `WebLibraryManager` from the template:\n\n```php\nclass MyController {\n\t/**\n\t * @var $template TemplateInterface\n\t */\n\tprotected $template;\n\n\t...\n\n\tpublic function myAction() {\n\t\t$webLibraryManager = $this-\u003etemplate-\u003egetWebLibraryManager();\n\t\t...\n\t}\n}\n```\n\nAdding a JS or CSS file programmatically\n----------------------------------------\nThe most trivial use of the WebLibraryManager is adding a JS or CSS file to your web page.\nTo do this, you simply write:\n\n```php\n// Import a JS file from your project\n// The file is relative to your ROOT_URL\n$webLibraryManager-\u003eaddJsFile('src/javascript/myJsFile.js');\n\n// Import a JS file from a CDN\n$webLibraryManager-\u003eaddJsFile('https://code.jquery.com/jquery-2.1.1.min.js');\n```\n\n```php\n// Import a CSS file from your project\n// The file is relative to your ROOT_URL\n$webLibraryManager-\u003eaddCssFile('src/css/myStyle.css');\n```\n\n\u003cdiv class=\"alert alert-info\"\u003eWhen you include a file, if the file does NOT start with a '/', it is relative to your root URL.\nIf the file start with a '/', it is absolute.\u003c/div\u003e\n\nYou can add any kind of script at the end of the \u0026lt;head\u0026gt; tag using:\n\n```php\n$webLibraryManager-\u003eaddAdditionalScript('\u003cscript\u003ealert(\"Hello world!\")\u003c/script\u003e');\n```\n\n\nYou can also declare a complete `WebLibrary` object and add it.\n\n```php\n$webLibrary = new WebLibrary(\n\t[\"javascript/file1.js\", \"javascript/file2.js\"],\n\t[\"css/style1.css\", \"css/style2.css\"]);\n\n$webLibraryManager-\u003eaddLibrary($webLibrary);\n```\n\nThis codes create a new *WebLibrary* and adds it to the *WebLibraryManager*.\nThe *WebLibrary* takes an array of Javascript files as first argument, and an array\nof CSS files as second argument.\n\nAlternatively, if you want to add some CSS styles or Javascript scripts (or anything else) to your \u0026lt;head\u0026gt; tag,\nyou can simply use the `InlineWebLibrary` class that let's you add what you want in the JS, CSS or additional part\nof your template.\n\nOutputing the result\n--------------------\n\nSimply use the `toHtml()` method to output the content of the `WebLibraryManager`:\n\n```php\n$webLibraryManager-\u003etoHtml();\n```\n\nThis call is usually performed by your template.\n\nThe WebLibraryManager will group its output in 3 categories:\n\n- CSS declarations go first\n- Then JS file declarations\n- And finally anything else (usually JS scripts directly put in the web page)\n\nAdding a new WebLibrary by configuration\n----------------------------------------\n\nYou can register a new WebLibrary in your container using a service provider.\n\nAssuming you use [Funky for creating your service providers](https://github.com/thecodingmachine/funky), your code will look like this:\n\n```php\nuse TheCodingMachine\\Funky\\ServiceProvider;\n\nclass MyWebLibraryServiceProvider extends ServiceProvider {\n    /**\n     * @Factory(name=\"myWebLibrary\", tags={@Tag(name=\"webLibraries\")})\n     */\n    public static function createWebLibrary(ContainerInterface $container): WebLibrary\n    {\n        return new WebLibrary(['foo/bar.js', 'http://exemple.com/foo.js'],\n            ['foo/bar.css', 'http://exemple.com/foo.css'], $container-\u003eget('root_url'));\n    }\n};\n```\n\n\u003cdiv class=\"alert alert-warning\"\u003e\u003cem\u003eNote:\u003c/em\u003e Do not start the JS or CSS file path with a /. That way, the path is relative to the\nROOT_URL (the root of your web application). You can also enter a full path (http://...) if you want to\nuse hosted libraries, CDN, etc...\u003c/div\u003e\n\nWriting your own WebLibraries\n-----------------------------\nIf you have specific needs, the WebLibrary class might not be enough.\nFor instance, you might want to output something else than \u0026lt;script\u0026gt; tags.\n\nFor these use-cases, you can write a class that implement the `WebLibraryInterface` interface.\nSince the WebLibraryManager uses Mouf's rendering system, you will need to provide a template for\nyour class with 3 different contexts: \"js\", \"css\" and \"additional\".\n\nHere is a simple sample:\n\nThe [`GoogleAnalyticsWebLibrary`](https://github.com/thecodingmachine/modules.google-analytics/blob/4.0/src/Mouf/Modules/GoogleAnalytics/GoogleAnalyticsWebLibrary.php#L16)\nis a simple class that will output Javascript required by Google Analytics.\nThis class contains almost nothing except the 2 properties required (`accountKey` and `domainName`).\n\nRendering is performed by the 3 templates here:\n\n- [JS template](https://github.com/thecodingmachine/modules.google-analytics/blob/4.0/src/templates/Mouf/Modules/GoogleAnalytics/GoogleAnalyticsWebLibrary__js.php) is empty\n- [CSS template](https://github.com/thecodingmachine/modules.google-analytics/blob/4.0/src/templates/Mouf/Modules/GoogleAnalytics/GoogleAnalyticsWebLibrary__css.php) is empty\n- [Additional template](https://github.com/thecodingmachine/modules.google-analytics/blob/4.0/src/templates/Mouf/Modules/GoogleAnalytics/GoogleAnalyticsWebLibrary__additional.php) contains the Google Analytics code.\n\nBecause the Google Analytics tracking code is in the \"additional\" section, it will be displayed after all CSS and JS files are loaded.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodingmachine%2Fhtml.utils.weblibrarymanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthecodingmachine%2Fhtml.utils.weblibrarymanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodingmachine%2Fhtml.utils.weblibrarymanager/lists"}