Initialization¶

Description: The ctr Javascript API is a simple ECMAScript 2015 class exported under the js identifier. Accordingly, a ctr instance must be initialized with the new operator. During initialization, a global option Object can be passed to the new ctr instance to set initial options.

Example

// requirie, which that I admire
const CTR = require('ctr').js;
// kick it with the new kids and use an es2015 import
import {js as CTR} from 'ctr';

// ctr instance is initialized and ready to rock'n roll
const ctr = new CTR();

Notes

• For the time being, ctr is dependent on Stylus for syntactical structure, as such ctr is a synchronous operation
• As I mention previously, since ctr is not run-time, you must use a preprocessing step/hook like the ctr-loader
• Both YAML methods yaml and setYamlTransform are located in the YAML tab
• Any options passed to a new ctr instance will be merged with .ctrrc.yml
• For the sake of brevity I do not include the dance of initialization, i.e., const ctr = new CTR(); in the rest of the these examples

create¶

Description: The create method is the main squeeze. It creates and processes styles which are aggregated in the ctr instance as a Set.

Parameters

• create(<selector>, <data>)
• create(<selector>, <data>, [<option> | <transform>])
• create(<selector>, <data>, <option>, <transform>)
• create({<selector>: <data>})
  • Abstinent a selector the single Object parameter must be formatted in key-value pair fashion
  • The <option> and <transfrom> parameter can be used in the same interchangeable manner as illustrated above

Arguments

• <selector> String
  • Selector for ctr styles
• <data> Object | Template Literal | String
  • ctr styles
• <option> Object
  • Global ctr options such as the hover duration that will only be applied to the styles at hand
• <transform> Function | [Function, Function, ...]
  • Custom transform logic to be applied to rendered styles

Example

// (String, Object) -> (<selector>, <data>)
ctr.create('.test-1', {
  width: '200px'
});

// Option parameter
ctr.create('.test-2', {
  height: '400px',
  'hover-on': {
    color: 'red'
  }
}, {
  hover: {
    duration: '10s',
    ease: 'ease-in'
  }
});

const ctrResult = ctr.getResult();
// .test-1 {
//   width: 200px;
// }
// .test-2 {
//   height: 400px;
// }
// .test-2:hover {
//   color: #f00;
//   transition-delay: 0s;
//   transition-duration: 10s;
//   transition-property: color;
//   transition-timing-function: ease-in;
// }

// (Object) -> ({<selector>: <data>})
ctr.create({
  // selector
  '.test-1': {
    width: '200px',
    // stylus alpha built-in function
    background: 'alpha(red, 20%)'
  }
});

// Two separate styles, processed in the same ctr set instance
ctr.create({
  '.test-2': {
    height: '400px'
  },
  '.test-3': {
    height: '800px'
  }
});

const ctrResult = ctr.getResult();
// .test-1 {
//   width: 200px;
//   background: rgba(255,0,0,0.2);
// }
// .test-2 {
//   height: 400px;
// }
// .test-3 {
//   height: 800px;
// }

// NOTE: Processed through the YAML parser, white space sensitive
// (String, Template Literal) -> (<selector>, <data>)
ctr.create('.test-1', `
  width: 200px
`);

const ctrResult = ctr.getResult();
// .test-1 {
//   width: 200px;
// }

// NOTE: Processed through the YAML parser, white space sensitive
// (String, String) -> (<selector>, <data>)
ctr.create('.test-1', 'width: 200px');

const ctrResult = ctr.getResult();
// .test-1 {
//   width: 200px;
// }

Notes

• Shy away from using Literal’s and never use String’s unless you’re absolutely sure you know what you’re doing
  • If you wish to avoid the ugliness plight of JS Objects than YAML is your answer
• There is no limit on create, and the best part is once the style is created it’s cached in a Map so you can blaze like a bat out of hell
• Tests: /__tests__/cases-js/public-methods/create

getResult¶

Description: The getResult method returns the rendered CSS for the ctr instance. Once getResult is invoked the result Set is cleared.

Parameters

• getResult({<reset>: true, <raw>: false})
• getResult(<reset> = true, <raw> = false)

Arguments

• <reset> Boolean | true
  • Clear’s the result Set
• <raw> Boolean | false
  • Returns the raw Set of rendered styles

Example

ctr.create('.test-1', {
  width: '200px'
});

ctr.create('.test-2', {
  height: '400px'
});

const ctrResult = ctr.getResult();
// .test-1 {
//   width: 200px;
// }
// .test-2 {
//   height: 400px;
// }

ctr.create('.test-1', {
  width: '200px'
});

const ctrResOne = ctr.getResult();
// .test-1 {
//   width: 200px;
// }

ctr.create('.test-2', {
  height: '400px'
});

const ctrResTwo = ctr.getResult();
// .test-2 {
//   height: 400px;
// }

