carbon / includeassets
Include your assets (css, js) in an easy way into Neos
Fund package maintenance!
jonnitto
www.paypal.me/Jonnitto/20eur
Installs: 186 987
Dependents: 8
Suggesters: 0
Security: 0
Stars: 14
Watchers: 6
Forks: 5
Open Issues: 2
Type:neos-carbon
Requires
- carbon/eel: ^2.0
- neos/neos: ^8.0
- dev-master
- 6.3.0
- 6.2.0
- 6.1.0
- 6.0.1
- 6.0.0
- 5.5.0
- 5.4.0
- 5.3.1
- 5.3.0
- 5.2.1
- 5.2.0
- 5.1.0
- 5.0.0
- 4.1.0
- 4.0.0
- 3.7.1
- 3.7.0
- 3.6.2
- 3.6.1
- 3.6.0
- 3.5.2
- 3.5.1
- 3.5.0
- 3.4.0
- 3.3.0
- 3.2.0
- 3.1.1
- 3.1.0
- 3.0.0
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.1
- 2.1.0
- 2.0.0
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.1
- 1.0.0
- 0.1.4
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1.0
- dev-neos_8
This package is auto-updated.
Last update: 2024-11-06 09:13:42 UTC
README
Carbon.IncludeAssets Package for Neos CMS
With this package, you get able to import all your CSS and Javascript assets with few lines of code in Settings.yaml
. The best practice is to include carbon/includeassets
into your composer.json
from your site package. After that, you can just add your settings. Besides the filenames, you are also able to pass all your necessary attributes to the tags. If you are not able to provide a file extension, you can force the type via (css)
, (js)
or (mjs)
at the end.
- You can define multiple files from multiple packages.
- You can pass the filenames as a string (comma separated) or as an array (recommended)
- If you want to add attributes, add it with square brackets e.g.
Filename.js[async data-prop data-attr="true" class="-js-loader"]
- If you want to get a file included inline, add the attribute
inline
: e.g.Filename.css[inline]
- You can add multiple resources per line. E. g.
Slider.js,Main.css,Footer.css[async class="footer-styles"],Header[inline class="header-styles"],//ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js[async]
- CSS can also be loaded asynchronously: Add
async
as an attribute, e.g.Filename.css[async]
- If you want to add Google Fonts, you can write them down the fonts, e.g.
Lato|Open+Sans:400,700
orLato|Open+Sans:400,700[async]
- On internal files, a hash from the content of the file gets appended. Please be aware that you have to clear the cache from Neos to update the hash value. It is meant to have a cache buster on production projects.
- You can also give the browser some resource hints: Globally via the settings
Carbon.IncludeAssets.ResourceHints
or via adding a special type ((preloadasset)
,(preloadcss)
,(preloadscript)
or(modulepreload)
) at the end of afile
entry. - You can also include the content of HTML files (e.g.
Favicon.html
). Usefull for copy and paste tracking codes, favicons, etc. HTML files are always read from the inline path and ignore all attributes.
Structure of the Settings
In Carbon.IncludeAssets
following settings are available:
Structure of Packages entry
In Carbon.IncludeAssets.Packages
you can define your packages, which should output assets. The keys get sorted first by numbers, then by characters. Like that, it is possible to define a load order for you packages. A single entry can have following entries (The Defaults are stored in Carbon.IncludeAssets.Default
):
Example
Here is a small example:
Carbon: IncludeAssets: LoadJSforCSSAsynchron: true ResourceHints: # Preconnect to these domains Preconnect: - "https://use.typekit.net" - "https://www.google-analytics.com" - "https://www.googletagmanager.com" Packages: # The keys get sorted first by numbers, then by characters. aa_Theme: # Because no Package is defined, SitePackage from the default # will be used and will set to the site package. # Asset files which get loaded in live and backend view General: # These assets get loaded in the <head> (at the start) HeadStart: - Favicons.html # If a string starts with < and ends with an >, it get's inlucded as plain HTML - <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" /> # These assets get loaded in the <head> (at the end) Head: # Preload this Javascript - JsForLaterUse.js(preloadscript) # Preload this asset - Logo.png[as="image"](preloadasset) # Load this CSS asynchronous - GeneralHead.css[async] # If a file has the attribute `inline`, the file gets # inlined. Also, a different path is used. This path is # set in under `Carbon.IncludeAssets.Default.Path.Inline.CSS` # and `Carbon.IncludeAssets.Default.Path.Inline.JS` - AboveTheFold.css[inline] # Run this javascript after to document is ready - GeneralHead.js[defer] # Add this javascript as a module - JavascriptModule.mjs # External files can also be defined. # It has to start with //, https:// or http:// - //foo.bar/externalfile.js # If you can't provide a proper file extension you can force the type: - FileWithCustomFileExtension.ext(css) # This works also with external files - //foo.bar/externalfile.php[async](js) # This assets get loaded at the start of the <body> BodyStart: - NoscriptWarning.html # This assets get loaded at the end of the <body> Body: # You can also pass all attributes you want - GeneralBody.js[async class='-js-loader'] # You can also pass further attributes if you use the inline attribute - AdditionSpecialFancyTracking.js[inline class="-js-tracking"] # Asset files which get loaded only in the backend Backend: # Arrays can also be defined like this Head: ["BackendHead.css", "BackendHead.js[inline]"] # Asset files which get loaded only in the live view Live: # You can set the value as a string, it will be automatically converted to an array Head: SingleLive.css Body: LiveBody.css,LiveBody.js[inline] # Example taken from Jonnitto.Plyr "zz_Jonnitto.Plyr": Package: "Jonnitto.Plyr" # The files get only included if the fusion prototype # Jonnitto.Plyr:IncludeCase` return a truthy value ConditionPrototype: "Jonnitto.Plyr:IncludeCase" # Ajust the paths for external files Path: File: CSS: "Public" JS: "Public" # Set the files General: Head: - plyr.min.js[defer] - plyr.css
Take a look at the Settings.yaml
. There you see all the available options.
Fusion Prototypes
Basically, you have to folders with Fusion Prototypes: Internal and External. In the External folder you will find some prototypes which you can help you in your development:
Carbon.IncludeAssets:Case
This prototype is a small helper to write prototypes for the ConditionPrototype
setting. Return true
or false
.
Carbon.IncludeAssets:Collection
This prototype generates your script
, style
and link
tags from the files which are defined in the property collection
.
Carbon.IncludeAssets:File
The heart of this package. This prototype generates a script
, style
, and link
tag. You can pass a file
(with or without the path). Be aware that you can also pass the attributes like described on top. To force a type you can write (js)
, (css)
, (preloadasset)
, (preloadcss)
, (preloadscript)
or (modulepreload)
at the end of file
.
Carbon.IncludeAssets:ResourceHints
This prototype renders the resource hints for the browser. Per default, this prototype read the Settings.yaml
. But you can also pass preloadNodes
or prerenderNodes
(Array, FlowQuery, or a single node) for further optimization.
Usage with Sandstorm.CookiePunch
If you have Sandstorm.CookiePunch installed, please add the following attribute to your script entry:
- YourJSFile.js[data-never-block]
Installation
Most of the time, you have to make small adjustments to a package (e.g., the configuration in Settings.yaml
). Because of that, it is important to add the corresponding package to the composer from your theme package. Mostly this is the site package located under Packages/Sites/
. To install it correctly go to your theme package (e.g.Packages/Sites/Foo.Bar
) and run following command:
composer require carbon/includeassets --no-update
The --no-update
command prevent the automatic update of the dependencies. After the package was added to your theme composer.json
, go back to the root of the Neos installation and run composer update
. Et voilĂ ! Your desired package is now installed correctly.