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.
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" |
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.
sass/_getting-started.scss
, line 47
Section 1.2.1
#_getting-started.JavaScript.VueJS
VueJS
General Component Structure
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>
sass/_getting-started.scss
, line 68
Section 1.3
#_getting-started.SASS
SASS
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.
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 |
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.
sass/mixins/_mixins.scss
, line 6