Info¶

One of the most powerful concepts when working with Objects is that of merging two or more Objects together to create a single Object. Consequently, the ability to merge an internal and/or external Object(s) into a ctr instance whose parts are the composition of Objects is incredibly powerful. On the other hand, merge, is one of the features that can create unnecessary confusion and complexity if you fly too close to the sun, so it’s best to use it sparingly.

Syntax¶

Description: merge is defined as a utility that merges internal and external Objects into a ctr instance.

ctr('<#selector>', {
  merge: <object>
  <...>: <...>
})

<#selector>
  merge: <object>
  <...>: <...>

<#selector> {
  <object:properties>: <object:values>;
  <...>: <...>;
}

Notes

• Regex: /^merge$/i
• The key property merges List values via concatenation if conflict otherwise List values are not merged
• merge does not merge the Object reference key while mergeWith does
  • merge: {x: {a: 1, b: 2}} = {a: 1, b: 2}
  • mergeWith: {x: {a: 1, b: 2}} = {x: {a: 1, b: 2}}

Internal¶

Description: The merge property can merge internal Local Varibles ($$.

ctr('.test', {
  $$: {
    myObject: {
      height: 200px
      background: red
    }
  }
  width: 200px
  merge: '$myObject$'
})

.test:
  $$:
    myObject:
      height: 200px
      background: red
  width: 200px
  merge: $myObject$

.test {
  width: 200px;
  height: 200px;
  background: #f00;
}

ctr('.test', {
  $$: {
    myObject: {
      height: 200px
      background: red
    }
  }
  width: 200px
  merge: '$myObject$'
})

.test {
  width: 200px;
  height: 200px;
  background: #f00;
}

.test:
  $$:
    myObject:
      height: 200px
      background: red
  width: 200px
  merge: $myObject$

External¶

Description: The merge property can merge external Objects.

$MyObject = {
  height: 200px
  background: red
}

ctr('.test', {
  width: 200px
  merge: $MyObject
})

.test {
  width: 200px;
  height: 200px;
  background: #f00;
}

$MyObject = {
  height: 200px
  background: red
}

ctr('.test', {
  width: 200px
  merge: $MyObject
})

.test {
  width: 200px;
  height: 200px;
  background: #f00;
}

Notes

• Also works with Javascript Objects
• Personally, I recommend you shy away from using external Objects in Stylus due to their global nature

Multiple¶

Description: A List value of Objects for the merge property merges the Objects in the order it is received.

ctr('.test', {
  $$: {
    objectA: {
      height: 400px
    }
    objectB: {
      hover: {
        on: {
          opacity: 1
        }
        non: {
          opacity: 0.5
        }
      }
    }
  }
  width: 200px
  merge: '$objectA$' '$objectB$'
})

.test:
  $$:
    objectA:
      height: 400px
    objectB:
      hover:
        on:
          opacity: 1
        non:
          opacity: 0.5
  width: 200px
  merge: [$objectA$, $objectB$]

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

ctr('.test', {
  $$: {
    objectA: {
      height: 400px
    }
    objectB: {
      hover: {
        on: {
          opacity: 1
        }
        non: {
          opacity: 0.5
        }
      }
    }
  }
  width: 200px
  merge: '$objectA$' '$objectB$'
})

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

.test:
  $$:
    objectA:
      height: 400px
    objectB:
      hover:
        on:
          opacity: 1
        non:
          opacity: 0.5
  width: 200px
  merge: [$objectA$, $objectB$]

Notes

• Merge does not overwrite the source or previous merged Object

Scoped¶

Description: The merge property can be used at any scoped level.

ctr('.test', {
  $$: {
    fontHeader: {
      font-family: 'Ubuntu'
    }
    fontBody: {
      font-family: 'Lato'
    }
    fontStyle: {
      font-weight: normal
      font-style: normal
      font-size: 1em
      color: black
    }
  }
  width: 200px
  font-size: 1.2em
  merge: '$fontHeader$' '$fontStyle$'
  'component-.bodyText': {
    color: gray
    merge: '$fontBody$' '$fontStyle$'
  }
})

.test:
  $$:
    fontHeader:
      font-family: Ubuntu
    fontBody:
      font-family: Lato
    fontStyle:
      font-weight: normal
      font-style: normal
      font-size: 1em
      color: black
  width: 200px
  font-size: 1.2em
  merge: [$fontHeader$, $fontStyle$]
  component-.bodyText:
    color: gray
    merge: [$fontBody$, $fontStyle$]

.test {
  color: #000;
  width: 200px;
  font-size: 1.2em;
  font-style: normal;
  font-family: Ubuntu;
  font-weight: normal;
}
.test > .bodyText {
  color: #808080;
  font-size: 1em;
  font-family: Lato;
  font-style: normal;
  font-weight: normal;
}

ctr('.test', {
  $$: {
    fontHeader: {
      font-family: 'Ubuntu'
    }
    fontBody: {
      font-family: 'Lato'
    }
    fontStyle: {
      font-weight: normal
      font-style: normal
      font-size: 1em
      color: black
    }
  }
  width: 200px
  font-size: 1.2em
  merge: '$fontHeader$' '$fontStyle$'
  'component-.bodyText': {
    color: gray
    merge: '$fontBody$' '$fontStyle$'
  }
})

.test {
  color: #000;
  width: 200px;
  font-size: 1.2em;
  font-style: normal;
  font-family: Ubuntu;
  font-weight: normal;
}
.test > .bodyText {
  color: #808080;
  font-size: 1em;
  font-family: Lato;
  font-style: normal;
  font-weight: normal;
}

.test:
  $$:
    fontHeader:
      font-family: Ubuntu
    fontBody:
      font-family: Lato
    fontStyle:
      font-weight: normal
      font-style: normal
      font-size: 1em
      color: black
  width: 200px
  font-size: 1.2em
  merge: [$fontHeader$, $fontStyle$]
  component-.bodyText:
    color: gray
    merge: [$fontBody$, $fontStyle$]

Notes

• If you adhered to the Don’t Repeat Yourself philosophy you can make your code as DRY as a bone

Set Variables¶

Description:The merge property can reffrance reference internal global variable Objets set in ctrSetVariable or in the .ctrrc.yml.

// sets internal ctr global variable 
ctrSetVariable({
  primaryColorPair: {
    color: red
    background: snow
  }
  secondaryColorPair: {
    color: blue
    background: antiquewhite
  }
})

ctr('.test', {
  width: 200px
  component-article: {
    component-h1: {
      merge: '$primaryColorPair$'
    }
    component-h3: {
      merge: '$secondaryColorPair$'
    }
  }
})

# sets internal ctr global variable
ctr:::setVariable:
  primaryColorPair:
    color: red
    background: snow
  secondaryColorPair:
    color: blue
    background: antiquewhite

.test:
  width: 200px
  component-article:
    component-h1:
      merge: $primaryColorPair$
    component-h3:
      merge: $secondaryColorPair$

.test {
  width: 200px;
}
.test > article > h1 {
  color: #f00;
  background: #fffafa;
}
.test > article > h3 {
  color: #00f;
  background: #faebd7;
}

// sets internal ctr global variable 
ctrSetVariable({
  primaryColorPair: {
    color: red
    background: snow
  }
  secondaryColorPair: {
    color: blue
    background: antiquewhite
  }
})

ctr('.test', {
  width: 200px
  component-article: {
    component-h1: {
      merge: '$primaryColorPair$'
    }
    component-h3: {
      merge: '$secondaryColorPair$'
    }
  }
})

.test {
  width: 200px;
}
.test > article > h1 {
  color: #f00;
  background: #fffafa;
}
.test > article > h3 {
  color: #00f;
  background: #faebd7;
}

# sets internal ctr global variable
ctr:::setVariable:
  primaryColorPair:
    color: red
    background: snow
  secondaryColorPair:
    color: blue
    background: antiquewhite

.test:
  width: 200px
  component-article:
    component-h1:
      merge: $primaryColorPair$
    component-h3:
      merge: $secondaryColorPair$