// Example: raw
ctr.create('.test-1', {
  width: '200px'
});

ctr.create('.test-2', {
  height: '400px'
});

//Returns the raw Set
let ctrResult = ctr.getResult({
  raw: true
});

// To convert the Set into a String
ctrResult = [...ctrResult.values()].join('');
// .test-1 {
//   width: 200px;
// }
// .test-2 {
//   height: 400px;
// }

// Example: reset
ctr.create('.test-1', {
  width: '200px'
});

const ctrResOne = ctr.getResult({reset: false});
// .test-1 {
//   width: 200px;
// }

ctr.create('.test-2', {
  height: '400px'
});

const ctrResTwo = ctr.getResult({reset: false});
// .test-1 {
//   width: 200px;
// }
// .test-2 {
//   height: 400px;
// }

Notes

• Alias: getRes
• Tests: /__tests__/cases-js/public-methods/get-result

getLastResult¶

Description: The getLastResult method returns the rendered CSS for the last result Set processed by the ctr instance. Unlike getResult by default it does not clear out the result Set.

Parameters

• getLastResult({<reset>: false, <raw>: false})
• getLastResult(<reset> = false, <raw> = false)

Arguments

• <reset> Boolean | false
  • Removes the last result Set, as in itself, from the result Set
• <raw> Boolean | false
  • Returns the raw Set of rendered styles

Example

ctr.create('.test-1', {
  width: '200px'
});

ctr.create('.test-2', {
  height: '400px'
});

const ctrResOne = ctr.getLastResult();
// .test-2 {
//   height: 400px;
// }

// Still returns both styles
const ctrResTwo = ctr.getResult();
// .test-1 {
//   width: 200px;
// }
// .test-2 {
//   height: 400px;
// }

// Example: reset
ctr.create('.test-1', {
  width: '200px'
});

ctr.create('.test-2', {
  height: '400px'
});

const ctrResOne = ctr.getLastResult({
  reset: true
});
// .test-2 {
//   height: 400px;
// }

// .test-2 will not be in the return
const ctrResTwo = ctr.getResult();
// .test-1 {
//   width: 200px;
// }

Notes

• Tests: /__tests__/cases-js/public-methods/get-last-result

setClass¶

Description: The setClass method sets (adds) a ctr class instance.

Parameters

• setClass(<class>, <data>)
• setClass(<class>, <data>, <option>)
• setClass({<class>: <data>})
  • Abstinent a class the single Object parameter must be formatted in key-value pair fashion
• setClass({<class>: <data>}, <option>)

Arguments

• <class> String
  • Class name
• <data> Object
  • Class styles
• <option> Object
  • <option>.overwrite Boolean | false
    • Overwrites any previous set class with the same class name

Example

// (String, Object) -> (<class>, <data>)
ctr.setClass('Gettin', {
  width: '200px'
});
ctr.setClass('Crazy', {
  height: '400px'
});


ctr.create('.test', {
  extend: 'Gettin',
  before: {
    extend: 'Crazy'
  }
});

const ctrResult = ctr.getResult();
// .test {
//   width: 200px;
// }
// .test::before {
//   height: 400px;
// }

// (Object) -> ({<class>: <data>})
ctr.setClass({
  MakeIt: {
    width: '200px'
  },
  Funky: {
    height: '400px'
  }
});

ctr.create('.test', {
  extend: 'MakeIt',
  before: {
    extend: 'Funky'
  }
});

const ctrResult = ctr.getResult();
// .test {
//   width: 200px;
// }
// .test::before {
//   height: 400px;
// }

Notes

• Alias: addClass
• In Javascript you can mock-up your own class data structure pretty easy so by no means should you feel locked-in, in this regard
• Tests: /__tests__/cases-js/public-methods/set-class

setOption¶

Description: The setOption method sets global ctr options to replace the defaults through merging the new options with the default options. These set global options are applied to all styles processed by the instance.

Parameters

• setOption(<option>)
• setOption({<ctrrc>: true, <once>: false, <overwrite>: false, <reset>: false})
• setOption(<option>, {<ctrrc>: true, <once>: false, <overwrite>: false, <reset>: false})

Arguments

• <option> Object
  • Global ctr options whose defaults are defined in .ctrrc.yml
• <ctrrc> Boolean | true
  • Overrides the default reset action of resetting back to the .ctrrc.yml regardless of if it exists or not
  • This option is to be used in conjunction with <reset>
• <once> Boolean | false
  • Sets the options to be applied once to the following instance and then disregarded
• <reset> Boolean | false
  • Resets all options set through setOption and reverts to the set defaults or the specified defaults defined in .ctrrc.yml
• <overwrite> Boolean | false
  • By default, a previous set option set through setOption can not be overwritten unless explicit permission is given

Example

