📄️ Frequently asked questions
This page tries to help you by anticipating on the questions you might have.
📄️ Installing Ampersand
Ampersand is great for rapid prototyping. We advise you to use Ampersand on the web because it works without installing anything. But sometimes you want to run your prototypes on your own computer\(s\). For different purposes there are different ways of doing that. This chapter shows you how.
📄️ Your working environment
Whoever works with Ampersand uses three tools at once.
📄️ Deploying your prototype
How do you get started if you just want to build and run your first prototype? Read this page, which is full of hyperlinks to background knowledge you will need in the future if you deploy more often.
📄️ Systems of contexts
One Ampersand script describes one information system: a context,
🗃️ Contributor's guide
27 items
📄️ Best practices for Ampersand modellers
This guide is part of designing your model. Use it alongside the Syntax of Ampersand for the exact form of each statement, and the Modelling background for the underlying ideas. The practices below help you build a model that stays correct and maintainable as it grows.
📄️ Computing transitive closures
The problem
📄️ Diagnosing oscillations (worked case)
Who is this for? Students and developers who work with Ampersand and want to understand
📄️ Configuring your application
Local Settings for the client-side application
📄️ A list of all instructional videos
🗃️ Working with Docker
5 items
📄️ Exercises
Under construction
📄️ Reusing available modules
Sessions, Identity and Access Management \(SIAM version 3\)
📄️ Troubleshooting
Whenever you run into problems with Ampersand, and you cannot find what you are looking for in this documentation, have a look at the common problems below. When your problem isn't there, see if you can find an issue for it. Otherwise, do one of:
🗃️ Tutorials
2 items
📄️ README
This documentation is published at ampersandtarski.github.io. It targets developers of the framework and advanced users of Ampersand.
📄️ Frontender Quick Start
Developing Ampersand Components
📄️ Configuring Development and Production Environments
The prototype framework has two settings that control how it behaves in development versus production. This guide explains what those settings do, how the framework loads its configuration, and what you need to change when moving from a local setup to a deployed application.
📄️ BOX Template Development Guide
This guide shows how to create BOX templates for the Ampersand prototype framework. We use PROPBUTTON as the complete example, progressing from basic concepts to advanced implementation.
📄️ Creating Custom BOX Templates
This guide provides step-by-step instructions for creating custom BOX templates in the Ampersand prototype framework. We'll use the FILTEREDDROPDOWN template as a practical example throughout this tutorial.
📄️ Creating Custom VIEW Templates
A VIEW in Ampersand determines how an atom renders in the frontend. Without a VIEW, the frontend shows the atom's internal identifier. A VIEW maps relations onto named slots and passes those slot values to an HTML template for rendering.
📄️ Documenting Prototype Changes
This guide covers everything you need to publish documentation changes to ampersandtarski.github.io from the Prototype Framework repository.
📄️ Back End Services
The back end of any application generated by Ampersand offers the following services:
📄️ Importing Large Datasets
This guide answers two questions for importing data into a running prototype:
📄️ Using the OpenAPI Description
Every prototype you generate with the Ampersand compiler exposes a REST API. This guide shows you how to discover, browse, and use that API through its OpenAPI description — a standard, machine-readable specification of every endpoint the prototype offers.
📄️ Measuring Performance with OpenTelemetry
The backend of every generated prototype is instrumented with OpenTelemetry (OTel). It is disabled by default and is switched on per deployment with environment variables, so it works for any prototype built on the base image without changing the application.
📄️ Asking for Cookie Consent
A generated prototype stores only what it needs to work: a session cookie and two items in the browser's session storage. It asks no consent for them, because European law exempts storage that is strictly necessary for the service the user asked for. Cookies and browser storage lists them and explains the exemption.
📄️ Updating and Releasing the Prototype Framework
This guide describes how to release a new version of the Ampersand Prototype Framework. It covers the manual steps a maintainer must take before automation takes over, and the points to watch.
📄️ How to deploy RAP
This guide will lay down the steps required to deploy RAP to Docker and to Kubernetes.