|
| 1 | +# CSS class helper |
| 2 | + |
| 3 | +`PropsControl` provides you with a simple helper to assemble your component's CSS class names. |
| 4 | +The helper formats classes with [simplified BEM](https://github.com/inuitcss) syntax. |
| 5 | + |
| 6 | +## Base class |
| 7 | + |
| 8 | +Our component's base class name is defined in `getClassName` method. By default, it will create `dash-cased` class name |
| 9 | +from your component's control class, e.g `MyComponent` will result in `my-component`. |
| 10 | + |
| 11 | +If you wish to introduce a different way of creating your base class, |
| 12 | +or you simply want to define it manually, you can do it as follows: |
| 13 | + |
| 14 | +```php |
| 15 | +public function getClassName(): string |
| 16 | +{ |
| 17 | + return 'base-class'; |
| 18 | +} |
| 19 | +``` |
| 20 | + |
| 21 | +## Modifiers |
| 22 | + |
| 23 | +It's very common a component we create needs to modify its class name based on the data input. We can easily achieve |
| 24 | +this with `PropsControl` by defining `getClassNameModifiers` method. |
| 25 | + |
| 26 | +The method will return an array of our modifiers definitions. |
| 27 | + |
| 28 | +### Prop name |
| 29 | + |
| 30 | +The simplest way to use a prop as modifier is to include its name in the array: |
| 31 | + |
| 32 | +```php |
| 33 | +public function getClassNameModifiers(): array |
| 34 | +{ |
| 35 | + return [MyComponentProps::SOME_PROP]; |
| 36 | +} |
| 37 | +``` |
| 38 | + |
| 39 | +If `MyComponentProps::SOME_PROP` has a truthy value the **prop name** is used as a modifier. |
| 40 | + |
| 41 | +```html |
| 42 | +<div class="base-class base-class--some-prop"></div> |
| 43 | +``` |
| 44 | + |
| 45 | +### Prop value |
| 46 | + |
| 47 | +If you need to use the prop's value as a modifier instead, mark it with a constant predefined in `PropsControl`: |
| 48 | + |
| 49 | +```php |
| 50 | +public function getClassNameModifiers(): array |
| 51 | +{ |
| 52 | + return [MyComponentProps::SOME_PROP => self::USE_VALUE]; |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +If `MyComponentProps::SOME_PROP` has a truthy value the **value** is used as a modifier. |
| 57 | + |
| 58 | +```html |
| 59 | +<div class="base-class base-class--some-value"></div> |
| 60 | +``` |
| 61 | + |
| 62 | +### Custom modifiers |
| 63 | + |
| 64 | +You can also define custom modifiers using a callback function that will receive `Wavevision\PropsControl\ValidProps` |
| 65 | +object as an argument. |
| 66 | + |
| 67 | +```php |
| 68 | +public function getClassNameModifiers(): array |
| 69 | +{ |
| 70 | + return [ |
| 71 | + 'custom' => function (ValidProps $props): bool { |
| 72 | + if ($entity = $props->get(MyComponentProps::ENTITY)) { |
| 73 | + return $entity->enabled; |
| 74 | + } |
| 75 | + return false; |
| 76 | + }, |
| 77 | + fn (ValidProps $props): string => $props->get(MyComponentProps::IS_VALID) ? 'enabled' : 'disabled', |
| 78 | + ]; |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +It this example, `custom` will be used as a modifier if the callback returns `true`. |
| 83 | + |
| 84 | +The other callback shows we can also return a `string`, in that case the returned string is a modifier. |
| 85 | + |
| 86 | +```html |
| 87 | +<div class="base-class base-class--custom base-class--disabled"></div> |
| 88 | +``` |
| 89 | + |
| 90 | +## Formatting the CSS class |
| 91 | + |
| 92 | +Once you have defined everything and your component is being rendered, its template will be provided with |
| 93 | +`Wavevision\PropsControl\Helpers\ClassName` object in `$className` variable |
| 94 | +that serves as a formatter with predefined base class and its modifiers. |
| 95 | + |
| 96 | +The formatter has following methods publicly available: |
| 97 | + |
| 98 | +### `block(?string ...$modifiers): string` |
| 99 | + |
| 100 | +Formats a block class name with optional inline modifiers passed as parameters. |
| 101 | + |
| 102 | +### `element(string $className, ?string ...$modifiers): string` |
| 103 | + |
| 104 | +Formats an element class name as `base-class__$className` with optional inline modifiers passed as parameters. |
| 105 | + |
| 106 | +### `create(string $baseClass, bool $block = true, bool $excludeModifiers = false): ClassName` |
| 107 | + |
| 108 | +Creates a new formatter instance with a new base class. Useful for nested blocks inside your components. |
| 109 | + |
| 110 | +By default, the format is `base-class-$baseClass`. If `$block` is `false`, only `$baseClass` will be used. |
| 111 | + |
| 112 | +If `$excludeModifiers` is `true`, **no modifiers** defined in the component will be passed to the newly instantiated formatter. |
0 commit comments