easy-with-style v3.0.354

Easy with Style

Programmatic styles for Easy.

To find out what variant of CSS is supported, which is essential to know, please read the With Style readme file.

Installation

With npm:

npm install easy-with-style

You can also clone the repository with Git...

git clone https://github.com/djalbat/easy-with-style.git

...then install the dependencies with npm from within the project's root directory:

npm install

You can also run a development server, see the section on building later on.

Example

There is a small development server that can be run from within the project's directory with the following command:

npm start

The example will then be available at the following URL:

http://localhost:8888

The source for the example can be found in the src/example.js file and corresponding src/example folder. You are encouraged to try the example whilst reading what follows. You can rebuild it on the fly with the following command:

npm run watch-debug

The development server will reload the page whenever you make changes.

One last thing to bear in mind is that this package is included by way of a relative rather than a package import. If you are importing it into your own application, however, you should use the standard package import.

Usage

You must call the renderStyles() function after importing the view but before rendering it. Doing so ensures that the styles generated as a result of executing the view code are inserted into the DOM before the view itself.

import withStyle from 'easy-with-style';

import { Body } from 'easy';

import View from './view';

const { renderStyles } = withStyle;

const body = new Body();

renderStyles();

body.mount(

  <View />

);

Note that rendering the styles in this way is not done as part of the build process, you must explicitly call the renderStyles() function, ideally right before you attach the view to the body.

Creating primitive elements with style

All of the standard HTML elements are supported. For a complete list of tag names, see the tagNames.js file. You can create these elements, which are functional elements under the hood, as follows:

const Link = withStyle.a`

  color: ${white};
  text-decoration: none;

  @media (min-width: ${desktop}) {
    color: ${black};
  }

`;

Now you are free to use the Link element in the usual way. Note that expression interpolation is supported. For example, here colour and breakpoint variables have been used.

To learn more about template literals in general and expression interpolation in particular, see the relevant MDN page.

Creating functional elements with style

This can be done with the withStyle() function:

const Header = (properties) => {
  const { className } = properties;

  return (

    <header className={className}>

      ...

    </header>

  );
};

export default withStyle(Header)`

  ...

`;

Note that the className property is retrieved from the properties object and must be used as the value of the attribute of the same name on the outermost JSX element that the function returns.

Creating class elements with style

Creating your own elements by extending the Element or InputElement class, or any supported element class for that matter, is also relatively straightforward:

import { Element } from "easy";

class Div extends Element {
  static tagName = "div";

  ...

  static fromProperties(Class, properties) {
    if (properties === undefined) {
      properties = Class; ///

      Class = Div;
    }

    return Element.fromProperties(Div, properties);
  }
}

export default withStyle(Div)`

  ...

`;

The one caveat to be aware of is that the static fromProperties() factory method must be polymorphic as shown. This is because the anonymous class that the withStyle() method returns calls the fromProperties() method and expects this signature.

Extending the styles of elements with style

If all you want to do is to add further styles to an element, be it a primitive, functional or class element, simply wrap it in another withStyle() call:

const HeaderLink = withStyle(Link)`

  ...

`;

In this case the Link element will keep its own styles whilst the HeaderLink element will both inherit those styles and of course possess its own.

Elements with style and composition

Composing elements with style obviously causes no problems in general, aside from one small caveat. If you set the className property of an element with style, then you will overwrite the class name that has been given to it automatically. In the case of all functional and class elements with style, however, it is easy to recover the class name and incorporate it into your own:

const NavigationButton = (properties) => {
  const { className } = Button,
        { children } = properties;

  return (

    <Button className={`${className} navigation`}>
      {children}
    </Button>

  );
}

This situation occasionally arises when using placeholder class names, see below.

Class elements with style and class inheritance

Extending your own class elements with style involves nothing more than remembering the correct signature for the static fromProperties() factory method, there is nothing more to do:

class MainDiv extends Div {
  ...

  static defaultProperties = {
    className: "main"
  };

  static fromProperties(Class, properties) {
    if (properties === undefined) {
      properties = Class; ///

      Class = MainDiv;
    }

    return Div.fromProperties(MainDiv, properties);
  }
}

export default withStyle(MainDiv)`

  ...

`;

Note that the element has been given a class name by way of the static defaultProperties class field in the normal fashion. The automatically generated class name for the styles does not interfere with this process. Again this is an example of placeholder class names, see immediately below.

Placeholder class names

Class names are randomly generated hashes of around eight characters, and as such are far from ideal when debugging. It is best to add your own placeholder class names, therefore. For functional components the following pattern is recommended:

const MainHeader = (properties) => {
  const { className } = properties;

  return (

    <header className={`${className} main`}>

      ...

    </header>

  );
};

export default withStyle(MainHeader)`

  ...

`;

For class components there is nothing to do, just add your own placeholder class name by wa of the className property of the defaultProperties static class field, as above.

Placeholder class names make the association of DOM elements in your browser's developer tools with their corresponding components far easier.

An example of functional classes

Elements with style are great for working with styles relating to an element's functionality as opposed to just its appearance.

class Div extends Element {
  hide() {
    this.addClass('hidden');
  }

  display() {
    this.removeClass('hidden');
  }

  isHidden() {
    const hidden = this.hasClass('hidden');

    return hidden;
  }

  isDisplayed() {
    const hidden = this.isHidden(),
          displayed = !hidden;

    return displayed;
  }

  ...
}

export default withStyle(Div)`

  .hidden {

    display: none;

   }

`;

In the example above, for example, the element can be programmatically displayed and hidden.

Additional styles

There may be times when you need to add general styles to a page or target the children of DOM elements. In these cases you can make use of the renderStyle() method thus:

import withStyle from 'easy-with-style';   ///

const { renderStyle } = withStyle;

renderStyle(

  ...

);

This will create a separate style DOM element and place your style in there.

Building

Automation is thanks to npm scripts, have a look at the package.json file. The pertinent commands are:

npm run build-debug
npm run watch-debug

Contact

• james.smith@djalbat.com