LIN3S Front Foundation

Base CSS and JS files for building views in LIN3S way.

Installation

The recommended and the most suitable way to install is through Yarn:

$ yarn add lin3s-front-foundation

or alternatively through NPM:

$ npm install --save lin3s-front-foundation

Usage - Available features

Async

This package will provide all asynchronous related implementations. For instance, Promise related ones.

Async.cancelablePromise( promise )

This method will wrap a Promise object and provide a cancel() method for canceling the inner Promise. We will access the original promise throught the promise property.

import {Async} from 'lin3s-front-foundation';
 
const aPromise = new Promise((resolve, reject) => {
  // ...
});
 
const aCancelablePromise = Async.cancelablePromise(aPromise);
 
aCancelablePromise.promise.then(resolvedObject => {
  // ...
});
 
aCancelablePromise.cancel();
// aCancelablePromise.promise has been rejected right after calling the cancel() method.

Browser

This package will provide all browser related implementations.

Browser.isIE11()

This method will tell us if the browser is Internet Explorer 11.

import {Browser} from 'lin3s-front-foundation';
 
const isIE11 = Browser.isIE11();

Dom

This package will provide all Dom related implementations.

import {Dom} from 'lin3s-front-foundation';

const currentHtmlLang = Dom.getHtmlLang();

console.log(currentHtmlLang);

Dom.getHtmlLang()

This method will return the html tag's lang attribute.

Dom.loadScript( scriptPath )

This method will load an script by the provided scriptPath and return us a Promise object. This promise will be resolved one the script has been loaded.

import {Dom} from 'lin3s-front-foundation';
 
const scriptPath = 'https://yourdomain.com/script-path.js';
 
const scriptLoadPromise = Dom.loadScript(scriptPath);

scriptLoadPromise.then(() => {
  // Our script has been loaded!
});

Dom.injectScript( scriptCode, domNode = document.body )

This method will inject the specified scriptCode at the passed domNode. domNode will be the document's body by default. Provided scriptCode will be wrapped with an IIFE

import {Dom} from 'lin3s-front-foundation';
 
const 
  mainDomNode = document.querySelector('.main'),
  testScriptA = `console.log('This is the injected script A');`,
  testScriptB = `console.log('This is the injected script B');`;

Dom.injectScript(testScriptA);
Dom.injectScript(testScriptB, mainDomNode);

Dom.waitImagesLoadInDomNode( domNode )

This method will return us a Promise object that will be resolved once all the images contained in the provided domNode have been loaded.

import {Dom} from 'lin3s-front-foundation';
 
const imagesCollection = document.querySelector('.images__collection');
 
const imagesLoadPromise = Dom.waitImagesLoadInDomNode(imagesCollection);
 
imagesLoadPromise.then(() => {
  // All images have been loaded!
});

Dom.scrollToElement( selector, {duration = 500, offset = 0, callback = null} )

This method will scroll to the given element's positions minus offset in the given duration (in milliseconds). A callback can be provided that will trigger once the animation has finished.

import {Dom} from 'lin3s-front-foundation';

const callback = () => console.log('Scroll to element done!');

Dom.scrollToElement('.some-selector', {duration: 2000, offset: 10, callback});

Dom - Utilities / Helpers

Dom.isDomNodeDescendantOfDomNode( needleDomNode, mainDomNode )

This method will return true if the passed needleDomNode y a descendant of the mainDomNode.

Dom.getDomNodeIndex( domNode, selector = null )

This method will return the index of the provided domNode, optinally filtered by a css selector. It is a native alternative to the jQuery's .index() method.

Dom.removeDomNodes( domNodes )

This method will remove the passed domNodes from their parents. It will work with a single node as well. It is a native alternative to the jQuery's .remove() method.

Dom.addSelectorFilteredEventListener( domNode, eventName, selector, event => {} )

This method will add an event listener for the eventName to the passed domNode, filtering the event.target with the defined selector. It is a native alternative to the jQuery's .on(eventName, selector, callback) method when filtering it's targets by a selector.

Dom.dispatchNativeEvent( domNode, eventName )

This method will dispatch a DOMElement native event. It's a native alternative to the jQuery's .trigger(eventName) method.

Dom.scrollToElement( selector, {duration = 500, offset = 0, callback = null} )