// set option
ctr.setOption({
  hover: {
    duration: '10s'
  }
});

// create style
ctr.create('.test', {
  height: '200px',
  hover: {
    height: '400px'
  }
});

const crtResult = ctr.getResult();

/* ctrResult */

.test {
  height: 200px;
}
.test:hover {
  height: 400px;
  transition-delay: 0s;
  transition-duration: 10s;
  transition-property: height;
  transition-timing-function: cubic-bezier(0.42, 0, 0.58, 1);
}
.test:not(:hover) {
  transition-delay: 0s;
  transition-duration: 10s;
  transition-property: height;
  transition-timing-function: cubic-bezier(0.42, 0, 0.58, 1);
}

// set option only once
ctr.setOption({
  global: {
    sort: '-len'
  }
}, {once: true});

// sorted by '-len'
ctr.create('.test-1', {
  height: '200px',
  background: 'red'
});

//revets back to `len` sort
ctr.create('.test-2', {
  height: '200px',
  background: 'red'
});

const ctrResult = ctr.getResult();

/* ctrResult */

.test-1 {
  background: #f00;
  height: 200px;
}
.test-2 {
  height: 200px;
  background: #f00;
}

Notes

• Important: If you’re making heavy use of setOption it would be wise to utilize setReset due to the merging nature its action
• In practice, this should not be a replacement for .ctrrc.yml but rather used to target a set of styles and then reset
• Option priority: local > create <option> > setOption > .ctrrc.yml > default
• Tests: /__tests__/cases-js/public-methods/set-option

setReset¶

Description: The setReset method resets all or specific “set” methods set in setOption, setTransform, setVariable, setYamlTransfrom.

Parameters

• setReset()
• setReset({<variable>, <option>, <transform>, <yamlTransform>})

Arguments

• argumentless
  • Resets all “set” methods and reverts to the set defaults or the specified defaults defined in .ctrrc.yml
• <variable> Object | Boolean | false
  • New default variable, or to reset or not
• <option> Object | Boolean | false
  • New default options, or to reset or not
• <transform> Function | [Function] | Boolean | false
  • New default transformations, or to reset or not
• <yamlTransform> Function | [Function] | Boolean | false
  • New default YAML transformations, or to reset or not

Example

ctr.setVariable({
  width: '444px'
});

ctr.setOption({
  hover: {
    ease: 'ease-in'
  }
});

ctr.setTransform(function (css) {
  return css.toUpperCase();
});

ctr.setClass('Sorcery', {
  $$: {
    width: '200px'
  },
  'hover-on': {
    width: '$width$'
  }
});

// will have above "set's" applied
ctr.create('.test-1', {
  extend: 'Sorcery'
});

// reset all
ctr.setReset();

// will not have "set's" applied
ctr.create('.test-2', {
  extend: 'Sorcery'
});

const ctrResult = ctr.getResult();

/* ctrResult */

.TEST-1:HOVER {
  WIDTH: 444PX;
  TRANSITION-DELAY: 0S;
  TRANSITION-DURATION: 0.5S;
  TRANSITION-PROPERTY: WIDTH;
  TRANSITION-TIMING-FUNCTION: EASE-IN;
}
.test-2:hover {
  width: 200px;
  transition-delay: 0s;
  transition-duration: 0.5s;
  transition-property: width;
  transition-timing-function: cubic-bezier(0.42, 0, 0.58, 1);
}

Notes

• Alias: development
• Due to the design decision of not explicitly overwriting “set” methods, it would be advantageous to use setReset if you’re doing a great deal of “set” play during development
• Tests: /__tests__/cases-js/public-methods/set-reset

setTransform¶

Description: The setTransform method creates a hook in the render callback to allow for the transformation of the resulting CSS String.

Parameters

• setTransform({<reset>: false, <once>: false})
• setTransform(<transform>, {<reset>: false, <once>: false})

Arguments

• <transform> Function | [Function, Function, ...]
  • A single argument of the resulting CSS String is passed to the transform Function(s)
  • Functions are applied in the order they were received
  • Must return a String value otherwise disregarded
• <once> Boolean | false
  • Sets the transforms to be applied once to the following instance and then disregarded
• <reset> Boolean | false
  • Resets all transforms set through setTransform

Example

// make a design statement
ctr.setTransform(function (css) {
  return css.toUpperCase();
});

ctr.create('.test', {
  width: '200px',
  before: {
    content: 'can you even css?'
  }
});

const ctrResult = ctr.getResult();

.TEST {
  WIDTH: 200PX;
}
.TEST::BEFORE {
  CONTENT: "CAN YOU EVEN CSS?";
}

Notes

• Transform results are memoized
• Tests: /__tests__/cases-js/public-methods/set-transform

setVariable¶

Description: The setVariable method sets global variables that can be referenced through the variable String syntax: $<variable>$.

Parameters

