Skip to content

Front end

Jump to bottom
energyyear edited this page Jun 30, 2020 · 5 revisions

Content

Laravel Blades

  1. Structure Rules
  2. Style Rules
  3. Formatting Rules

JavaScript

  1. Organization
  2. General Rules
  3. Naming conventions
  4. Variables
  5. Object rules
  6. References
  7. Functions
  8. Lines and spacing

CSS

  1. General Formatting Rules
  2. Naming conventions
  3. Meta Rules

React

Front-end

The application mainly uses server-side-rendered pages, rendered in Laravel's Blade engine. The files are found in resources/views/. Rendering views should be done with the view($path) helper. Additional data can be passed by calling ->with($key, $value) on the returned object. The views should almost never retrieve data themselves, all data should be passed through the with calls.

Blade

The blade templates can be found in resources/views. The file extension is in the format of .blade.php.

1 Structure Rules

1.1 Layout

All layouts can be found in the views/layouts folder. The idea is to work with a main template and include partials from there.

For example, a sidebar will be included as a partial in the main template. Partial can also contain multiple partials.

<!-- Recommended -->
layouts
|    HUdefault.blade.php
|____partials
|    |____sidebar
|         |    sidebar.blade.php
|         |____partials  
|              |    admin.blade.php
|              |    student.blade.php

This way you have directories for partials. This makes it easier to add new partials or delete specific layouts.

1.2 Components

Components can be found in views/components. This folder contains code that will be used several times in the application. It is preferred to include the components in order to reduce redundant code.

See 'Reusable code' (ch. 3.4) for code examples that should be converted into components.

1.3 Blade directives

Make use of blade directives where possible and use a closing tag if laravel recommends it. For example, use @error to display errors and @csrf for every form.

2 Style Rules

2.1 Document type

HTML5 is used. HTML5 is preferred for all HTML documents: <!DOCTYPE html>.

It's recommended to use HTML as text/html, and it is preferred to not use XHTML because of a lack of browser support.

2.2 HTML validity

Use valid HTML where possible.

It is recommended to test your HTML code by a validator (for example the W3 Html Checker)

<!-- Not recommended -->
 <title>Test</title>
 <article>This is only a test.
<!-- Recommended -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

2.3 Multimedia fallback

For multimedia (videos, gifs, etc) make sure to offer alternative access.

Use alternative text and video/audio transcripts if available.

For example, blind people will not be able to understand what the image is about without alt.

<!-- Not recommended -->
<img src="spreadsheet.png">
<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">

2.4 Inline css

The standard here is 'seperation of concerns'. To keep the presentation (css) seperate from the structure (markup), it is recommended not to use inline-css.

It also helps to reduce redundant code and it improves readability.

See the css section of this styleguide for more guidelines of css.

2.5 Inline javascript

The standard here is 'seperation of concerns'. To keep the behavior (javascript) seperate from the structure (markup), it is recommended to seperate javascript from the blades where possible.

Javascript is only used in blades if it directly uses php code or variables used by the blades.

See the javascript section of this styleguide for more guidelines of javascript.

2.6 Type attribute

It is considered good practise to omit the type attribute for stylesheets (unless not using CSS) and scripts (unless not using javascript).

Defaults for HTML5 are text/css and text/javascript, this also supports older browsers.

3 Formatting Rules

3.1 General formatting

Use a new line for each block, list or table element. Indent every child element.

3.2 Line-wrapping

For line-wrapping it is recommended to break long lines to improve readability.

When line-wrapping, each continuation line should be indented from the original line.

3.3 Quotation marks

Use double "" rather than single '' quotation marks around attribute values.

3.4 Reusable code and TODO

These are examples of code that are currently used multiple times in the project and should be converted into components. Make use of @component to make as many components as possible. If this is setup well, writing code will be a lot easier.

3.4.1 Layouts and components

Currently there is only 1 component: card. This should be extended by making a cards folder and adding different types of cards (with partials).

There should be a layout partial with the following code to reduce redundant code:

<!-- recommended -->
<div class="container-fluid">
  <div class="row">

  </div>
</div>

example path: resources/views/analytics/charts/index.blade.php
3.4.2 Lists and forms

Lists could be written with foreach to improve readability and reduce redundant code: This is also the case for forms and other types of lists like select

<!-- desired situation -->
<ul>
@foreach($menuitems as $menuitem)
    <li>{{ __('home.with-tile') }} <b>$menuitem->view</b> $menuitem->step</li>
