SOS UiComponents

SOSUiComponents
SOS UiComponents - (c) @VinaiKopp - for #MageTitansIT, Milano, 06. April 2018

Alternative titles:
Lessons learned from UiComponents
or
My own best practices for UiComponents

I'm assuming you have at least a (very)
basic understanding of
— require.js
— Knockout.js
— jQuery UI Widgets
— UiComponents

UiComponents
So what is the problem?

For me grokking UiComponents was one
of the hardest things

It still takes me a long time to do some
things that I expect to be quick

I try to understand UiComponents mainly
by reading code
Reading Code > Reading Docs

So I try to optimize code for reading

This talk
1. A little bit of whining
2. General advice on readable code
3. View state management

Three issues I frequently encounter:
1. High cognitive load
2. Duplication of knowledge
3. State is coupled to the DOM

If it was my job...
..to ﬁx UiComponents

Cognitive load
Super verbose declaration
(no sane defaults)

Cognitive load
Mixing of concepts
(Knockout.js and jQuery UI Widgets)

Cognitive load
Inconsistent use in core

Self
Documenting
CodeSOS UiComponents - (c) @VinaiKopp - for #MageTitansIT, Milano, 06. April 2018

Rules I try to apply to code I write.
When working with the core code...
well, it is what it is.

4 Rules of simple design by Kent Beck:
1. Passes all tests
2. Reveals intent
3. No duplication
4. Fewest elements

Passes all tests
The code has to work.

Reveals intent

Reveals intent
Good naming
— Descriptive base class names
— Intent of functions, not
implementation
— Descriptive properties and variables

Reveals intent
bad:
interface ButtonProviderInterface
{
/**
* Retrieve button-specified settings
*
* @return array
*/
public function getButtonData();
}

Reveals intent
because:
public function getButtonData()
{
// ...
return [
'label' => __('Save'),
'class' => 'save primary',
'data_attribute' => [
'mage-init' => [
'buttonAdapter' => [
'actions' => [
[
'targetName' => 'product_form.product_form',
'actionName' => 'save',
'params' => [false]
]
]
]
]
],
'class_name' => Container::SPLIT_BUTTON,
'options' => $this->getOptions(),
];
}

Reveals intent
better:
interface ButtonProviderInterface
{
public function getLabel();
public function getCssClassNames();
public function getActions();
...
}

Reveals intent
bad:
{
getSortOrder: function () {
return this.order;
}
}

Reveals intent
good:
{
isDescending: function() {
return this.order === SORT_DESC;
},
isAscending: function() {
return this.order === SORT_ASC;
}
}

Reveals intent
Try to use a style familiar to
the most likely reader

Reveals intent
Favor UiComponent JSON over XML

Reveals intent
<item name="progressBar" xsi:type="array">
<item name="sortOrder" xsi:type="string">0</item>
<item name="component" xsi:type="string">Magento_Checkout/js/view/progress-bar</item>
<item name="displayArea" xsi:type="string">progressBar</item>
<item name="config" xsi:type="array">
<item name="deps" xsi:type="array">
<item name="0" xsi:type="string">checkout.steps.shipping-step.shippingAddress</item>
<item name="1" xsi:type="string">checkout.steps.billing-step.payment</item>
</item>
</item>
</item>

Reveals intent
{
"progressBar": {
"component": "Magento_Checkout/js/view/progress-bar",
"sortOrder": 0,
"displayArea": "progressBar",
"config": {
"deps": [
"checkout.steps.shipping-step.shippingAddress",
"checkout.steps.billing-step.payment"
]
}
}
}

No duplication

No duplication
Keep knowledge in one place

No duplication
Duplication is a common problem in M2
EAV, DataInterfaces, UiComponents,
GraphQL, ...
How does it apply in the view layer?

No duplication
Avoid selectors in view models
loginFormSelector = 'form[data-role=email-with-possible-login]',

No duplication
:'-(
miniCart.sidebar({
'targetElement': 'div.block.block-minicart',
'button': {
'checkout': '#top-cart-btn-checkout',
'remove': '#mini-cart a.action.delete',
'close': '#btn-minicart-close'
},
'showcart': {
'parent': 'span.counter',
'qty': 'span.counter-number',
'label': 'span.counter-label'
},
'minicart': {
'list': '#mini-cart',
'content': '#minicart-content-wrapper',
'qty': 'div.items-total',
'subtotal': 'div.subtotal span.price'
},
'item': {
'qty': ':input.cart-item-qty',
'button': ':button.update-cart-item'
}
});

No duplication
If selectors are required?
Keep the definition and the configuration
as close as possible,
ideally in the same file

No duplication
DOM selector declaration and conﬁg
<div data-bind="scope: 'foo'">
<div data-role="message-container">...</div>
</div>
<script type="text/x-magento-init">
{
"*": {
"Magento_Ui/js/core/app": {
"components": {
"foo": {
"component": "MyCompany_MyModule/js/view/foo",
"containerSelector": "div[data-role=message-container]"
}
}
}
}
}
</script>

No duplication
UiComponent selector declaration and conﬁg
<div data-bind="scope: 'messages'">
...
</div>
{
"*": {
"components": {
"messages": {
"component": "Magento_Theme/js/view/messages"
}
}
}
}
}
</script>

No duplication
Keep knowledge in one ﬁle and close together.
{
"*": {
"components": {
"appRoot": {
"component": "My_Module/js/root"
"children": {
"thingA": {
"component: "My_Module/js/thing-a"
},
"thingB": {
"component: "My_Module/js/thing-b",
"sibling":" "thingA"
}
}
}
}
}
}
}
</script>

