Class: KssSection

kss.KssSection(dataopt)

A KssSection object represents a single section of a KssStyleGuide.

A section of a style guide can be used for:

  • a category of sub-sections, since sections are hierarchical
  • a component in a design
  • a mixin (or similar concept) of a CSS preprocessor

This class is normally accessed via the kss module:

const KssSection = require('kss').KssSection;

Constructor

new KssSection(dataopt)

Creates a KssSection object and stores the given data.

If passed an object, it will add the properties to the section.

Parameters:
Name Type Attributes Description
data Object <optional>

An object of data.

Source:

Methods

(private) _propertyHelper(propertyName, objectConstructor, propertiesopt) → {*}

Gets or adds nested objects of the section.

A common helper for .modifiers() and .parameters() methods.

Different types of arguments for properties will yield different results:

  • Object|Array: If the value is an array of objects or an object, the properties are added to this section.
  • undefined: Pass nothing to return all of the section's properties in an array.
  • integer: Use a 0-based index to return the section's Nth property.
  • string: Use a string to return a specific modifier by name.
Parameters:
Name Type Attributes Description
propertyName string

The name of property in KssSection.

objectConstructor Constructor

The constructor function for the type of object the property is.

properties * <optional>

Optional. The properties to set for the section.

Source:
Returns:

If properties is given, the KssSection object is returned to allow chaining of methods. Otherwise, the requested properties of the section are returned.

Type
*

colors(colorsopt) → {KssSection|string|boolean}

Gets or sets the colors of the section.

If the colors value is provided, the colors for this section is set. Otherwise, the colors of the section is returned.

Parameters:
Name Type Attributes Description
colors Array <optional>

Collection of color object.

Source:
Returns:

If colors is given, the KssSection object is returned to allow chaining of methods. Otherwise, the colors of the section is returned, or false if none.

Type
KssSection | string | boolean

custom(name, valueopt) → {KssSection|*}

Gets or sets a custom property of the section.

If the value is provided, the requested custom property of the section is set. Otherwise, the section's custom property with the name specified in the name parameter is returned.

Parameters:
Name Type Attributes Description
name string

The name of the section's custom property.

value * <optional>

Optional. The value of the section's custom property.

Source:
Returns:

If value is given, the KssSection object is returned to allow chaining of methods. Otherwise, the section's custom property, name, is returned.

Type
KssSection | *

customPropertyNames() → {Array.<string>}

Gets the list of custom properties of the section.

Note that this method will return the actual custom properties set for this section, and not all of the custom properties available for the entire style guide. Use KssStyleGuide.customPropertyNames() for that list.

Source:
Returns:

An array of the section's custom property names.

Type
Array.<string>

deprecated(deprecatedopt) → {KssSection|boolean}

Gets or sets the deprecated flag for the section.

If the deprecated value is provided, the deprecated flag for this section is set. Otherwise, the deprecated flag for the section is returned.

Parameters:
Name Type Attributes Description
deprecated boolean <optional>

Optional. The deprecated flag for the section.

Source:
Returns:

If deprecated is given, the KssSection object is returned to allow chaining of methods. Otherwise, the deprecated flag for the section is returned.

Type
KssSection | boolean

depth(depthopt) → {KssSection|number}

Gets or sets the depth of the section.

If the depth value is provided, the depth for this section is set. Otherwise, the depth of the section is returned.

Parameters:
Name Type Attributes Description
depth number <optional>

Optional. The depth of the section as a positive integer.

Source:
Returns:

If depth is given, the KssSection object is returned to allow chaining of methods. Otherwise, the depth of the section is returned.

Type
KssSection | number

description(descriptionopt) → {KssSection|string}

Gets or sets the description of the section.

If the description value is provided, the description for this section is set. Otherwise, the description of the section is returned.

Parameters:
Name Type Attributes Description
description string <optional>

Optional. The description of the section.

Source:
Returns:

If description is given, the KssSection object is returned to allow chaining of methods. Otherwise, the description of the section is returned.

Type
KssSection | string

experimental(experimentalopt) → {KssSection|boolean}

Gets or sets the experimental flag for the section.

If the experimental value is provided, the experimental flag for this section is set. Otherwise, the deprecated flag for the section is returned.

Parameters:
Name Type Attributes Description
experimental boolean <optional>

Optional. The experimental flag for the section.

Source:
Returns:

If experimental is given, the KssSection object is returned to allow chaining of methods. Otherwise, the experimental flag for the section is returned.

Type
KssSection | boolean

Gets or sets the header of the section, i.e. the first line in the description.

If the header value is provided, the header for this section is set. Otherwise, the header of the section is returned.

Parameters:
Name Type Attributes Description
header string <optional>

Optional. The header of the section.

Source:
Returns:

If header is given, the KssSection object is returned to allow chaining of methods. Otherwise, the header of the section is returned.

Type
KssSection | string

markup(markupopt) → {KssSection|string|boolean}

Gets or sets the markup of the section.

If the markup value is provided, the markup for this section is set. Otherwise, the markup of the section is returned.

Parameters:
Name Type Attributes Description
markup string <optional>

Optional. The markup of the section.

Source:
Returns:

If markup is given, the KssSection object is returned to allow chaining of methods. Otherwise, the markup of the section is returned, or false if none.

