Download the PHP package lin3s/front-foundation without Composer
On this page you can find all versions of the php package lin3s/front-foundation. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download lin3s/front-foundation
More information about lin3s/front-foundation
Files in lin3s/front-foundation
Package front-foundation
Short Description Library that provides a sort of commonly used front-end components in LIN3S projects
License MIT
Informations about the package front-foundation
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:
or alternatively through NPM:
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.
Browser
This package will provide all browser related implementations.
Browser.isIE11()
This method will tell us if the browser is Internet Explorer 11.
Dom
This package will provide all Dom related implementations.
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.
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
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.
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.
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).
Cookies
This package will provide all document.cookie
related implementations.
Cookies.read
This method will return the value of a cookie by its name.
Cookies.write
This method will write a cookie. Accepts an object with names parameters for name, value, expiration, domain and 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:
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.
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:
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:
Type | Properties |
---|---|
GMapInitializedEvent | gmapInstance: GMap |
GMapMarkerSelectedEvent | gmapInstance: GMap marker: Your marker object representation |
GMapGeocodeEvent | gmapInstance: GMap status: response status results: 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.
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:
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.
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:
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.
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:
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:
Type | Properties |
---|---|
FormSelectInitializedEvent | formSelectInstance: FormSelect |
FormSelectOptionSelectedEvent | formSelectInstance: FormSelect marker: Your marker object representation |
FormSelectStateChangedEvent | formSelectInstance: FormSelect state: [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.
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:
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.
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:
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:
FormLabel - Customization
In order to customize the atom's appearance, you should define these variables before importing the involved scss file.
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:
FormError - Customization
In order to customize the atom's appearance, you should define these variables before importing the involved scss file.
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:
FormInput - Customization
In order to customize the atom's appearance, you should define these variables before importing the involved scss file.
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:
FormSelect - Customization
In order to customize the atom's appearance, you should define these variables before importing the involved scss file.
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:
Usage - Available macros
The library provides you opinionated macros for rendering the form components with pre-defined parameters.
Atoms - form_inputs
Components - form_group_checkboxes
Components - form_group_inputs
Components - form_group_selects
Components - form_group_textareas
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.
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 errorCode
s.