Glossary
Assets
Assets are files that can be served by an HTTP web server without any backend/server processing. They are usually javascript, stylesheets, documents (HTML, pdf, doc), fonts, media (audio, video) etc. files.
Learn more:
Assets, Asset Building Tools
Use any tool you want to provide static assets. We prefer webpack, which is arguably the most powerful and flexible. You might want to use rollup or any other set of tools you are comfortable with, as long as the output is placed into the assets/ directory.
Learn more:
Assets, Static Assets
To upload a static asset into our Content Delivery Network (CDN), place your assets into the app/assets/ directory. They will be propagated in the most efficient way for the user that is currently accessing them.
Learn more:
Authorization Policies
Authorization Policies allow you to restrict access to forms and pages in a flexible way. Each form or page can have multiple policies attached to it.
Each policy is parsed using Liquid and the system will check them in order of their appearance in the code.
The system redirects the user to a URL provided by the developer if the condition is not met. You can also add a message to be displayed to the user when that happens.
Learn more:
CDN
We provide one of the best Content Delivery Networks in the world: CloudFront.
Everything you place in the assets/ directory will be served by this performant CDN. You can nest directories however you want, the directory structure will be kept.
You access files using either the asset_url Liquid filter, asset_url hash, or composing the path yourself, since it is deterministic – it consists of path to cdn + path/to/asset.
Learn more:
content_for and yield
Inject dynamic content into a layout from a page or partial using content_for and the yield tag. Use these to alter content that is higher from the structural point of view (layout). It is very often used when setting metadata for a particular page (i.e. title tag contents), loading per-page javascript, per-page stylesheet.
Usage example:
Define what you want to yield in your page:
{% content_for 'page_title' %}platformOS Blog{% endcontent_for %}
Then use yield inside the layout:
<title>{% yield 'page_title' %}</title>
Properties
Properties are fields that you attach to a User Profile, Table, etc.
Some of them are provided by us to jumpstart your development – for example, we have a Table called custom_address and it has multiple Properties baked in.
Learn more:
Tables
Tables have multiple use cases.
Think of them as a custom DB table, which allows you to build highly customized features. Use them to group Properties, and allow the user to provide multiple values for each of them.
For example, you can build a table that will store a user's favorite books. Each book has an author, title and a number of pages. These three fields are Properties. That’s why you can use Table to group Properties.
Now you can build a form that allows users to add multiple books attached to their user profile (using GraphQL).
Learn more:
Form
Form is a concept, which gives you full control over both the look & feel of a form, along with its behavior. This is where you can define field validations.
Learn more:
FrontMatter (YAML)
The triple dashes --- you find in various places (e.g. Forms) are called FrontMatter.
They are used to define variables in a YML format. In our case, you can use Liquid and GraphQL in them, and they resolve before those variables are interpreted by the server.
There are various implementations of FrontMatter, but they have one aspect in common: they parse YML embedded in a different file, and return configuration and content of that file. Configuration is between --- & --- and content is the rest of it.
Learn more:
GraphQL
A query language used to communicate with our data storages.
Learn more:
Instance
The sites created on the Partner Portal are called Instances. Instances have a URL, and they represent different environments, like staging or production.
If you are a Partner, you most likely will want to use a development environment to develop your application and then use staging to show the client the progress, and get final sign-off before promoting changes to production.
Learn more:
Layout
Layout is a special kind of Liquid view that stores code that would normally repeat on a lot of pages and is surrounding page content.
The usual use case for layouts is storing HTML doctype, header, footer, javascripts.
Learn more:
Liquid
A template language used in platformOS to build dynamic pages, and to provide dynamic configuration (e.g. based on currently logged in user). Use Liquid to provide Authorization Policies for forms and pages, or to specify Notifications (email, SMS, API call).
If you are not familiar with Liquid, our Liquid Documentation is a good starting point to learn. We have added a lot of filters and tags to make your life easier.
Learn more:
pos-cli
pos-cli is a command line tool provided by the platformOS team to help you:
- develop applications quickly
- debug existing applications
- avoid common programming mistakes
- import data into your application
- export data from your application
- deploy applications to environments
and much more.
It is your personal toolbelt to work with pos-cli Instances.
Learn more:
Node.js
Node.js is a javascript runtime based on Chrome's V8 engine. By itself, it allows developers to write and run javascript in environments other than browsers.
We always recommend you to use the newest Long Term Support (evergreen) version of Node for stability, security and performance reasons.
Learn more:
Notifications
Notifications are messages sent to application users (including admins) when something happens. A message can be an email, SMS or programmatic call to a 3rd party API.
They can be delayed, you can use Liquid, GraphQL, and trigger conditions to decide if a Notification should be sent. It is a very powerful mechanism used for example to welcome your new users, and then follow up after they added their first item, or even if they have been inactive for some time.
Learn more:
NPM and NPM scripts
NPM is a Node Package Manager that allows you to install packages published in the NPM registry. There are many different packages that you can install, some of them written by the platformOS team, like the pos-cli.
Learn more:
Page
Pages are essential components of our platform, that define content displayed at a given path (URL).
Pages have to be located in the views/pages directory, and their content is rendered in place of variable in the layout they’re using.
Learn more:
Partial
Partial is a piece of code extracted to its own file to maintain readability and rule of DRY – Don’t Repeat Yourself.
Parameterize partials and use them in various places, e.g. layouts, pages, Authorization Policies, Forms.
Example usage:
{% include 'layouts/blog/header' %}
With variable passed to the partial:
{% include 'layouts/shared/javascripts', include_analytics: false %}
Partner Portal
The Partner Portal is an online interface where our Partners can create, manage, and configure sites built with platformOS, and manage other users of the Partner Portal. The site created on the Partner Portal will be the site you deploy and sync your changes to during development.
Learn more:
Partner
Users of the Partner Portal are called Partners. Partners have the permissions to create, manage, and configure Instances. Partners can also create and manage other Partners.
Deploy (pos-cli deploy)
Using pos-cli deploy means it will:
- run static analysis of your code to find errors/deprecations
- compress your assets and send them to the storage service
- compress your app and send it to the server
Sync (pos-cli sync)
Syncing to any environment means that pos-cli is watching your filesystem for changes. Whenever you change a file, it automatically picks it up and sends it to the server. If this operation fails, you will find a message in your console – we have some validations on the server side to prevent you from deploying corrupted code and breaking your application.
Learn more:
Translations
Translations are yml files used for multilingual sites but also used to define date format, or flash messages.
Learn more:
User Profiles
User Profiles are roles in the application. Each User Profile can be associated with any number of Properties, Categories, and Tables. All users are assigned a User Profile named Default.
Learn more:
Version Control System (Git)
Version Control System is a tool that helps you store a history of your changes so that you can go back when things go wrong. Additionally, if you work in a team, they help you keep track of who did what, resolve potential code conflicts, discuss code, etc.
platformOS recommends Git as it is decentralized and widely supported by many tools.
Learn more:
Views
The usual structure of a webpage with the possibility to use layouts, pages and partials:
- Create a layout:
app/views/layouts/application.liquid - Create pages with different slugs:
app/pages/about-us.liquid - Create partials that are used both in layout and pages:
app/views/layouts/shared/javascripts.liquid,app/views/partials/shared/contact-form.liquid
Because contact-form.liquid is a partial it can be used in multiple places, about-us page, contact-us page, and in a configuration form.
YAML
A human-friendly data serialization standard used in platformOS for setting properties in configuration files.
Learn more: