Extending RTLCSS

Your guide on how to use and make the most out of RTLCSS

Time is Priceless, Caffeine is Not! Buy Me a Coffee ☕

Control Directives

Control directives are triggered by CSS comments found between declarations or statements (rules and at-rules). They support processing any node type and can target one node (self-closing) or a set of nodes (block-syntax).

  • Self-closing
.code {
/*rtl:ignore*/
direction:ltr;
/*rtl:ignore*/
text-align:left;
}
  • Block-syntax
.code {
/*rtl:begin:ignore*/
direction:ltr;
text-align:left;
/*rtl:end:ignore*/
}

Important
Control directives are NOT triggered by comments inside selectors, at-rule parameters, or declaration values.

§Control directive defintion object

The definition of a control directive has the following attributes:

  • expect {object}

    An object hash defining the node types this directive is excpected to process, where keys are strings of node types and values are booleans.

    • atrule: At-rule node.
    • comment: Comment node.
    • decl: Declaration node.
    • rule: Rule node.
    • self: Comment node that triggred the directive.

    Find out more about node types at PostCSS API documentation.

    Note: Omitted keys are considred to have a false value.

    "expect": { "rule" : true, "self" : true }
  • begin {function}

    The begin function is responsible for processing nodes of the expected types. It is executed each time a node with the excpected type is encountered.

    'begin': function (node, metadata, context) { ... }

    The begin function must return a boolean value to indicate if it is allowed to process this node by other directives or not.

    • true: prevent further processing.
    • false: allow further processing.
  • end {function}

    The end function is responsible for cleanup and deactivation. It is executed after processing the expected node (if it was self-closing) or when the directive end statement (block-syntax) is encountred.

    'end': function (node, metadata, context) { ... }

    The end functions must return a boolean value to indicate if the directive has finished and should be deactivated or not.

    • true: deactivate.
    • false: keep active.

§Example

Here is a complete example of a control directive definition to ignore processing of one node or a set of nodes.

It can be triggered via: /*rtl:ignore*/ or /*rtl:begin:ignore*/.

'ignore': {
// the expected node types
'expect': { 'atrule': true, 'comment': true, 'decl': true, 'rule': true },
// local variable to store ending node
'endNode': null,
// prevent processing all nodes except comments indicating the end of this directive
'begin': function (node, metadata, context) {
// find the ending node in case of self closing directive
if (!this.endNode && metadata.begin && metadata.end) {
var n = node
while (n && n.nodes) {
n = n.nodes[n.nodes.length - 1]
}
this.endNode = n
}
var prevent = true
if (node.type === 'comment' &&
(node.text === '!rtl:end:ignore' || node.text === 'rtl:end:ignore')) {
prevent = false
}
return prevent
},
// deactivate the directive if:
// 1. block directive and the node is comment
// 2. self closing directive and node is endNode
'end': function (node, metadata, context) {
if (metadata.begin !== metadata.end && node.type === 'comment' ||
metadata.begin && metadata.end && node === this.endNode) {
// clear ending node
this.endNode = null
// deactivate
return true
}
// keep ignoring
return false
}
}

PREVNEXT