-
-
Notifications
You must be signed in to change notification settings - Fork 0
Assets
Brander's ability to generate assets is built on a task-based system which can be configured in the .branderrc file. These all follow the same general schema within the configuration:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"input": {
"type": "object",
"properties": {
"dir": { "type": "string" },
"files": {
"anyOf": [
{ "type": "string" },
{
"type": "array",
"items": { "type": "string" }
}
]
},
"format": { "type": "string" }
},
"required": [ "files" ]
},
"options": {
"type": "object",
"properties": {
"groupBy": { "type": "string" },
"sizes": {
"type": "array",
"items": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "string",
"pattern": "^\\s*\\d+\\s*([xX]\\s*\\d+)?\\s*$"
}
]
}
}
}
},
"output": {
"type": "object",
"properties": {
"dir": { "type": "string" },
"files": { "type": "string" },
"format": { "type": "string" }
},
"anyOf": [
{ "required": [ "files" ] },
{ "required": [ "format" ] }
]
},
"task": { "type": "string" }
},
"required": [
"input",
"task"
]
}The tasks are executed in the order in which they are declared within the configuration file. A task can only be executed for a single input and output format combination, however, you can simply declare multiple tasks for different formats. For example, the following configuration is invalid as the "input.files" configuration contains files of mixed formats:
{
"tasks": [
{
"task": "clean",
"input": {
"files": [
"logo/**/*.png",
"logo/**/*.min.svg"
]
}
}
]
}But this could easily by fixed by splitting that task up for each unique format:
{
"tasks": [
{
"task": "clean",
"input": {
"files": "logo/**/*.png"
}
},
{
"task": "clean",
"input": {
"files": "logo/**/*.min.svg"
}
}
]
}Tasks are split into three types: clean, convert, and optimize. The "task" configuration is used to identify one of these and the rest of the information is only needed to provide the specifics for that task. There are some variations with relating to the configuration between these types that will be explained further in the sections below.
TODO: Cover evaluated values (file.dir, file.name, option.groupBy)
clean tasks simply force deletes all of the input files found. These are generally declared before or after all other tasks, however, they can be declared at any point.
The "output" configuration is ignored entirely by this task type as there is no output generated as a result of its execution.
The following formats at supported by clean tasks:
| Input Format | Output Format |
|---|---|
| Any | Ignored |
Removes all PNG and optimized SVG files before doing anything else:
{
"tasks": [
{
"task": "clean",
"input": {
"files": "logo/**/*.png"
}
},
{
"task": "clean",
"input": {
"files": "logo/**/*.min.svg"
}
}
]
}This is good practice to ensure a clean slate each time Brander is executed.
convert tasks attempt to generated versions of all of the input files found in an entirely different format by converting them.
The "output" configuration is required, however, the "output.dir" configuration is entirely optional and output files will be written to the same directory as the original input file, by default. As for the "output.file" and "output.format" configurations; only one is required but both can be provided for ultimate control. When the "output.file" configuration is provided and the "output.format" configuration isn't, an attempt will be made to derive the latter from "output.files" by parsing the file extension. Likewise, if the "output.format" configuration is provided and the "output.file" configuration isn't, an attempt will be made to derive the latter from "output.format" and the input file (i.e. "<%= file.base(true) %>." + outputFile.format).
All convert tasks supports the "options.sizes" configuration which can be used to control the output files generated. For SVG to PNG conversion, this can be used to generate a PNG file for each size per input file. However, for PNG to ICO conversion, this can be used to specify the size of the input files that are being written to the single ICO file. The "options.groupBy" configuration can be useful for using a single task declaration to generate convert PNG files to multiple ICO files.
The following formats at supported by convert tasks:
| Input Format | Output Format |
|---|---|
png |
ico |
svg |
png |
Converts SVG files with 1:1 aspect ratio to PNG files:
{
"tasks": [
{
"task": "convert",
"input": {
"files": "logo/**/*.svg"
},
"output": {
"format": "png"
},
"options": {
"sizes": [
16,
32,
64,
128
256,
512,
1024
]
}
}
]
}Converts SVG files with 4:3 aspect ratio to PNG files:
{
"tasks": [
{
"task": "convert",
"input": {
"files": "banner/**/*.svg"
},
"output": {
"format": "png"
},
"options": {
"sizes": [
"400x300",
"1000x750"
]
}
}
]
}Creates an ICO file containing all PNG files:
{
"tasks": [
{
"task": "convert",
"input": {
"files": [
"logo/base/my-brand-logo-16x16.png",
"logo/base/my-brand-logo-32x32.png",
"logo/base/my-brand-logo-64x64.png",
"logo/base/my-brand-logo-128x128.png",
"logo/base/my-brand-logo-256x256.png"
]
},
"output": {
"format": "ico"
},
"options": {
"sizes": [
16,
32,
64,
128,
256,
]
}
}
]
}Creates an ICO file containing multiple multiple PNG files resized from each PNG input file:
{
"tasks": [
{
"task": "convert",
"input": {
"files": "logo/**/*-256x256.png"
},
"output": {
"format": "ico"
},
"options": {
"groupBy": "<%= file.dir %>",
"sizes": [
16,
32,
64,
128,
256,
]
}
}
]
}optimize tasks attempt to generate optimized versions of all of the input files found. These are generally declared after all other tasks in order to avoid conflicts with other task input file patterns, however, they can be declared at any point.
The "output" configuration is entirely optional, however, the "output.dir" and "output.files" configurations can be useful to control where the optimized files are written to. By default, the optimized version of each input file is written to the same directory as that file with name derived from it (i.e. "<%= file.base(true) %>.min<%= file.extension() %>").
The following formats at supported by optimize tasks:
| Input Format | Output Format |
|---|---|
svg |
Ignored |
Removes all previously optimized SVG files before re-generating them:
{
"tasks": [
{
"task": "clean",
"input": {
"files": "logo/**/*.min.svg"
}
},
{
"task": "optimize",
"input": {
"files": "logo/**/*.svg"
}
}
]
}This way we can easily avoid generating optimized versions of previously optimized files.