@endforeach
</ul>
<!-- current situation -->
<ul>
  <li>{{ __('home.with-tile') }} <b>{{ __('home.learningprocess') }}</b> {{ __('home.steps.1') }}</li>
  <li>{{ __('home.with-tile') }} <b>{{ __('home.progress') }}</b> {{ __('home.steps.2') }}</li>
  <li>{{ __('home.with-tile') }} <b>{{ __('home.analysis') }}</b> {{ __('home.steps.3') }}</li>
  <li>{{ __('home.with-tile') }} <b>{{ __('home.deadlines') }}</b> {{ __('home.steps.4') }}</li>
  <li>{{ __('home.with-tile') }} <b>{{ __('home.profile') }}</b> {{ __('home.steps.5') }}</li>
</ul>

example path: resources/views/users/student/producing/home.blade.php
3.4.3 Student folder

There is a lot of duplicate code between the views in the users/student folder.

Many views of acting and producing are (almost) identical.

JavaScript

There are certain for writing JavaScript code. These are rules that provide a clear overview so that it can also be readable by developers who work on the application in the future.

1 Organization

The JavaScript files of the blades can be find in the follow directory: public/js/blades-js. The structure is similar to the blades structure. If you want to create a new JS file for a blade, you have to do it in this directory. Sometimes inline JS must be written in the blades. Only JavaScript that uses php code or variables can be written in inline JS.

2 General Rules

2.1 Expanded syntax

Make use of extended syntax where each line of JS is on a new line, the opening curly brace of a block is on the same line as the corresponding statement, and the closing curly brace is on a new line. This maximizes readability.

Recommended:

function myFunc() {
    console.log('Hello!');
};

Not recommended:

function myFunc() { console.log('Hello!'); };
2.2 Comments

Use JS-style comments to comment code that isn't self-documenting:

// This is a JavaScript-style comment

Don't put the comments on the same line as the code, but put it on a separate line above it and leave an empty line above the comment. See example:

// Above this comment is an empty line
const active = true;

Use /** ... */ for multiline comments.

As you can see from the examples, keep at least one space between the slashes // and the comment.

3 Naming conventions

Variables and function names must be complete and logical words. The name should be written like the camelCase notation where the first letter shouldn't be capitalized. The name should be descriptive but not exaggerated.

However, there is an exception for, for example, iterations that usually use an i that represents the index in a loop.

4 Variables

Put values in variables if it is used in multiple places. For example, avoid hard-coded values in functions.
Each variable must start with a letter.

Assign variables where you need them, but place them in a reasonable place. Bad example:

// bad - unnecessary function call
function checkName(hasName) {
  const name = getName();

  if (hasName === 'test') {
    return false;
  }

  if (name === 'test') {
    this.setName('');
    return false;
  }

  return name;
}

Here the variable is assigned while this step may be unnecessary in that place (if the first if-condition is true). Good example:

// good
function checkName(hasName) {
  if (hasName === 'test') {
    return false;
  }

  const name = getName();

  if (name === 'test') {
    this.setName('');
    return false;
  }

  return name;
}

5 Object rules

There are some general rules about defining objects:

  • Place the opening brace on the same line as the object name.
  • Use colon plus one space between each attribute and its value.
  • Use quotes around String values, but don't use them with numeric values.
  • Don't add a comma after the last property of an object.
  • Place the closing brace on a new line, without leading spaces.
  • Always end an objectdefinition with a semicolon.

Example:

var person = {
    firstName: "John",
    lastName: "Doe",
    age: 50,
    eyeColor: "blue"
};

By a short object definition it can be aligned on one line with spaces between the properties:

var person = {firstName: "John", lastName: "Doe", age: 50, eyeColor: "blue"};

6 References

Use const for all references and avoid using var for references. This is to ensure that the references aren't reassigned. Doing so can cause bugs and difficulties in understanding the code.

If you still want to reassign a reference, use let instead of var. This because let is block-scoped while var is function-scoped, it only exists in its own scope. A block is when you see { braces }. See below a comparison table between the three ways to declare a variable:

var let const
Reassigned 0 0 X
Scope Function Scope Block Scope Block Scope
Reference before declaration 0 X X

7 Functions

A function should not have more than 3 parameters.
Never reassign or mutate a parameter, but instead use variables.
Give functions logical names and make use of a verb in the function name. The use of a verb in function names provides clarity.

Where possible, use the function declaration to define functions:

// Recommended
function sum(a, b) {
    return a + b;
}

instead of function expressions:

//Not recommended
let sum = function sum(a, b) {
    return a + b;
}

Never put a space between the argument list and the function name in a function declaration. Place a space before the function name and between the argument list and opening curly brace.

