bookunited/blurr repository overview

⁠Blurr

⁠Coding standards

Refer to the coding-standards⁠ document for the PHP/JS/CSS coding standards for this project.

⁠Getting Blurr to work (clean install)

Prerequisites when running Windows:

• Windows 10 professional with Hyper-V enabled
• Docker CE for Windows⁠

Prerequisites when running Mac OSX:

• Docker CE for Mac⁠

⁠Clone the repository

git clone -b develop [email protected]:travver/blurr.git

⁠Build/download the docker images

develop build

⁠Install the required composer dependencies

develop composer install

⁠Copy the .env.example file to a new .env file, then update the file with the correct values (ask a colleague) and set the app key

cp .env.example .env
develop artisan key:generate

⁠Install npm dependencies

develop npm install

⁠Run the webpack command to generate the assets:

develop webpack development

⁠Start the docker container(s)

develop up -d

Now you should have a working instance of Blurr running that you can visit on http://localhost/⁠ and https://localhost/⁠

⁠Partners / brands

Blurr is built to host multiple websites that all connect to the same backend API. Each website is referred to as a 'partner' or a 'brand'.

⁠Creating a new partner

To create a new partner, simply run the following command which will interactively help you create a new partner.
This will create the files as well as add an entry into the database.

develop artisan partners:create

⁠Default partner folder structure

Partner-specific code is generated in the brands/{namespace}/ folder in the project. By default, this folder contains the following files:

⁠Referencing partner-specific information in the code

Get the partner object through a function.

partner();

Get specific partner setting.

partner()->setting('partner.name');
    

Get a partner asset from the mix manifest.

partner()->mix('filename.ext');

Get an unversioned partner asset.

partner()->file('filename.ext');

⁠Configuring vue components

⁠Immutable brand configuration

These settings are global for every brand and not page specific. To adjust the behaviour of various vue components you can add settings to the config.json file of the partner found in resources/assets/config.json. You can reference these files (in resources/whitelabel/assets/js/) for the available options and their default values:

All variables are accessible with under the config in every Vue component

this.$config.get('SearchList.Amount')

⁠overrides

To override the default setting for a brand you add a config file in /brands/{brandname}/resources/assets/js/{component}/config.json When building the main config file these settings are merged for a brand

⁠Dynamic component configuration

To create a menu in the backend for a component you need a (componentname).json file in the same directory as the vue component. This menu structure is used by the backend to create menu which can populate the dynamic settings of the component. Think about header text, or custom queries for product listings. These settings are injected at runtime, and are available in the components data section of the vue file. Make sure the data property exist that the componentSettings mixin is used.

⁠export configuration

You can import and export all dynamic configuration in the backend of blur, in the content section. This allows you to copy the production environment for use in development.

⁠Content pages

The homepage, content pages like contact, faq etc and custom pages are managed by the content section in the admin. You can manage the text and the various components with their settings. You can build for example a custom homepage by using a configurable list of components. Every partner gets his own set of pages based on a languages with the use of default content. You can find this content in the md files located in /resources/whitelabel/views/content/pages.

⁠Develop command

The develop command (develop.bat for Windows systems, develop.sh for Mac OSX systems) has been created to make dealing with the docker containers a bit easier.

By default (without any parameters) the develop command runs docker-compose ps using the development docker-compose file (docker-compose.dev.yml). This lists the running docker containers.
When supplied by a parameter that is not listed below, the command will run docker-compose using the development docker-compose file and add the parameters added to the command. For example, to run a bash shell in the blurr container, use:

develop run --rm blurr bash

⁠Docker commands

Using docker you can build, run, inspect and destroy docker images and containers. Here you will find a list of regularly used commands. To check out the available commands and options, check out the docker-compose reference docs⁠.

Building the images from the docker compose file (use the --no-cache flag to force a full rebuild`):

develop build

Starting the docker containers (use the -d flag to detach after starting the containers):

develop up

Stopping the docker containers (use the -v flag to remove created volumes if required):

develop down

⁠Running special develop commands

⁠Artisan

To run artisan commands, use develop artisan. This will run artisan in the blurr container. So to run migrations use develop artisan migrate, to create a new event run develop artisan make:event etc.

⁠Composer

To install or update composer dependencies, use the develop composer command. This will run composer in the blurr container, ensuring that the correct dependencies are installed. To install use develop composer install, to add a package use develop composer require developer/package, etc.

⁠PHPUnit

To run PHPUnit tests, use develop phpunit. This will run all tests using the phpunit version installed through composer in the blurr container.

⁠NPM

To install or update nodejs dependencies, use develop npm. This will run npm in the node container. To install the depencies run develop npm install, to install a new dependency use develop npm install <package> --save, etc.

⁠Webpack

Use the webpack command to compile the assets. Using the develop webpack command will run webpack in the node container.

The webpack command accepts 2 extra parameters: develop webpack <command> <namespace> that accept the following values:

command should be replaced by development to run a development build, production to run a production build, or watch to watch the assets and update the development build when a file is changed. When the argument is not supplied, production is used.

namespace is optional and can be used to specify the namespace of a specific partner that should be compiled or watched. To make webpack watch the files of the Hoteldeal partner, use develop webpack watch Hoteldeal.

The -f flag can be prepended to speed up the build: develop webpack -f <command> <namespace>

This runs only a part of the webpack build, it excludes:

• PurifyCSS (to remove redundant css code)
• URL processing for SCSS files
• The Favicons plugin that generates various icons
• The MergeJson plugin that combines json configuration files
• The Stylelint plugin that checks css code
• The PostCSS BEM linter that checks css for valid BEM style
• The grid prefixes for the autoprefixer