helsingborg-stad / blade-component-library
A component library based upon blade engine.
Installs: 22 006
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 12
Forks: 1
Open Issues: 4
- dev-master
- 0.15.0
- 0.14.0
- 0.13.0
- 0.12.0
- 0.11.0
- 0.10.0
- 0.9.5
- 0.9.4
- 0.9.3
- 0.9.2
- 0.9.1
- 0.9.0
- 0.8.6
- 0.8.5
- 0.5.11
- 0.5.10
- 0.5.9
- 0.5.8
- 0.5.7
- 0.5.6
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5
- 0.4
- 0.3.9
- 0.3.8
- 0.3.7
- 0.3.6
- 0.3.5
- 0.3.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.6
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.0
- 0.0.2
- 0.0.1
- dev-fix/3.0/labelledby-attribute
- dev-fix/options-required
- dev-fix/date-translation
- dev-fix/table-sort
- dev-develop
- dev-feature/collection
- dev-feature/date-badge
- dev-collec
- dev-img-place
- dev-feature/grid-comp-2
- dev-fix/table-sort-hover
- dev-hotfix/if-endpoints
- dev-wip/dynamic-top-nav
- dev-wip/nav-dynamic-children
- dev-wip/footer-component
- dev-wip/side-bar-dynamic-children
- dev-wip/card-component-rework
- dev-feature/splitbutton-bug-fix
- dev-feature/json-attribute
- dev-wip/redesign
- dev-wip/notification
- dev-feature/react-init
- dev-wip/calendar
- dev-feature/card-doc-button-fix
- dev-wip/button-component-rework
- dev-feature/card-button-usage-refactor
- dev-feature/button-group-fix
- dev-feature/button-controller-cleanup
- dev-feature/button-fix
- dev-wip/button-fix
- dev-feature/form
- dev-feature/icon-button-hover-color
- dev-feature/code-prism
- dev-hotfix/icons-testimonials
- dev-feature/Testimonials-layout
- dev-feature/Testimonials
- dev-feature/icon-generator-fix
- dev-feature/Dropdown-mobile
- dev-feature/docs
- dev-feature/Cards-accordion
- dev-feature/unique-id
- dev-feature/tabindex
- dev-feature/base-class-generator
- dev-wip/text-button
- dev-feature/FW2-78-button-group
- dev-feature/FW2-79-split-button
- dev-feature/id
- dev-feature/Gallery-ie-compability
- dev-feature/Card-focus-traversing
- dev-feature/Card-dropdown
- dev-feature/toggle-only-outline
- dev-wip/toggle-only-outline
- dev-FW2-82-cards
- dev-wip/FW2-79-split-button
- dev-feature/FW2-80-drop
- dev-wip/FW2-80-drop
- dev-wip/FW2-77-button-toggle
- dev-wip/FW2-78-button-group
- dev-feature/refactor-init
- dev-feature/Fw2-76_Gallery
- dev-feature/FW2-72-notice-icon-size
- dev-feature/FW2-85-improve-customization
- dev-fix-button
- dev-feature/FW2-69-Button
- dev-feature/FW2-72-Notice
- dev-wip/FW2-72-Notice
- dev-feature/FW2-68-Image
- dev-feature/html
- dev-feature/data
- dev-feature/view-composers
This package is auto-updated.
Last update: 2024-02-11 15:27:51 UTC
README
This is a library containing load functions and library of views with their controllers. Enables swift and precise development of static user interfaces across multiple products. The package is designed to be used standalone or with WordPress as CMS engine.
Important note: This is a view package! Not a single line of CSS or Javascript will be appended. We (will, not complete yet) have a separate package to provide these feature in a syleguide format.
Getting started
Recommended method of usage is with composer. Add the requirement below, to enable a new set of awesome features.
composer reqire helsingborg-stad/blade-component-library
Known issues
- Components/directives must be called with an @endcomponent tag. Directives without end-tag will not work.
Example usage (register a component)
<?php namespace Municipio\Theme; class RegisterUtility { public function __construct() { \BladeComponentLibrary\Register::addViewPath( MUNICIPIO_PATH . 'views/utility', true //true = prepend, false = append, default = prepend ); \BladeComponentLibrary\Register::addControllerPath( MUNICIPIO_PATH . 'library/Controller/Utility/', true //true = prepend, false = append, default = prepend ); \BladeComponentLibrary\Register::add( 'button', [ 'isPrimary' => true, 'isDisabled' => false, 'isOutlined' => true, 'label' => "Button text", 'href' => "https://google.se", 'target' => "_self" ], 'button.blade.php' // You can leave this out, it will automatically be generated from slug. ); \BladeComponentLibrary\Register::add( 'date', [ 'hasTime' => false, 'hasDate' => true, 'isHumanReadable' => true ], 'date-time.blade.php' ); } }
Example usage (render component)
A registered component can be utilized as a component or directive just as in laravel. They do however have the added functionality to load the controller before render to enshure that stuff is formatted and defined.
Render as a directive
@button(['text' => "Button text", 'href' => "https://helsingborg.se"]);
Render as a component
@component('button') Button text @slot('href') https://helsingborg.se @endslot @endcomponent
Implement replacement views & controllers
This package is designed to be overrided with a theme or plugins own views. Simply add a new path as below. You have an ability to prepend or append the existing search arrays. The path's will be searched chronologically.
use BladeComponentLibrary/Register as Register; //Adds a new view search path Register::addViewPath( MUNICIPIO_PATH . 'views/utility', false //Prepend = true ); //Adds a new controller search path Register::addControllerPath( MUNICIPIO_PATH . 'library/Controller/Utility/', false //Prepend = true );
Data flow
Base controller components This controller handles all data flow to every component. There are multiple ways of inputting data to a component.
-
The default configuration of the component. These settings are made in the configuration json in each component folder. All variables used in the controller SHOULD be declared here. This is to avoid undeclared variabe varnings.
-
By populating the directive (in view file). This should be data that idicates states like isDisabled => true etc. This is the main location of end user customization.
-
By data manipulation in the controller connected to each component. This data can be in every form, but should focus on translating other input to view data. This file can contain clear-text-classes.
Example:
if($isDisabled) { $this->classList[] = 'disabled'; }
- If the component library is running inside WordPress. There is a additional filter that can be used to externally manipulate the data as a last step before output.
Filter (General): BladeComponentLibrary/Component/Data - Takes $data
Filter (Component specific): BladeComponentLibrary/Component/ComponentName/Data - Takes $data
Filter class (General): BladeComponentLibrary/Component/Class - Takes $class
Filter class (Component specific): BladeComponentLibrary/Component/ComponentName/Class - Takes $class
Class filters extracts the class variable from $data object.
Add a builtin component
The most efficient and proposed way of adding a compning is by a PR to this package. It will then be available for everyone to be used. A internal component requires three different files.
- View
- Controller
- Configuration
The view
The view sould be as simple as possible, in most cases just a few if-statements. For more advanced solution, please consider to use directive components as childs to a larger component.
Example:
<a class="{{ $class }}" target="{{ $target }}" href="{{ $href or '#' }}">{{ $slot or $text }}</a>
The controller
The controller should handle all logic associated with a component. This file soule purpose is to remove any logic from the view.
Example:
namespace BladeComponentLibrary\Component\Button; class Button extends \BladeComponentLibrary\Component\BaseController { public function init() { $this->data['foo'] = "bar"; } }
The configuration
A simple configuration of the slug for the component (used as directive & component name). The default parameters and the view name (defaults to the slug name). The configuration should be written in a valid json format. This file must contain the keys "slug", "default" (default parameters) and "view".
Example:
{ "slug":"button", "default":{ "isPrimary":true, "isDisabled":false, "isOutlined":true, "label":"Button text", "href":"https:\/\/google.se", "target":"_self" }, "view":"button.blade.php" }
WordPress Compability
Each component will get their respective WordPress filter registered if WordPress core is included before this library. We simply look for the built-in functions called apply_fitlers. The filter will be named as their respective folder location.
For example; Card component located in "./src/Component/Card" will get the filter "BladeComponentLibrary/Component/Card/Data" applied before render. The last part of the slug "Data" can be changed to "Class" to just filter the sub array "classes" of the data object.
A specific filter for each key in the data object will also be created. Fir instance if the data object includes the key 'foo' a filter will be created like this: BladeComponentLibrary/Component/Card/Foo. This will not include the key "data" as it's reserved by above filter.
A generic filter will also be called for the data object called "BladeComponentLibrary/Component/Data". This has the side effect of reserving the data namespace. Therefore you cannot create a component called Data.
View variables
All component views will be allocated with some basic parameters. These are listed below. Everything else added to the $data array will automatically be added as a $var named with the key value.
Variable | Description |
---|---|
$class | An array of classes that wraps the component. |
$compiledClass | An string of classes that wraps the component. |
$baseClass | A string of first class assigned. |
$attribute | A string of attributes |
Built With
- Laravel Blade 5.*
Dependencies
- PHP 7.0
Releases
https://github.com/helsingborg-stad/blade-component-library/releases
Authors
- Sebastian Thulin
- Johan Silvergrund
- Jonatan Hanson
- Nikolas Ramstedt
- Eric Rosenborg
- Alexander Boman Skoug
License
This project is licensed under the MIT License - see the LICENSE file for details