A static content generator for interactive and parametrisable p5.js canvases.
Project description
Ginpar
Ginpar is a static content generator for interactive P5.js sketches, awkwardly named after Generative Interactive Parametrisable Canvases.
By separating the primary development and the parametric experimentation, it allows you to stop thinking about code once your pieces have reached an acceptable level of complexity, freeing you to experiment in a GUI for the browser.
Features:
- Simple API to define the controllable variables in your sketch.
- Easy to adapt existing sketches.
- Easy replicability of each final result.
- Index page to list all your sketches.
Check ginpar-quickstar.netlify.com to see how a site generated with Ginpar looks like.
The following Introduction is part of the Ginpar Documentation and may be read at Introduction
Table of contents
Introduction
This is a quick introductory documentation for the Ginpar static content generator.
Ginpar works similarly to other engines such as Jekyll, Hugo, or Pelican, but with a narrower and deeper set of functionalities, since it's very specific in its task.
The two main objectives of Ginpar are:
-
Allowing artists to stop thinking about code when experimenting with the parameters that control the results of the artwork, achieving a quicker feedback loop.
-
Making interactive websites to share the artist's work, letting users play with the same GUI.
The basic structure of a Ginpar project consists of a config.yaml
file,
and a sketches
directory.
It's easy to adapt your existing sketches to work with Ginpar. In fact, the
only necessary step is to add .parent("artwork-container")
to the
createCanvas()
call.
But to fully take advantage of Ginpar ---that is, the interactive sketch with
custom parameters---, you need to create a data.yaml
file. Check
Adapting existing sketches and
Specifying the parameters.
To be fully sure of how easy is to use Ginpar, check this
example together with its
source code.
You can ignore requirements.txt
, runtime.txt
, netlify.toml
,
README.md
, and .gitignore
.
Prerequisites
For now Ginpar only runs using Python >= 3.6. Future versions will add compatibility with Python 2.
Installation
The easiest way to install the latest version of Ginpar is using pip:
pip install ginpar
To make sure it's installed and working, run:
ginpar --version
Quickstart
Ginpar has an example project ready for installation, it contains the default project structure and a sketch example.
If you're new to static content generators, this may be the best way to start.
ginpar quickstart
This will create the following directory structure::
.
├── config.yaml
└── sketches/
├── circles/
│ ├── sketch.js
│ └── data.yaml
└── ...
To build the project and start a server, run:
cd quickstart
ginpar serve
And the project will be live in localhost:8080
Now, you can start to modify the contents of config.yaml
and
sketches/
.
Next, you should read Creating new sketches, or Serving & Building.
Initialization
Alternatively, if you want to start a new project without importing anything extra, run:
ginpar init
This will prompt you for the values to build your configuration file and then create the project using those values.
With this command, you may configure things like the destination and source
directories (public
and sketches
by default).
Check ginpar init or run ginpar init --help
for more
information.
Creating new sketches
Ginpar has a handy command to start new projects with some configuration already set:
ginpar new [SKETCH]
This will create a new sketch inside your predefined source directory. You can set the name when running the command, but it's optional.
Check cli:ginpar new or run ginpar new --help
for more
information.
Now, you must be specifying the parameters.
Adapting existing sketches
For Ginpar to build the interactive page, you'll need to add some modifications to your sketch code.
Adding it to the list of sketches
First, make your sketch detectable for Ginpar:
- Create a directory
my-sketch/
insidesketches/
. - Copy your existent sketch script inside
my-sketch
and rename it tosketch.js
. - Create a
data.yaml
file.
You should end with a structure like this::
.
└── sketches/
└── my-sketch/
├── sketch.js
└── data.yaml
Making your sketch compatible with Ginpar
In your createCanvas
instruction, add .parent("artwork-container")
.
Now, you must be specifying the parameters.
Specifying the parameters
Each sketch is a directory that contains two files: sketch.js
and
data.yaml
. The data.yaml
file is where the parameters specification
takes place.
To create a parameters list, add this to your data file:
---
date: 2019-11-04
# ... other data
# ...
# Key that contains a list of parameters
params:
# The name of the parameter must be the key of the element
# It must match a variable in your sketch.js file
- MY_VARIABLE:
# Ginpar parameters definition keys. All optional.
# For a full list check the API
randomizable: True
name: My displayed variable name
# HTML valid attributes
attrs:
type: number
value: 30
step: 1
min: 0
max: 100
Once parsed, Ginpar will produce:
-
A form containing each of the items in the
parameters
list:<form> <div class="form-field"> <label for="my-variable"> My displayed variable name </label> <input name="my-variable" id="my-variable" type="number" value="30" step="1"> </div> <!-- More form-fields. One for each params element. ---> </form>
-
A JS code fragment to update each of the parameters using the form values:
function updateVars() { MY_VARIABLE = document.getElementByID("my-variable").value; // More variable updates. One for each params element. }
If the type of the input is a number
, Ginpar will parse it before
assigning it to the variable.
To use this parameters inside your sketch, just use the same name you used as key:
console.log(MY_VARIABLE)
// ==> 30
Serving & Building
Ginpar has two different commands to build your site:
ginpar build
Will build your site into the build_directory
path, which by default is
public
.
ginpar serve
Will start a new server on localhost:8000
and open your default web
browser. You can specify the port with --port
.
Check ginpar serve and ginpar build, or run
ginpar serve --help
, ginpar build --help
to see the full list of
options and arguments available.
Built With
- Jinja2 - Templating language.
- Click - CLI Tool composer.
- PyYAML - YAML framework.
- Livereload - Hot reloading server.
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
Contributors
- David Omar - Initial work - davidomarf
See also the list of contributors who participated in this project.
License
This project is licensed under the MIT License - see the LICENSE.md file for details
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.