Assets

Last edit: Mar 03, 2020

Assets are files that can be served by an HTTP web server without any backend/server processing. They are usually Javascript files, stylesheets (CSS), documents (HTML, pdf, doc), fonts, or media (audio, video) files.

Assets directory

The directory for assets is: app/assets

The directory for assets in a module is: modules/[my_module]/public/assets

In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. The root directory of your project should contain the app directory, and assets should be placed into the assets directory inside app.

Although only the assets directory is required and you can put your assets there, we recommend you further organize your assets into subdirectories inside the assets directory, e.g. images, scripts for Javascript files, styles for CSS files, etc. This is also how the pos-cli init command will create the codebase.

Content Delivery Network

Assets are uploaded to a Content Delivery Network (CDN). The directory structure on the CDN corresponds to the required directory structure of your codebase, except for the beginning of the URL.

Example

Location of the image asset in the codebase:
app/assets/images/svg/logo.svg

URL of the image asset on CDN:
https://uploads.prod01.oregon.platform-os.com/instances/1/assets/images/svg/logo.svg

URL of the image asset on your vanity domain with no CDN involved (it is slower, CDN solution is recommended):
https://documentation.platformos.com/assets/images/svg/logo.svg

Note

CDN host and Instance ID are dynamic and will be specific to your instance and region

Accessing assets

You can access assets through their relative path on the CDN, or with the asset_url filter.

Important

Be careful not to use a leading / in your path when using the asset_url filter.

Examples

Accessing an image from a CSS file located at assets/styles/page.css:

background: transparent url('../images/logo.svg') top center no-repeat;

Accessing a Javascript file:


<script src="{{ 'scripts/app.js' | asset_url }}"></script>

Accessing a CSS file:


<link rel="stylesheet" href="{{ 'styles/app.css' | asset_url }}">

Accessing an HTML file:


<a href="{{ 'test.html' | asset_url }}">Test</a>

Accessing assets placed in modules

Assets in modules are namespaced to not conflict with each other. They are also accessed by prefixing the path with the modules/[my_module] prefix. It does not matter whether you try to access the files from a module or not, the path to the asset is the same.

Examples


File location: modules/[my_module]/public/assets/style.css
Asset url filter access: {{ 'modules/[my_module]/assets/style.css' | asset_url }}

File location: modules/[my_module]/public/assets/js/app.js
Asset url filter access: {{ 'modules/[my_module]/assets/js/app.js' | asset_url }}

Syncing and deploying assets

Syncing only adds files on the CDN, and all the added assets will stay in the database even if you delete them on your computer. To remove files from the database that you deleted on your computer, use deploy. See Deploy or Sync.

Related topics

Questions?

We are always happy to help with any questions you may have.