• setVariable(<variable>)
• setVariable({reset: false, once: false, ctrrc: true, overwrite: false})
• setVariable(<variable>, {reset: false, once: false, ctrrc: true, overwrite: false})

Arguments

• <variable> Object
  • Sets global variables that can be resolved in both ctr instances and classes
• <ctrrc> Boolean | true
  • Overrides the default reset action of resetting back to the .ctrrc.yml regardless of if it exists or not
  • This option is to be used in conjunction with <reset>
• <once> Boolean | false
  • Sets the variables to be applied once to the following instance and then disregarded
• <reset> Boolean | false
  • Resets all variables set through setVariable and reverts to the specified variables defined in .ctrrc.yml if any exists
• <overwrite> Boolean | false
  • By default, a previous set variables set through setVariable can not be overwritten unless explicit permission is given

Example

// set
ctr.setVariable({
  width: '200px',
  height: '400px',
  // nesting is okie-doke
  mySecretColor: {
    sauce: '#eee'
  }
});

ctr.create('.test-1', {
  width: '$width$',
  height: '$height$',
  color: '$mySecretColor.sauce$'
});

ctr.create('.test-2', {
  width: '$width$',
  height: '$height$',
  color: '$mySecretColor.sauce$'
});

const ctrResult = ctr.getResult();
// .test-1 {
//   color: #eee;
//   width: 200px;
//   height: 400px;
// }
// .test-2 {
//   color: #eee;
//   width: 200px;
//   height: 400px;
// }

// set
ctr.setVariable({
  width: '200px'
});

ctr.create('.test-1', {
  width: '$width$'
});

// set once overwrite var
ctr.setVariable({
  width: '400px'
}, {once: true});

ctr.create('.test-2', {
  width: '$width$'
});

// .test-3 === .test-1
ctr.create('.test-3', {
  width: '$width$'
});


const ctrResult = ctr.getResult();
// .test-1 {
//   width: 200px;
// }
// .test-2 {
//   width: 400px;
// }
// .test-3 {
//   width: 200px;
// }

Notes

• Alias: setVar
• Not sure how much mileage you will get out of this method since you can easily create your own custom variable solution in Javascript, nevertheless, it’s available
• Goes hand in hand with YAML
• Tests: /__tests__/cases-js/public-methods/set-variable

writeFile¶

Description: The writeFile method is essentially a wrapper around fs.writeFileSync with other goodies packaged in to streamline the process of writing out the rendered results.

Parameters

• writeFile()
• writeFile(<option>)
• writeFile(<filePath>, <option>)

Arguments

• argumentless
  • If no filePath is specified a path is auto-generated which should work in most V8 environments
  • Under the hood, it uses Error.prepareStackTrace to obtain the last functions caller path which should be the ctr instance
  • [caller-file-path].js [caller-file-path].css
• <filePath> String
  • The absolute path for fs to write the style results to, including the file extension of .css
• <option> Object
  • <option>.callback Function | false
    • Callback is invoked right after the file is written with a single argument of the file path
    • Callback function is binded to the ctr instance
  • <option>.comment Boolean | String | true
    • If false, omits writing a comment completely
    • If String, replaces the default comment with the one specified
  • <option>.commentFile Boolean | String | true
    • Sets the CTR LOC commnet for the CSS file
    • If false, omits the file path comment generation.
    • If String, replaces file location with the one specified
  • <option>.dynamicPath Boolean | false
    • Returns the path with the inital / and .css removed so its a dynamic path to appease webpack
    • Example usage: require('/' + [path] + '.css')
  • <option>.fileName String | false
    • Uses the auto-generated path and replaces the file name with the specified fileName.
    • [caller-file-path]/[fileName].js [caller-file-path]/[specified-fileName].css
  • <option>.filePath String | false
    • Same as <filePath> argument just in the option Object
  • <option>.returnPath Boolean | false
    • Instead of returning the ctr instance it returns the path that the file was written to

Example

ctr.create('.test', {
  width: '200px'
});

// write file, auto-gen file location
ctr.writeFile();

/* --------------------------------------- *
 * NOTICE  : This CSS was generated by ctr *
 * DO NOT  : Do not, edit CSS directly     *
 * CTR LOC : [file-location].js            *
 * --------------------------------------- */


.test {
  width: 200px;
}

ctr.create('.test', {
  width: '200px'
});

// write file, custom comment
ctr.writeFile({
  comment: '/*My custom comment, yo!*/'
});

/*My custom comment, yo!*/


.test {
  width: 200px;
}

ctr.create('.test', {
  width: '200px'
});

// write file, no comment prepended
ctr.writeFile({
  comment: false
});

.test {
  width: 200px;
}

Notes

• If you wish or need to use this method I recommend you check out the tests for further examples
• Tests: /__tests__/cases-js/public-methods/write-file