Type
KssSection | string | boolean

modifiers(modifiersopt) → {KssSection|KssModifier|Array.<KssModifier>|boolean}

Gets or adds modifiers of the section.

Different types of arguments will yield different results:

  • modifiers(Object|Array): If the value is an array of objects or an object, the modifiers are added to this section.
  • modifiers(): Pass nothing to return all of the section's modifiers in an array.
  • modifiers(Integer): Use a 0-based index to return the section's Nth modifier.
  • modifiers(String): Use a string to return a specific modifier by name.
Parameters:
Name Type Attributes Description
modifiers * <optional>

Optional. The modifiers of the section.

Source:
Returns:

If modifiers is given, the KssSection object is returned to allow chaining of methods. Otherwise, the requested modifiers of the section are returned.

Type
KssSection | KssModifier | Array.<KssModifier> | boolean

parameters(parametersopt) → {KssSection|KssParameter|Array.<KssParameter>|boolean}

Gets or adds parameters if the section is a CSS preprocessor function/mixin.

Different types of arguments will yield different results:

  • parameters(Object|Array): If the value is an array of objects or an object, the parameters are added to this section.
    • parameters(): Pass nothing to return all of the section's parameters in an array.
    • parameters(Integer): Use a 0-based index to return the section's Nth parameter.
    • parameters(String): Use a string to return a specific parameter by name.
Parameters:
Name Type Attributes Description
parameters * <optional>

Optional. The parameters of the section.

Source:
Returns:

If parameters is given, the KssSection object is returned to allow chaining of methods. Otherwise, the requested parameters of the section are returned.

Type
KssSection | KssParameter | Array.<KssParameter> | boolean

reference(referenceopt) → {KssSection|string}

Gets or sets the reference for the section.

If the reference value is provided, the reference for this section is set. Otherwise, the reference for the section is returned.

Parameters:
Name Type Attributes Description
reference string <optional>

Optional. The reference of the section.

Source:
Returns:

If reference is given, the KssSection object is returned to allow chaining of methods. Otherwise, the reference for the section is returned.

Type
KssSection | string

referenceNumber(referenceNumberopt) → {KssSection|string}

Gets or sets a numeric reference number for the section.

If the referenceNumber value is provided, the referenceNumber for this section is set.

If no parameters are given, this method returns a numeric reference number; if the style guide's references are already numeric (e.g. 2, 2.1.3, 3.2), then this method returns the same value as reference() does. Otherwise, an auto-incremented reference number will be returned.

Parameters:
Name Type Attributes Description
referenceNumber string <optional>

Optional. The auto-incremented reference number of the section.

Source:
Returns:

If referenceNumber is given, the KssSection object is returned to allow chaining of methods. Otherwise, the reference number of the section is returned.

Type
KssSection | string

referenceURI(referenceURIopt) → {KssSection|string}

Gets or sets the reference of the section, encoded as a valid URI fragment.

If the referenceURI value is provided, the referenceURI for this section is set. Otherwise, the referenceURI of the section is returned.

Parameters:
Name Type Attributes Description
referenceURI string <optional>

Optional. The referenceURI of the section.

Source:
Returns:

If referenceURI is given, the KssSection object is returned to allow chaining of methods. Otherwise, the referenceURI of the section is returned.

Type
KssSection | string

source(sourceopt) → {KssSection|Object}

Gets or sets the file information of the file where the section was originally found.

If the source parameter is provided, the source for this section is set. Otherwise, the source of the section is returned.

The source object contains the following information:

  • filename: The name of the file.
  • path: The full path of the file.
  • line: The line number where the KSS comment is found.
Parameters:
Name Type Attributes Description
source Object <optional>

The source file information where the section was originally found.

Source:
Returns:

If source is given, the KssSection object is returned to allow chaining of methods. Otherwise, the source of the section is returned.

Type
KssSection | Object

sourceFileName() → {string}

Gets the name of the file where the section was originally found.

Source:
Returns:

Returns the source file's path relative to the base path.

Type
string

sourceLine() → {string}

Gets the line number where the section was found in the original source file.

Source:
Returns:

Returns the source file's line number.

Type
string

styleGuide(styleGuideopt) → {KssStyleGuide|KssSection}

Gets or sets the KssStyleGuide object this KssSection is associated with.

If the styleGuide value is provided, the KssStyleGuide for this section is set. Otherwise, the KssStyleGuide of the section is returned.

Parameters:
Name Type Attributes Description
styleGuide KssStyleGuide <optional>

Optional. The KssStyleGuide that owns the KssSection.

Source:
Returns:

If styleGuide is given, the current KssSection object is returned to allow chaining of methods. Otherwise, the KssStyleGuide object the section belongs to is returned.

Type
KssStyleGuide | KssSection

toJSON() → {Object}

Return the KssSection as a JSON object.

Source:
Returns:

A JSON object representation of the KssSection.

Type
Object

weight(weightopt) → {KssSection|number}

Gets or sets the weight of the section.

If the weight value is provided, the weight for this section is set. Otherwise, the weight of the section is returned.

Parameters:
Name Type Attributes Description
weight number <optional>

Optional. The weight of the section as an integer.

Source:
Returns:

If weight is given, the KssSection object is returned to allow chaining of methods. Otherwise, the weight of the section is returned.

Type
KssSection | number