Section 1 #_getting-started
Getting-started

Get started

Platform-UI is a responsive framework.

Learn how we've built Platform UI and patterns to help you contribute.

Source: sass/_getting-started.scss, line 1

Section 1.1 #_getting-started.installation
Installation

Lifecycle scripts included in @ritterim/platform-ui:

script (npm run) runs
start npm install && gulp
test echo "Error: no test specified" && exit 1
build gulp build
build:all npm install && cd custom-builder && npm install && npm run sass && cd .. && gulp
build:style rm -rf styleguide && cd custom-builder && npm run sass && cd .. && gulp
ver echo "$npm_package_version"
Source: sass/_getting-started.scss, line 11

Section 1.2 #_getting-started.JavaScript
JavaScript

We use semi-colons.

We use single quotes.

Do not use trailing commas. This actually causes errors in Edge and Internet Explorer (YES, we have to deal with BOTH!).

// Do NOT do this
['hedgehog', 'hedgehog',]
// This is good
['hedgehog', 'hedgehog']

Keep towards ES6 standards whenever possible (let, const should be used over var).

We use two spaces for JavaScript, HTML, and CSS. If you happen to be writing any C#, use four spaces. The .editorconfig file should handle this.

Source: sass/_getting-started.scss, line 47

Section 1.2.1 #_getting-started.JavaScript.VueJS
VueJS

General Component Structure

https://vuejs.org/

Components are generally done in single file components. These components are structured in the order of <template> and then <script>. In general, we do not use <style> unless directed to do so by the UI team and something needs that encapsulation.

The general component structure should be like below, following the same order as the pieces in the object below.

import nonComponents;

import Components;

export default {
	name: 'PascalCaseName',
	components: {
		PascalCaseComponentImports
	},
	mixins: [importedMixinsCamelCase],
	computed: {
		computedProperty() {
			return null;
		},
		...mapState([
			'things'
		])
	},
	data() {
		return {
			item: 'hello'
		}
	},
	created() {
		console.log('first lifecycle piece');
	},
	mounted() {
		// in general mounted should be used over created, unless created is needed
		console.log('next lifecycle piece');
	},
	destroyed() {
		console.log('last lifecycle piece');
	},
	watch: {
		item() {
			console.log(this.item);
		}
	},
	methods: {
		thisMethod() {
			console.log('this is a method');
		}
	},
	filters: {
		formatString(val) {
			return val.toLocaleString();
		}
	}
}

HTML/Template Structure

When using three or more attributes, an element should be stacked. In addition to this, if props are included, those props should be camelCased.

If you are adding a base component that uses vue-custom-element, note that your props will need to be snake-cased. This helps us differentiate when we are pulling in a full, standalone component and when we are pulling in individual pieces inside of a standalone component.

Component tags should be written as snake-cased as opposed to PascalCased.

We should use the following order when using Vue attributes on our elements. Following this order will allow everyone to very quickly see the pieces that we are looking for.

ref
v-if/v-else
v-for
v-model
:camelCaseProps
@events
regular attributes

An example with two or less attributes can be seen below.

<button @click="handleClick" class="button">
	Click Me!
</button>

An example with three or more attributes can be seen below.

<my-component
	v-if="condition"
	v-for="thing in things"
	v-model="thing"
	:key="thing.id">
</my-component>

<!-- Either of these are correct, with the closing > on the last line or its own -->
<my-component
	v-if="condition"
	v-for="thing in things"
	v-model="thing"
	:key="thing.id"
>
</my-component>
Source: sass/_getting-started.scss, line 68

Section 1.3 #_getting-started.SASS
SASS

https://sass-lang.com/

Mixins v. Extends

If you're passing an argument or looping through a function, this is a mixin.

If you're writing css to be re-used, this is an extend. Stand-alone extends always begin with %.

NOTE: Place any SCSS native call, includes, extends, loops, and functions, at the bottom of any regular CSS. I.e., @include, @extend, @for, @each

Updated syntax

With the dart-sass update you now will need to call a mixin by including the namespace of the mixins file. In our case it's mixins. @include breakpoint() becomes @include mixins.breakpoint(). Notice the mixins. before the mixin name.

Source: sass/_getting-started.scss, line 26

Section 1.3.1 #_getting-started.SASS.Extends
Extends

We use extends throughout platform-ui. You can extend a block of scss by using @extend {class-name} or, how we typically use extends is by extending a placeholder selector. Rather than a class @extend %example-placeholder. These are style rules that we only want to extend.

You can find a list of extendable placeholders below:

Extend
%flex-center %truncate-with-ellipsis %inverted %scrollbar
%rotate-45 %rotate-90 %rotate-180
Source: sass/mixins/_extends.scss, line 6

Section 1.3.2 #_getting-started.SASS.Mixins
Media Queries

Breakpoints

With this mixin you can either use straigh px values or the preset breakpoints we set in the breakpoints map. Each time you use this mixin you will need the size value and a direction parameter (min, or max).

You could also create custom media queries by changing the parameters. For example, you could make a max-height specific media query by using the following code @include mixin.breakpoint(600px, max-height){ code }.

Square

If you want an element that has equal height and width, you can build one using the @include square() mixin. All you need is to enter a value being the height and width of the square you want to build. So @include mixins.square(2rem); for example.

Source: sass/mixins/_mixins.scss, line 6