No duplication
Injecting DOM-Nodes is better
E.g. with a custom binding:
<div data-bind="scope: 'myViewModel', bindDomNode: true">
</div>

No duplication
Custom binding handler declaration:
define(['ko'], function(ko) {
'use strict';
ko.bindingHandlers.bindDomNode = {
init: function(element, valueAccessor, _a, _b, bindingContext) {
if (valueAccessor()) {
bindingContext.$data.domNode = element;
}
}
};
});

No duplication
Example access of injected DOM node the view model:
this.domNode.getBoundingClientRect();

Fewest elements

Fewest elements
If something works,
expresses intent
and contains no duplicate knowledge,
don't split it further

Fewest elements
The Single Responsibility Principle is not
the Single Public Method Principle.

Fewest elements
If things are related, keep them together.

Managing
State

Context: Magento <= 2.2.2
Not a SPA/PWA
SRP with several frontend "components",
each with its own more or less
independent state.

We have three options.
1. Keep state in the DOM or
UiComponents
2. Pass state from root down to children
3. Keep state outside of the view

Example TicTacToe
https://github.com/Vinai/example-module-tictactoe

Example TicTacToe
Shamelessly stolen from https://reactjs.org/tutorial/tutorial.html

Example TicTacToe
Simple example for each approach to
managing shared state:
https://github.com/Vinai/example-module-tictactoe
$ git branch
* 0-in-component-state
1-pass-to-children
2-external-state

1. Keep state in the DOM or
UiComponents
E.g. jQuery or pure Knockout.js
Only for simplest, single component cases

1. State in the DOM
How is state stored in the DOM?
— Form element values
— CSS classes (e.g. "active" or "invalid")
— Inline styles (e.g. "display: none")
— Element attributes (e.g. disabled)

1. State in the DOM
DOM state storage is common with jQuery
self.element.off('submit');
// disable 'Add to Cart' button
addToCartButton = $(form).find(this.options.addToCartButtonSelector);
addToCartButton.prop('disabled', true);
addToCartButton.addClass(this.options.addToCartButtonDisabledClass);
form.submit();

1. State in UiComponents
Properties on the knockout view model
Shared state: imports, exports, links

1. State in UiComponents
Component.extend({
defaults: {
links: {
squares: '${ $.provider }:squares'
},
imports: {
xIsNext: '${ $.provider }:xIsNext',
winner: '${ $.provider }:winner'
}
},
square: function () {
return this.squares[this.squareIndex];
}
handleClick: function () {
const square = this.square();
if ('' === square() && !this.winner) {
square(this.xIsNext ? 'X' : 'O');
}
}
});

1. Shared state in DOM or UiComponents
Strong coupling through
cross-component dependencies

1. Derived state
In this approach state derived from one
model is o!en stored in another model

1. Derived State
updateFoo: function() {
this.foo = this.other.bar * this.other.bar;
}
// vs.
foo: function() {
return this.other.bar * this.other.bar;
}

E.g. pure react components
Works within one component hierarchy

2. Example from React TicTacToe
<Board
squares={current.squares}
onClick={i => this.handleClick(i)}
/>
class Board extends React.Component {
renderSquare(i) {
return (
<Square
value={this.props.squares[i]}
onClick={() => this.props.onClick(i)}
/>
);
}

Problem when state is required outside
one hierarchy

Not common in Magento 2

No callback on parent, only on child
Component.extend({
initContainer: function (parent) {
const state = parent.state;
this.cells = [...state.squares.keys()].map(function (i) {
return new Square({index: i, state: state});
});
return this._super(parent);
}
...
}

3. Keep state outside the view
E.g. Elm architecture, ﬂux, redux/vuex
Most versatile but needs more plumbing

3. Keep state outside the view
There are differences:
Naming, (im)mutability, 1 or 2 way data
flow, (F)RP, effects handling, amount of
architecture...
But there always is a single state storage

3. Separate state with UiComponents
State object with observable properties
define(['ko'], function (ko) {
'use strict';
return ko.track({
moves: [],
squares: [...Array(9).keys()].map(() => ko.observable('')),
xIsNext: true,
winner: false
});
});

3. Separate state with UiComponents
Require and use state container object
define(
['uiComponent', 'ticTacToeState'],
function (Component, state) {
'use strict';
return Component.extend({
...
handleClick: function () {
if ('' === this.value() && !state.winner) {
state.squares[this.index](state.xIsNext ? 'X' : 'O');
}
},
});
}
);

Example Breakout
https://github.com/Vinai/example-module-breakout

3. Multiple state storage objects
define(
['gameComponent', 'ballState', 'frameState', 'gameState'],
function (GameComponent, ball, frame, game) {
'use strict';
return GameComponent.extend({
initialize: function () {
this._super();
this.initDimensions(frame);
frame.width = function () {
return game.width * .98;
};
frame.height = function () {
return game.height * .80;
};
frame.left = function () {
return game.width * .01;
};
frame.top = function () {
return game.height * .19;
};
},
...

3. State outside the view
Beneﬁts:
— State is simple to share
— View models contain mostly only logic
— Less code
— Easier to understand
— More maintainable

Recommendations
for maintainable UiComponents...

The code needs to...
1. Pass all tests
2. Reveal intent
3. Contain no duplication
4. Have the fewest possible elements
5. Separate shared state from the view

Thanks to Kent Beck for his timeless
4 rules of simple design.
Thank you for your attention!

SOS UiComponents

Recomendados

Recomendados

Más contenido relacionado

Similar a SOS UiComponents

Similar a SOS UiComponents (20)

Más de vinaikopp

Más de vinaikopp (17)

Último

Último (20)

SOS UiComponents