@blueelevation/components NPM

BlueElevation custom Nuxt component module.

Welcome to the ReadMe of the BlueElevation custom PWA Nuxt components module (a whole mouthfull). This module contains different components which we use throughout different projects in order to make it easier for ourselves to copy/paste different functionalities.

Folder structure

First something about the folders in this module.

`components`

The components folder contains all of the custom GLOBAL components that we have. At the time of writing this we have four: Carousel, Filter, GForm and PostLoop. Whenever more are added it isn't expected for it to be added to this list, but it is expected you include it in its own section below.

`dist`

The folder containing compiled/minified CSS & Javascript which gets published to the npm directory (and also to git, but that's less important).

`lib`

The folder containing the unminified and uncompiled CSS & Javascript. If you need to make any changes or add a file you can do that here. Please respect the folder structure and do NOT change the names (scss and js). This is important for the command npm run pub, which will be explained later. You can create an infinite number of *.scss and *.js files in their respective folders and it will be compiled/minified properly. In case you need to import it you can do so. For an example on how that works, see @blueelevation/components/components/Carousel/Carousel.vue. Here we import carousel.js.

`plugin`

This folder contains two important files.

eventbus.js: This is exactly what its file name describes: an EventBus. For more information on how or why, Google. You can also import this EventBus outside of this module and listen for events. Event will be described in their respective component sections.
plugin.js: Where the magic happens. Here we register Vue components if they're enabled through the nuxt.config.js file in your project. This will also get its own section.

Installing/enabling this module

In order to use this module in the project you need to use npm. You'll be able to install it to your project using the following command: npm install @blueeelvation/components. Afterwards, the latest version will be installed. If you'd like a specific version, you can include @<version> behind the previously specified command (so for example npm install @blueelevation/components@1.0.0).

After you've installed it, you actually need to enable it. You can do that in the modules section of your nuxt.config.js. An example:

modules: [
	"@blueelevation/components",
],

components: {
	modules: ['carousel', 'filter', 'post-loop', 'gform']
},

And as you can see you can create a components object in which you can specify a modules array of the ones you want to have globally registered in your Nuxt application. All Nuxt modules are basically independent of each other and can be registered individually. So you can only have the gform module registered for example.

Creating a new component

In order to create a new component you can follow these steps: 1. Create it in the components folder using the same naming/folder hierarchy that already exists. 2. Go to index.js, here you'll see an availableModules array. Choose a proper descriptive name. This is also the name you give to the modules array in your nuxt.config.js. 3. If you have a custom CSS file you'd like to add, you can do that in the cssFilesToLoad array. It already points to the dist/css folder in which *.scss files will be compiled to. 4. Go to plugin/plugin.js and import the component's .vue file the same way the others are done. Then using the if statements already there you can see if options.modules includes the modulename you chose in step 2. If that's the case, register the Vue component globally like always. You can also inject a variable if you want. For the gform module we've already done this. We've chosen the name GForm and the passed config object is accessible in the component by using this.$GForm. 5. Create your component however you like using the standard Nuxt methods. 6. Add your module and the way it works to this README.md in the section below. Please do this to avoid possible confusion and headaches in the future and put it in alphabetical order.

Modules

Whenever you create a new module you can add a new section below to explain how it works, what configuration options can be passed, the props, attributes, etc.

Carousel

Description

The carousel module is used to, guess what, render a carousel.

Component name: <Carousel></Carousel>
Within the Carousel tags you can place a multitude of children which will in return be made into a Carousel. An example of this HTML structure would be:

<Carousel>
	<div class="child">content</div>
	<div class="child">content</div>
	<div class="child">content</div>
	<div class="child">content</div>
</Carousel>

This is the most basic working of this module.

Attributes/Props

You can give the following attributes to the Carousel module to enable certain functionality:

nav { Boolean }: enables arrows to the left and right of the carousel which can be clicked to navigate
bullets { Boolean }: enables dots on the bottom which can be clicked to navigate.
equal_heights { Boolean }: is used to give every item in the carousel the same height.

All of these props default to false, which means: if you don't need it, don't specify it. An example to enable these three functionalities would be:

<Carousel nav bullets equal_heights>
	<div class="child">content</div>
	<div class="child">content</div>
	<div class="child">content</div>
	<div class="child">content</div>
</Carousel>

Filter

Description

Used to filter posts based on parameters. Still work in progress. Will have future configuration through nuxt.config.js.

Component name: <pwa-filter></pwa-filter> This component requires no other configuration to be used. The Wordpress Backend will give a response to the frontend requesting the pwa-filter component and it will be rendered. Styling for this component will be done in the project itself.

Sub-components

<pwa-filter-heading>: Used to render a search field along with a title and shorttags. Future configuration of this component will be done in nuxt-config.js.
<pwa-filter-shorttag>: Subcomponent for the <pwa-filter-heading> component.

This component uses fields from the gform module. Note however that it is not necessary to include the full gform module in the nuxt.config.js in order to use this component.

GForm module

Description

GForms module to display forms on the website based on JSON response received from the backend.

Component name: <pwa-gform></pwa-gform>
This component requires quite a bit of configuration in the nuxt.config.js to be used properly to your liking. The configuration options can be found below.

Sub-components

<pwa-form-html>: The GForm HTML standard field.
<pwa-form-input>: The GForm input standard field.
<pwa-form-radio>: The GForm radio standard field.
<pwa-form-checkbox>: The GForm checkbox standard field.
<pwa-form-section>: The GForm section standard field.
<pwa-form-select>: The GForm dropdown standard field.
<pwa-form-textarea>: The GForm textarea standard field.

Configuration

There's quite a lot of room for configuration in nuxt.config.js. Below you'll find all of the key:value pairs that you can enter in the gform object.

{
	modules: ['gform'],
	gform: {
		form: {
			title: true
		},

		field: {
			descriptionIcon: 'fas fa-info-circle'
		},

		pagination: {
		 	format: 'bar',
		 	title: 'Step' 
		}
	}
},

Options floatingLabels {BOOLEAN}: whether to enable the floating labels functionality yes or no. showFormTitle {BOOLEAN}: whether or not to show form titles. showProgressTitle {BOOLEAN}: whether or not to show the progress in every field set. descriptionIcon {ARRAY}: Icon is from FontAwesome format is font type first (fas, fab, etc), then icon name. I.E. ['fas', 'fa-info-circle']. If filled in, the description will be rendered with an icon. Otherwise, it's rendered as text below the field.

text {OBJECT}: Object with strings that can be changed per project. See possibilities below: