OctoberCMS

Gulp build-scss-and-yml task

The build-scss-and-yml gulp task can be used to generate theme settings for octobercms using scss variables.

To include the task in your october project, export the gulp task build-scss-and-yml to your gulpfile's exports:

require('@ribajs/octobercms/dist/yaml');
var gulp = require("gulp");

exports.default = gulp.series("build-scss-and-yml");`

The build-scss-and-yml task consists of three other gulp tasks which are executed in series: build-yml, merge-yml, merge-with-october-yml

build-yml

The build-yml task takes every file matching ./assets/**/*.scss, and transforms them using the scssToOctoberYml gulp plugin. The output is stored with the respective file name in the ./build/tmp/ directory.

The ./build/ directory can be added safely to any .gitignore file.

Currently the only option to change the directories is editing the riba.js source files, but that might change in future releases.

merge-yml

The merge-yml task takes every file matching ./build/tmp/**/*.yml (usually all temporary files created by the build-yml task), and merges them into a single big ./build/bundle.yml. If there are any duplicates of yaml keys, this task is supposed to print a warnining. (not happening yet)

merge-with-october-yml

The merge-with-october-yml task combines the content of the ./build/bundle.yml file with a file named ./default_theme.yaml. The bundle.yml content is added under the yaml key input.form.tabs.fields, which is the default octobercms config field key using the tabs configuration.

Gulp scssToOctoberYml plugin

The scssToOctoberYml gulp plugin extracts octobercms config fields from a scss file, and returns it as a yaml configuration string.

Currently, there are no options but the input and output files can be specified using the gulp src() function and the dest() pipe:

import { src, dest, task } from "gulp";
import { scssToOctoberYml } from "./includes/scss-to-october";

task("build-yml", function buildExampleYmlFromScss() {
  return src("./assets/**/*.scss").pipe(scssToOctoberYml()).pipe(dest("./build/tmp/"));
});

The plugin tries to match scss variables and to transform their values into the octobercms theme settings format. Currently it is only possible to export one scss variable per line, lines containing more than one variable will be ignored.

To mark a variable for export, the following comment is required after the variable declaration:

Input

$my-scss-variable: #123123 !default; // octoberyml: {}

If no further options are supplied, the scssToOctoberYml plugin tries to guess default options.

Compiled output for the example above

my_scss_variable:
  default: "#123123"
  assetVar: my-scss-variable
  label: my scss variable
  type: colorpicker

The type is guessed by using the default value, currently it either defaults to colorpicker or text, depending on the content.

Further options can be supplied through the brackets. Custom options always overwrite the default guess of the plugin, and can be used to further customize the output.

The content of the brackets is parsed using Function() object which also allows to use loose json for the options string:

Input

$my-scss-variable: #123123 !default; // octoberyml: {key: "value"}

Any (octobercms configuration value) can be used, to allow a high extent of customization:

Input

$navigation-font: "primary" !default; // octoberyml: {tab: "Font options", type: "balloon-selector", label: "Navigation Font", options: {primary: "Primary", secondary: "Secondary", tertiary: "Tertiary"}}

Compiled output:

navigation_font:
  default: '"primary"'
  assetVar: navigation-font
  label: navigation font
  type: balloon-selector
  tab: Font options
  options:
    primary: Primary
    secondary: Secondary
    tertiary: Tertiary