function decreaseHour() {

If you want to break a line inside the function parentheses, do that for each parameter. Not Recommended:

transaction(amount,
    installments)

Recommended:

transaction(
    amount,
    installments
)

8 Lines and spacing

Always place a blank line between logical blocks.

Maximum line length

Avoid having code lines longer than 80 characters, including spaces in the lines.

Multiple empty lines

Avoid using two or more empty lines in the middle of a code. See example below:

Not recommended:

const a = 'This is a test'


console.log(a);

Recommended:

const a = 'This is a test'

console.log(a);

Line breaks

If a JavaScript statement doesn't fit on one line, break it after an operator or a comma like the following example:

document.getElementById("demo").innerHTML =
"Hello Joe"

Line breaks inside function parentheses

If you want to break a line inside the function parentheses, do that for each parameter. See the following example:

Not Recommended:

transaction(amount,
    installments)

Recommended:

transaction(
    amount,
    installments
)

Spacing

  • Place a space between each argument list and an opening brace.
  • Always put spaces around operators.
  • Place a space between parameters.
  • Place a space for each opening bracket in control statements, such as if, while etc.
  • Never put a space between the argument list and the function name in function declarations.
  • Place a space before the function name in a function declaration.
  • Place a space between the argument list and the opening curly brace in a function declaration.
// bad
if(isJedi) {
  fight ();
}

// good
if (isJedi) {
  fight();
}

// bad
function fight () {
  console.log ('Swooosh!');
}

// good
function fight() {
  console.log('Swooosh!');
}

CSS

The CSS of this project is written in LESS which is then compiled to valid CSS. The LESS file that is to be used can be found at resources/assets/less/style.less. Any edits of the CSS, thus, must be done via LESS. The output is then found in public/css/*.

The compilation can be done through yarn, with the same command as with the JS assets. Use yarn watch to automatically compile the assets while developing. When you're done with your edits and are about to create a pull request, run yarn prod to compile a minified version of the assets. Although against most standards, currently there is a need to commit compiled versions of assets.

1 General Formatting Rules

1.1 Indentation

Indent by 2 spaces at a time.

Don't use tabs or mix tabs and spaces for indentation.

.example {
  color: blue;
}

1.2 Nested css

Css should be nested where possible.

<!-- Not recommended -->
#menu-bar .stud-info-header { display: none;}
#menu-bar a span {display: none}
#menu-bar a .logout {float: right;}

Recommended

#menu-bar {
 .stud-info-header {
    display: none;
  }

  a {
    span {
      display: none;
    }

    .logout {
      float: right;
    }
  }
}

2 Naming conventions

2.1 Capitalization

Use only lowercase. Names should be shortened where possible, but only if the name stays meaningful.

All code has to be lowercase. Seperation of words will be done with dashes

<!-- Not recommended -->
#selectWPLP {
  font-size: 16px;
}
.navigation {...}
.atr {...}
<!-- Recommended -->
#select-wplp {
  font-size: 16px;
}
.nav {...}
.author {...}

2.2 Variables

Variables should be used for repeating elements such as sizes, colors, fonts, devices.

2.3 Type Selectors

Avoid qualifying ID and class names with type selectors. Only use conjunction if necessary (for example helper classes), but otherwise avoid for performance reasons.

<!-- Not recommended -->
ul#example {...}
div.error {...}
<!-- Recommended -->
#example {...}
.error {...}

2.4 Shorthand Properties

Use shorthand properties where possible. This improves code efficiency and understandability

<!-- Not recommended -->
padding-right: 2em
padding-bottom: 3em
padding-left: 2em
<!-- Recommended -->
padding: 0 2em 3em 2em;

2.5 Hexadecimal Notation

Use 3 characters where possible.

<!-- Not recommended -->
@white: #FFFFFF;
<!-- Recommended -->
@white: #FFF;

2.6 Sizes

In general, sizes should be defined as rem and em.

This is because the project uses bootstrap which defines their sizes in rem and em.

Exception: px is used for device breakpoints. Example

@device-small: 600px;

@media only screen and (max-width: @device-small) {...}

3 Meta rules

3.1 Comments

Explain code as needed, where possible.

Use comments to explain code: What does it cover, what purpose does it serve.

Try to prevent writing unnecessary comments.

<!-- Not recommended -->
/* background color of navbar */
.nav {
  background-color: blue;
}
<!-- Recommended -->
/* Form Section */
.form {...}

.form-submit-btn {...}

3.2 Action items

Mark todos and action items with TODO

Highlight todos by using the keyword TODO only, not other common formats like @@

Append a part of website in parentheses as with the format TODO(footer)

Append action items after a colon as in TODO: add login form

React

Some elements in the application are simple React mini-applications. For example, the tip and programme pages, or the progress page.

It is possible to create more of the React elements. They have most use in areas where a lot of data is exchanged with the server and the interface is very interactive.

It is recommended to not introduce any JS dependencies, unless they are strictly necessary.

Compiling of the JS can be done with yarn. The instructions are available on the setup page.

Clone this wiki locally