This method will help us scrolling to a document node's position. It allows defining a duration (default 500ms), an offset (default 0) and a complete callback (default null).

import {Dom} from 'lin3s-front-foundation';
  
const links = document.querySelectorAll('.menu__list .menu__link');
  
const handleClick = event => Dom.scrollToElement(event.target.hash, {duration: 250, offset: 10});
  
Array.from(links, link => {
  link.addEventListener('click', handleClick, false);
});

Cookies

This package will provide all document.cookie related implementations.

Cookies.read

This method will return the value of a cookie by its name.

import {Cookies} from 'lin3s-front-foundation';

const cookieValue = Cookies.read('some-name');

Cookies.write

This method will write a cookie. Accepts an object with names parameters for name, value, expiration, domain and path.

import {Cookies} from 'lin3s-front-foundation';

Cookies.write({
  name: 'some-name',
  value: 'my value',
  expiration: 3600000, // 1 hour in milliseconds
  domain: 'example.com',
  path: '/'
});

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:----------------------|:----------|:------------------| | name | string | yes | - | | value | string | no | '' | | expiration | int (milliseconds) | no | * | | domain | string | no | location.hostname | | path | string | no | / |

* It will set cookie expiration to 'Session'

Cookies - EventBus events

Cookies.write will publish CookieWrittenEvent through the EventBus. We will subscribe to this event using some exported helper methods:

import {EventBus} from 'lin3s-front-foundation';

EventBus.onCookieWritten(({cookie}) => {
  const myCookieName = cookie.name;
  const myCookieValue = cookie.value;
});

Usage - Available UI components

GMap

This component will provide all the necessary implementations for displaying a Google Map, setting it's markers, setting a clusterer, use the Google Map geocoding feature and displaying the MarkerDetail view.

GMap - Styles

The GMap component comes with some default styles. You must include them in order to correctly render it.

@import './node_modules/lin3s-front-foundation/dist/scss/ui/components/gmap';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/components/gmap-marker-detail';

GMap - Basic setup

In order to setup the GMap component, we will define every required parameter while including the twig template. It will automatically fetch the needed js files and will init the Google Maps map instance.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:--------|:---------|:--------------| | gmap_api_key | string | yes | - | | gmap_center_lat | float | yes | - | | gmap_center_lng | float | yes | - | | gmap_initial_zoom | int | no | 8 | | gmap_max_zoom | int | no | 12 | | gmap_marker_default_path | string | yes | - | | gmap_marker_selected_path | string | yes | - | | gmap_marker_group_path | string | yes | - | | gmap_marker_width | int | yes | - | | gmap_marker_height | int | yes | - | | gmap_cluster_enabled | int | no | 1 [0,1] | | gmap_cluster_text_offset_x| int | no | 0 | | gmap_cluster_text_offset_y| int | no | 0 | | gmap_cluster_text_color | string | no | '#ffffff' | | gmap_cluster_text_size | int | no | 18 | | gmap_style | string | no | view** |

** In order to generate the Google Map custom styles, we could use any available tool. For instance the snazzy maps online platform.

The marker images will be required to be served both on .png and .svg formats.

The marker paths must be defined without the file extensions, as the GMap component will get the .png or .svg files based on the client browser.

This is a basic setup example:

{% include '@lin3s_front_foundation/components/gmap.html.twig' with {
    gmap_api_key: 'AIzaSyDQaCE_7C5iAmpwr_y1C1DHbtZsqag74Sk',
    gmap_center_lat: '43.2631394',
    gmap_center_lng: '-2.9275847',
    gmap_initial_zoom: 12,
    gmap_max_zoom: 16,
    gmap_marker_default_path: '/images/gmap/marker-default',
    gmap_marker_selected_path: '/images/gmap/marker-selected',
    gmap_marker_group_path: '/images/gmap/marker-group',
    gmap_marker_width: 40,
    gmap_marker_height: 60,
    gmap_cluster_enabled: 1,
    gmap_cluster_text_size: 14,
    gmap_cluster_text_color: '#222222'
} %}

GMap - JS API

These are the mostly used methods available on the GMap component's instance.

| Name | Parameters | Returned value | Description | |--------------------------------|:----------------------|:------------------|:------------| | setCenterOffsets | {      x: 0,      y: 0 } | undefined (void) | This method will set the instance's center's offset (in pixels) | | setMarkers | markers: [{      id: 0,      lat: 43.2631394,      lng: -2.9275847,      // your properties... }, //... ] | undefined (void) | This method will display the passed markers on the map. It will generate the clusters automatically. Each marker object must, at least, have the lat, lng and id properties. | | showMarkerDetailView | markerId, markerDetailHtmlContent | undefined (void) | This method will render and display the passed markerDetailHtmlContent centered on the correspondingn marker. | | hideMarkerDetailView | - | undefined (void) | This method will hide the currently visible marker detail view. | | geocodeAddress | address: String | undefined (void) | This method will geocode the passed address (Address, town, ZIP code, city...) and center the map on the result's location. If no result matches the passed address, it will publish an event through the EventBus. | | resetMapZoomAndCenterToDefault | - | undefined (void) | This method will reset the instance's center and zoom to the default values. |

GMap - EventBus events

Each GMap instance will publish these events through the EventBus. We will subscribe to these events using some exported helper methods:

import {EventBus} from 'lin3s-front-foundation';

const domNode = document.querySelector('.my-map');

EventBus.onGMapInitialized(domNode, gmapInitializedEvent => {
  const gmapInstance = gmapInitializedEvent.gmapInstance;
});

EventBus.onGMapGeocode(domNode, gmapGeocodeEvent => {
  console.log(gmapGeocodeEvent.status);
  console.log(gmapGeocodeEvent.results);
});

EventBus.onGMapMarkerSelected(domNode, gmapMarkerSelectedEvent => {
  const selectedMarker = gmapMarkerSelectedEvent.marker;
});

| Type | Properties | |--------------------------------|:------------------------| | GMapInitializedEvent | gmapInstance: GMap | | GMapMarkerSelectedEvent | gmapInstance: GMapmarker: Your marker object representation | | GMapGeocodeEvent | gmapInstance: GMapstatus: response statusresults: geociding results |

GMap - Advanced features

If we need to work with the initialized GMap component instance, we must subscribe to the GMapInitializedEvent, that will be published through the event-bus once the gmap component has been initialized.

import {EventBus} from 'lin3s-front-foundation';

const domNode = document.querySelector('.my-map');

EventBus.onGMapInitialized(domNode, gmapInitializedEvent => {
  const gmapInstance = gmapInitializedEvent.gmapInstance;
  // whatever...
});

We will set the GMap component's markers calling the setMarkers(markers) method.

If we want to use the built-in geocoding feature, we will call the geocodeAddress(address) of the GMap instance.

The GMap component also comes with methods for displaying/hiding the marker detail view ( showMarkerDetailView(markerId, markerDetailContentHtml) and hideMarkerDetailView()).

This is a complete example of the component's features:

import {EventBus} from 'lin3s-front-foundation';

class GMapTest {
  constructor(domNode) {
    this.domNode = domNode;
  
    EventBus.onGMapInitialized(this.domNode, gmapInitializedEvent => {
      const gmapInstance = gmapInitializedEvent.gmap;
      this.setupMarkers();
      this.init();
    });
  }
  
  setupMarkers() {
    const markers = [{
      id: 0,
      lat: 43.2631394,
      lng: -2.9275847
    }];

    this.gmapInstance.setMarkers(markers);
  }
  
  init() {
    this.filterInput = document.querySelector('.my-input-class'); 
    this.filterInput.addEventListener('input', () => {
      this.gmapInstance.geocodeAddress(this.filterInput.value);
    });
    
    EventBus.onGMapGeocode(this.domNode, gmapGeocodeEvent => {
      console.log(gmapGeocodeEvent.status);
      console.log(gmapGeocodeEvent.results);
    });
    
    EventBus.onGMapMarkerSelected(this.domNode, gmapMarkerSelectedEvent => {
      this.onMarkerSelected(gmapMarkerSelectedEvent.marker);
    });
  }
  
  onMarkerSelected(marker) {
    if (marker === undefined) {
      this.gmapInstance.hideMarkerDetailView();
    } else {
      this.gmapInstance.showMarkerDetailView(
        marker.id,
        `<h3>This is the marker detail's inner html content</h3>
         <p>Marker <b>lat</b>: ${marker.lat}</p>
         <p>Marker <b>lng</b>: ${marker.lng}</p>`
      );
    }
  }
}

onDomReady(() => {
  new GMapTest();
});

FormGroupInput

The component is composed by the FormLabel, FormInput and the FormError atoms.

FormGroupInput - Styles

The FormGroupInput component and it's associated atoms come with some default styles. You must include them in order to correctly render them.

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-label';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-error';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-input';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/components/form-group-input';

FormGroupInput - Basic setup

In order to setup the FormGroupInput component, we will define every required parameter while including the twig template.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |------------------------- |:--------------|:---------|:--------------| | input_id | string | yes | | | input_name | string | no | null | | input_value | string | no | null | | input_required | int | no | 0 | | input_validate | int | no | 0 | | input_validation_pattern | string | no | '' | | input_validation_type | string | no | '' | | input_type | string | no | 'text' | | input_placeholder | string | yes | - | | input_label_class_name | string | no | null | | input_label_modifiers | string | no | null | | input_label_content | html | no | null | | input_errors | array{    content: string*,     modifiers: string} | no | null | | input_class_name | string | no | null | | input_modifiers | string | no | null | | input_spinner | int | no | 0 |

This is a common setup example:

{% include '@lin3s_front_foundation/components/form_group_input.html.twig' with {
    input_id: 'my-form-user-name',
    input_required: 1,
    input_validate: 1,
    input_validation_type: 'phone',
    input_type: 'text',
    input_placeholder: 'Enter some data...',
    input_label_content: 'Your user name',
    input_errors: [{
        content: 'This field is required',
        modifiers: 'form-error--not-filled'
    }, {
        content: 'Entered phone is not a 9 digit valid phone',
        modifiers: 'form-error--not-valid'
    }],
    input_spinner: 1
} %}

FormGroupSelect

This component and it's associated FormSelect atom will build a custom rich select component. The component is composed by the FormSelect, FormLabel, FormInput and the FormError atoms.

FormGroupSelect / FormSelect - Styles

The FormGroupSelect component and it's associated atoms come with some default styles. You must include them in order to correctly render them.

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-label';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-error';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-input';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-select';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/components/form-group-select';

FormGroupSelect - Basic setup

In order to setup the FormGroupSelect component, we will define every required parameter while including the twig template.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | Purpose | |-------------------------- |:--------------|:---------|:--------------|:--------------| | select_id | string | yes | | | | select_name | string | no | null | | | select_required | int | no | 0 | | | select_validate | int | no | 0 | | | select_validation_pattern | string | no | '' | Any valid RegExp pattern | | select_validation_type | string | no | '' | Built-in validatory validation types ['email', 'phone', 'any'] | | select_mobile_breakpoint | int | no | 1024 | | | select_max_height_mobile | int | no | 260 | | | select_max_height_desktop | int | no | 420 | | | select_is_filterable | int | no | 1 | | | select_filter_placeholder | string | no | null | | | select_filter_order_by | string | no | 'value' | If you set 'label' as this parameter, the component will order it's items by the 'label' while filtering it's options. | | select_label_modifiers | string | no | null | | | select_label_content | html | no | null | | | select_errors | array{    content: string*,     modifiers: string} | no | null | | | select_select_modifiers | string | no | null | | | select_no_selection_label | string | no | '--' | | | select_no_selection_value | string | no | '--' | | | select_options | array | yes | | These are the component's options. Each option must have, at least, this shape: {    value: string*    label: string*    selected: int=0} | | select_outside_click_to_close_enabled | int | no | 1 | |

This is a full setup example:

{% set my_select_options = [{
    label: Male,
    value: 0,
    selected: 1
}, {
    label: Female,
    value: 1
}] %}

{% include '@lin3s_front_foundation/components/form_group_select.html.twig' with {
    select_id: 'my-select',
    select_required: 1,
    select_validate: 1,
    select_validation_pattern: '^(?!.*--).*$',
    select_mobile_breakpoint: 768,
    select_max_height_mobile: 260,
    select_max_height_desktop: 420,
    select_is_filterable: 1,
    select_filter_placeholder: 'Type to filter...',
    select_filter_order_by: 'label',
    select_label_modifiers: null,
    select_label_content: 'My select\'s label',
    select_errors: [{
        content: 'This field is required',
        modifiers: 'form-error--not-filled'
    }, {
        content: 'You cannot select the default value',
        modifiers: 'form-error--not-valid'
    }],
    select_select_modifiers: null,
    select_no_selection_label: '--',
    select_no_selection_value: '--',
    select_options: my_select_options
} %}

FormSelect - JS API

These are the mostly used methods available on the FormSelect atom's instance.

| Name | Parameters | Returned value | Description | |--------------------------------|:----------------------|:------------------|:------------| | open | - | undefined (void) | This method will open the select | | close | - | undefined (void) | This method will close the select | | update | {    options,    publishEvent: true} | undefined (void) | This method will update the FormSelect's options with the provided ones. By default it will publish the FormSelectOptionSelectedEvent. Each option object must, at least, have the label and value properties. | | enable | - | undefined (void) | This method will enable the select | | disable | - | undefined (void) | This method will disable the select |

FormSelect - EventBus events

Each FormSelect instance will publish these events through the EventBus. We will subscribe to these events using some exported helper methods:

import {EventBus} from 'lin3s-front-foundation';

const domNode = document.querySelector('.my-form-select');

EventBus.onFormSelectInitialized(domNode, formSelectInitializedEvent => {
  const formSelectInstance = formSelectInitializedEvent.formSelectInstance;
});

EventBus.onFormSelectOptionSelected(domNode, formSelectOptionSelectedEvent => {
  const selectedValue = formSelectOptionSelectedEvent.optionValue;
});

EventBus.onFormSelectStateChanged(domNode, formSelectStateChangedEvent => {
  const formSelectState = formSelectStateChangedEvent.state;
});

| Type | Properties | |--------------------------------|:-------------------------------| | FormSelectInitializedEvent | formSelectInstance: FormSelect | | FormSelectOptionSelectedEvent | formSelectInstance: FormSelectmarker: Your marker object representation | | FormSelectStateChangedEvent | formSelectInstance: FormSelectstate: [FormSelect.STATE.OPENED | FormSelect.STATE.CLOSED] |

FormGroupTextarea

The component is composed by the FormTextarea, FormLabel and the FormError atoms.

FormGroupTextarea - Styles

The FormGroupTextarea component and it's associated atoms come with some default styles. You must include them in order to correctly render them.

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-label';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-error';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-textarea';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/components/form-group-textarea';

FormGroupTextarea - Setup

In order to setup the FormGroupTextarea component, we will define every required parameter while including the twig template.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | Purpose | |---------------------------- |:--------------|:---------|:--------------|:--------------| | class_name | string | no | null | | | modifiers | string | no | null | | | textarea_id | string | no | null | | | textarea_name | string | no | null | | | textarea_value | string | no | null | | | textarea_required | int | no | 0 | | | textarea_validate | int | no | 0 | | | textarea_validation_pattern | string | no | '' | Any valid RegExp pattern | | textarea_validation_type | string | no | '' | Built-in validatory validation types ['email', 'phone', 'any'] | | textarea_label_class_name | string | no | '' | | | textarea_label_modifiers | string | no | '' | | | textarea_label_content | html | no | null | | | textarea_errors | array{    content: string*,     modifiers: string} | no | null | | | textarea_modifiers | string | no | '' | | | textarea_placeholder | string | no | '' | | | textarea_spinner | int | no | 0 | |

This is a full setup example:

{% include '@lin3s_front_foundation/components/form_group_textarea.html.twig' with {
    textarea_id: 'palindrome',
    textarea_required: 1,
    textarea_validate: 1,
    textarea_validation_pattern: '\\b(\\w)?(\\w)\\w?\\2\\1', {# Note that backslashes must be escaped (\ -> \\) #},
    textarea_label_content: '2-5 letter palindrome',
    textarea_errors: [{
        content: 'This field is required',
        modifiers: 'form-error--not-filled'
    }, {
        content: 'Entered text does not include a valid 2-5 letter palindrome',
        modifiers: 'form-error--not-valid'
    }],
    textarea_spinner: 1
} %}

FormGroupCheckbox

The component is composed by the FormCheckbox, FormLabel and the FormError atoms.

FormGroupCheckbox - Styles

The FormGroupCheckbox component and it's associated atoms come with some default styles. You must include them in order to correctly render them.

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-label';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-error';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-checkbox';
@import './node_modules/lin3s-front-foundation/dist/scss/ui/components/form-group-checkbox';

FormGroupCheckbox - Setup

In order to setup the FormGroupCheckbox component, we will define every required parameter while including the twig template.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | Purpose | |---------------------------- |:--------------|:---------|:--------------|:--------------| | class_name | string | no | null | | | modifiers | string | no | null | | | checkbox_id | string | no | null | | | checkbox_name | string | no | null | | | checkbox_required | int | no | 0 | | | checkbox_validate | int | no | 0 | | | checkbox_label_class_name | string | no | '' | | | checkbox_label_modifiers | string | no | '' | | | checkbox_label_content | html | no | null | | | checkbox_errors | array{    content: string*,     modifiers: string} | no | null | | | checkbox_modifiers | string | no | '' | | | checkbox_content | string | yes | | |

This is a full setup example:

{% include '@lin3s_front_foundation/components/form_group_checkbox.html.twig' with {
    checkbox_id: 'palindrome',
    checkbox_required: 1,
    checkbox_validate: 1,
    checkbox_content: 'I hace read and accept the terms and conditions',
    textarea_errors: [{
        content: 'Yout must accept the terms and conditions',
        modifiers: 'form-error--not-filled'
    }]
} %}

Usage - Available UI (React) components

FormGroupSelect (React) component

This React component will build a FormGroupSelect (vanilla) counterpart.

FormGroupSelect (React) - Basic setup

This is a controlled component. For a full initialization example, take a look at the provided example initialization and FormGroupSelect use case.

Usage - Available UI atoms

FormLabel

This atom will render an html <label> with some custom attributes.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:--------------|:---------|:--------------| | label_for | string | no | null | | label_required | int | no | 0 | | label_class_name | string | no | null | | label_modifiers | string | no | null | | label_content | html | yes | - |

This is a common setup example:

{% include '@lin3s_front_foundation/atoms/form_label.html.twig' with {
    label_for: 'user-email',
    label_required: 1,
    label_content: 'Email:'
} %}

FormLabel - Customization

In order to customize the atom's appearance, you should define these variables before importing the involved scss file.

$form-label-text-color: #222 !default;
$form-label-text-color-required: #f00 !default;
$form-label-font-family: sans-serif !default;
$form-label-font-size: 16px !default;
$form-label-font-weight: bold !default;
$form-label-line-height: 20px !default;

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-label';

FormError

This atom will render a form-input associated error.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:--------------|:---------|:--------------| | error_content | string | yes | - | | error_class_name | string | no | null |

This is a common setup example:

{% include '@lin3s_front_foundation/atoms/form_error.html.twig' with {
    error_content: 'This field is required.'
} %}

FormError - Customization

In order to customize the atom's appearance, you should define these variables before importing the involved scss file.

$form-error-background-color: #f2b8c2 !default;
$form-error-text-color: #b20008 !default;
$form-error-border-color: rgba($form-error-text-color, .5) !default;
$form-error-animation: $animation-vertical-node-in !default;
$form-error-font-family: sans-serif !default;
$form-error-font-size: 14px !default;
$form-error-font-weight: normal !default;
$form-error-line-height: 18px !default;

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-error';

FormInput

This atom will render a form input.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:--------------|:---------|:--------------| | input_id | string | no | - | | input_name | string | no | null | | input_value | string | no | null | | input_required | int | no | 0 | | input_type | string | no | 'text' | | input_placeholder | string | no | null | | input_class_name | string | no | null | | input_modifiers | string | no | null | | input_validate | int | no | 0 | | input_validation_pattern | string | no | null | | input_validation_type | string | no | null | | input_focusable | int | no | 1 |

This is a common setup example:

{% include '@lin3s_front_foundation/atoms/form_input.html.twig' with {
    input_placeholder: 'Enter some data...'
} %}

FormInput - Customization

In order to customize the atom's appearance, you should define these variables before importing the involved scss file.

$form-input-border-color: #d1d1d1 !default;
$form-input-border-color-hover: #0e8fff !default;
$form-input-placeholder-text-color: rgba(#444, .8) !default;
$form-input-font-family: sans-serif !default;
$form-input-font-size: 16px !default;
$form-input-font-size-small: 14px !default;
$form-input-font-weight: normal !default;
$form-input-line-height: 20px !default;
$form-input-line-height-small: 18px !default;

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-input';

FormSelect

This atom will render a custom rich form select.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:--------------|:---------|:--------------| | select_id | string | no | - | | select_name | string | no | null | | select_required | int | no | 0 | | select_class_name | string | no | null | | select_modifiers | string | no | null | | select_no_selection_label | string | no | '--' | | select_no_selection_value | string | no | '--' | | select_mobile_breakpoint | int | no | 1024 | | select_max_height_mobile | int | no | 260 | | select_max_height_desktop | int | no | 420 | | select_is_filterable | bool | no | 1 | | select_filter_placeholder | string | no | null | | select_filter_order_by | string ('label'|'value')| no | 'value' | | select_options | array | yes | These are the atom's options. Each option must have, at least, this shape: {    value: string*    label: string*    selected: int=0} | | select_is_filterable | int | no | 1 | | select_outside_click_to_close_enabled | int | no | 1 | | select_validate | int | no | 0 | | select_validation_pattern | string | no | null | | select_validation_type | string | no | null |

This is a common setup example:

{% set my_select_options = [{
    label: Male,
    value: 0,
    selected: 1
}, {
    label: Female,
    value: 1
}] %}

{% include '@lin3s_front_foundation/atoms/form_select.html.twig' with {
    select_class_name: 'form-select-demo',
    select_id: 'form-select-1',
    select_required: 1,
    select_filter_placeholder: 'Type to filter...',
    select_outside_click_to_close_enabled: 1,
    select_options: my_select_options
} %}

FormSelect - Customization

In order to customize the atom's appearance, you should define these variables before importing the involved scss file.

$form-select-background-color: #fff !default;
$form-select-background-color-disabled: #eee !default;
$form-select-border-color: #d1d1d1 !default;
$form-select-font-family: sans-serif !default;
$form-select-font-size: 16px !default;
$form-select-font-weight: normal !default;
$form-select-line-height: 20px !default;
$form-select-label-text-color: #222 !default;
$form-select-label-text-color-opened: rgba($form-select-label-text-color, .5) !default;
$form-select-options-box-shadow: 0 5px 30px -10px rgba(#222, .25) !default;
$form-select-option-text-color: #222 !default;
$form-select-option-text-color-active: #fff !default;
$form-select-option-background-color-active: #0e8fff !default;
$form-select-option-background-color-hover: #eee !default;
$form-select-option-background-color-hover-and-active: rgba($form-select-option-background-color-active, .8) !default;

@import './node_modules/lin3s-front-foundation/dist/scss/ui/atoms/form-select';

Picture

This atom will render a picture element with different sources depending on browser size and orientation.

The list of the available parameters, their type and default values are as follows:

| Parameter | Type | Required | Default value | |-------------------------- |:--------------|:---------|:--------------| | picture_class_name | string | no | null | | picture_image_class_name | string | no | null | | picture_alt | string | no | null | | picture_src_small | string | yes | - | | picture_src_medium | string | yes | - | | picture_src_large | string | yes | - | | picture_src_xlarge | string | yes | - | | picture_src_xxlarge | string | yes | - | | picture_small_breakpoint | int | no | 640 | | picture_medium_breakpoint | int | no | 1024 | | picture_large_breakpoint | int | no | 1200 | | picture_xlarge_breakpoint | int | no | 1440 | | picture_custom_srcset | html | no | null |

This is a common setup example:

{% embed '@lin3s_front_foundation/atoms/picture.html.twig' with {
    picture_class_name: 'my-picture',
    picture_image_class_name: 'my-picture__image',
    picture_alt: 'Some alt text',
    picture_src_small: 'http://mydomain.com/small-image.jpg',
    picture_src_medium: 'http://mydomain.com/medium-image.jpg',
    picture_src_large: 'http://mydomain.com/large-image.jpg',
    picture_src_xlarge: 'http://mydomain.com/xlarge-image.jpg',
    picture_src_xxlarge: 'http://mydomain.com/xxlarge-image.jpg',
    picture_small_breakpoint: 768,
} %}
    {% block custom_srcset %}
        <source srcset="http://mydomain.com/xsmall-image.jpg" media="(max-width: 540px)">
    {% endblock %}
{% endembed %}

Usage - Available macros

The library provides you opinionated macros for rendering the form components with pre-defined parameters.

Atoms - form_inputs

{% macro required(type, id, placeholder, name) %}
{% macro email(id, placeholder, name) %}
{% macro requiredEmail(id, placeholder, name) %}
{% macro phone(id, placeholder, name) %}
{% macro requiredPhone(id, placeholder, name) %}

Components - form_group_checkboxes

{% macro required(id, label, content, errors) %}

Components - form_group_inputs

{% macro required(type, id, placeholder, label, errors, name) %}
{% macro email(id, placeholder, label, errors, name) %}
{% macro requiredEmail(id, placeholder, label, errors, name) %}
{% macro phone(id, placeholder, label, errors, name) %}
{% macro requiredPhone(id, placeholder, label, errors, name) %}

Components - form_group_selects

{% macro required(id, filter_placeholder, label, options, errors) %}
{% macro requiredAndNot(id, filter_placeholder, label, not_valid_value, options, errors) %}

Components - form_group_textareas

{% macro required(id, placeholder, label, errors) %}
{% macro requiredWithPattern(id, placeholder, label, pattern, errors) %}

Validatory

FrontFoundation provides js and scss utility/helper code to work with the validatory librar to make easier our initialization or style customization.

Validatory - initWithEvents & EventBus subscriptions

FrontFoundation library provides an utility method EventBus.validatory.initWithEvents for initializing the validatory library coupled to the lin3s-event-bus library, so our app can be notified when a form, or any of it's element's validation state changes using the exposed EventBus.validatory.onFormStateChanged and EventBus.validatory.onFormElementStateChanged subscriptions.

import {EventBus} from 'lin3s-front-foundation';

EventBus.validatory.initWithEvents({
  formSelector: '#validatory-form',
  formElementSelector: '#validatory-form input, #validatory-form select, #validatory-form textarea'
});

// Event subscriptions through the event-bus

const myForm = document.getElementById('validatory-form');

EventBus.validatory.onFormStateChanged(myForm, stateChangedEvent => {
  // Do what you want with the provided payload object
  console.log(stateChangedEvent.formValidatorInstance);
});

const myFormElement = document.querySelector('#validatory-form .zip-code');

EventBus.validatory.onFormElementStateChanged(myFormElement, stateChangedEvent => {
  // Do what you want with the provided payload object
  console.log(stateChangedEvent.formElementValidatorInstance);
});

Validatory - custom validators and UI customization

In order to build and append a custom validator, we must first prepare the twig markup, then write our custom validator, and add some needed scss.

Note that we are adding some custom validation error messages/markup. (form-error--not-valid-zip-code, form-error--not-valid-no-service). These custom errors will match the custom validator's resolved errorCodes.

{% include '@lin3s_front_foundation/components/form_group_input.html.twig' with {
    input_id: 'zip-code',
    input_required: 1,
    input_validate: 1,
    input_validation_type: 'phone',
    input_placeholder: 'Enter your zip code',
    input_label_content: 'Zip code',
    input_errors: [{
        content: 'This field is required',
        modifiers: 'form-error--not-filled'
    }, {
        content: 'The entered value does not seem ot be a valid zip code',
        modifiers: 'form-error--not-valid-zip-code'
    }, , {
        content: 'Sorry, we are not providing service in the entered zip code's area.',
        modifiers: 'form-error--not-valid-no-service'
    }],
    input_spinner: 1
} %}

import debounce from 'es6-promise-debounce';
import {validatorRegistry, Validator, asyncValidation} from 'validatory';

const
  debouncedValidation = debounce(node => {
    console.log('Asynchronous validation started');

    const validZipCode = /^\d{5}$/.test(node.value); // zip code format validation

    if (!validZipCode) {
      return {valid: false, errorCode: 'zip-code'}; // will match the DOM markup's .form-error--not-valid-zip-code
    }

    return asyncValidation(fetch('https://jsonplaceholder.typicode.com/posts/1'), response => {
      const valid = node.value === '01005';

      return valid ? {valid} : {valid: false, errorCode: 'no-service'}; // will match the DOM markup's .form-error--not-valid-no-service
    });
  }, 500),
  asyncValidator = new Validator({
    supports: node => node.id === 'async',
    isEmpty: node => node.value === '',
    isValid: node => debouncedValidation(node),
  });

validatorRegistry.add(asyncValidator);

@import './../../node_modules/lin3s-front-foundation/dist/scss/_mixins/form-validation';

@include form_group_custom_error('.form-group-input__errors', 'zip-code');
@include form_group_custom_error('.form-group-input__errors', 'no-service');