Skip to content

Commit

Permalink
feat(stark-demo): creation of a getting started page
Browse files Browse the repository at this point in the history 
ISSUES CLOSED: #720
  • Loading branch information
@Mallikki
Mallikki committed Nov 7, 2018
1 parent 3609bfb commit 8c98965
Show file tree
Hide file tree
Showing 25 changed files with 905 additions and 5 deletions.
2 changes: 2 additions & 0 deletions packages/stark-ui/assets/styles/_media-queries.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ $mobile-only-query: "(max-width: 599px)";
$mobile-only-screen-query: "screen and (max-width: 599px)";
$tablet-only-query: "(min-width: 600px) and (max-width: 959px)";
$tablet-only-screen-query: "screen and (min-width: 600px) and (max-width: 959px)";
$handset-toc-query-screen:"(min-width: 0px) and (max-width: 839px)";
$tablet-toc-query-screen:"(min-width: 840px) and (max-width: 1279px)";
1 change: 1 addition & 0 deletions packages/stark-ui/assets/styles/_old-variables.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ $stark-footer-size: 24px;
$primary-dark-text-color: map-get($mat-light-theme-foreground, base);
$secondary-dark-text-color: rgba(0, 0, 0, 0.7);
$tertiary-dark-text-color: rgba(0, 0, 0, 0.45);
$custom-dark-background: rgba(39, 40, 34, 1);

$disabled-color: map-get($mat-light-theme-foreground, disabled-text);
$divider-color: map-get($mat-light-theme-foreground, divider);
Expand Down
2 changes: 1 addition & 1 deletion showcase/src/app/app.component.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ export class AppComponent implements OnInit {
label: "Getting started",
isVisible: true,
isEnabled: true,
targetState: "#"
targetState: "getting-started"
},
{
id: "menu-news",
Expand Down
2 changes: 2 additions & 0 deletions showcase/src/app/app.module.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ import { APP_STATES } from "./app.routes";
import { AppComponent } from "./app.component";
import { HomeComponent } from "./home";
import { NoContentComponent } from "./no-content";
import { GettingStartedModule } from "./getting-started";
/* tslint:disable:no-import-side-effect */
// load PostCSS styles
import "../styles/styles.pcss";
Expand Down Expand Up @@ -221,6 +222,7 @@ export const metaReducers: MetaReducer<State>[] = ENV !== "production" ? [logger
}
}),
SharedModule,
GettingStartedModule,
StarkAppFooterModule,
StarkAppLogoModule,
StarkAppLogoutModule,
Expand Down
7 changes: 7 additions & 0 deletions showcase/src/app/app.routes.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { HomeComponent } from "./home";
import { NoContentComponent } from "./no-content";
import { Ng2StateDeclaration } from "@uirouter/angular";
import { AppComponent } from "./app.component";
import { GettingStartedComponent } from "./getting-started/getting-started-component";

export const APP_STATES: Ng2StateDeclaration[] = [
{
Expand All @@ -15,6 +16,12 @@ export const APP_STATES: Ng2StateDeclaration[] = [
views: { "@": { component: HomeComponent } },
parent: "app"
},
{
name: "getting-started",
url: "^/getting-started",
views: { "@": { component: GettingStartedComponent } },
parent: "app"
},
{
name: "news.**",
url: "^/news", // use ^ to avoid double slash "//" in the URL after the domain (https://github.com/angular-ui/ui-router/wiki/URL-Routing#absolute-routes-)
Expand Down
30 changes: 30 additions & 0 deletions showcase/src/app/getting-started/getting-started-component/_getting-started-theme.scss
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
.file-structure-title {
color: mat-color($grey-palette, 900);
}

.custom-title {
color: mat-color($grey-palette, 900);
}

.custom-subtitle {
color: mat-color($grey-palette, 800);
}

.custom-code {
font-family: monospace;
background-color: mat-color($grey-palette, 200);
}

.custom-section {
& a {
text-decoration: none;
}
}

.custom-pretty-print {
& pre {
background-color: $custom-dark-background;
border-radius: 0.3em;
}
color: mat-color($grey-palette, 100);
}
59 changes: 59 additions & 0 deletions showcase/src/app/getting-started/getting-started-component/_getting-started.component.scss
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
.getting-started-content {
padding-right: 200px;
}

.file-structure-title {
font-size: 21px;
padding-bottom: 0;
display: inline-flex;
vertical-align: middle;
margin: 10px 0 10px 0;
}

.structure-description-margin {
margin-bottom: 20px;
margin-top: 20px;
}

.description {
align-self: center;
}

@media #{$mobile-only-query} {
.getting-started-content {
padding-right: 0;
}
}

.custom-title {
font-size: 27px;
display: block;
vertical-align: middle;
margin: 40px 0 10px 0;
}

.custom-subtitle {
font-size: 20px;
display: block;
vertical-align: middle;
margin: 15px 0 10px 0;
}

.custom-code {
padding: 0.2em 0.4em;
margin: 0;
font-size: 85%;
border-radius: 3px;
}

.table-of-contents-level-h2 {
padding-left: 12px;
}

.custom-pretty-print {
& pre {
white-space: pre;
overflow-x: scroll;
font-size: 13px;
}
}
219 changes: 219 additions & 0 deletions showcase/src/app/getting-started/getting-started-component/getting-started.component.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
<div class="getting-started-content">
<div class="mat-display-2">Getting started</div>

<table-of-contents headerSelectors=".custom-title,.custom-subtitle"></table-of-contents>

<section class="stark-section structure-description-margin custom-section">
<h1 id="install-stark" class="custom-title">How to install Stark ?</h1>
<p>To install Stark, you have to make sure your system is well configured, and then simply install the packages
you need.</p>
<h2 id="system_configuration" class="custom-subtitle">System Configuration</h2>
<p>Ensure that you are running the latest version:</p>
<ul>
<li>Node 8.x.x +</li>
<li>NPM 5.8.x +</li>
</ul>
<p>If you have <span class="custom-code">nvm</span> installed, which is highly recommended, you can do a
<span class="custom-code">nvm install --lts && nvm use</span> in <span class="custom-code">$</span>
to run with the latest Node LTS. You can also have this<span class="custom-code">zsh</span> done for you
<a class="custom-link"
href="https://github.com/creationix/nvm#calling-nvm-use-automatically-in-a-directory-with-a-nvmrc-file"
target="_blank">automatically</a>.</p>

<h2 id="packages_installation" class="custom-subtitle">Packages installation</h2>

<p>To install the different packages of the Stark framework, for example, the stark-core package, just do: </p>
<span class="custom-code">npm install "@nationalbankbelgium/stark-core"</span>
<p>Those packages are available at the following locations in NPM: </p>
<ul>
<li><a href="https://www.npmjs.com/package/@nationalbankbelgium/stark-core" target="_blank">stark-core</a>
</li>
<li><a href="https://www.npmjs.com/package/@nationalbankbelgium/stark-ui" target="_blank">stark-ui</a></li>
<li><a href="https://www.npmjs.com/package/@nationalbankbelgium/stark-build" target="_blank">stark-build</a>
</li>
<li><a href="https://www.npmjs.com/package/@nationalbankbelgium/stark-testing"
target="_blank">stark-testing</a></li>
</ul>
</section>

<section class="stark-section structure-description-margin custom-section">
<h1 id="stark_starter" class="custom-title">Using the Stark Starter</h1>

<p>The Starter project is an empty project using the Stark framework, that you can adapt as you want.</p>
<p>To do so, you'll have to simply clone the repository, adapt your configuration if needed and then, run it
once you've made the changes you want.</p>
<p>Of course, you'll be able to run tests as well, such as unit tests and E2E tests. </p>

<h2 id="clone_repo" class="custom-subtitle">Clone the repository</h2>

<p>To clone the project, use the following command line: </p>
<stark-pretty-print [data]="installingProject" format="html"
[enableHighlighting]="true"></stark-pretty-print>
<p>Then, go to the starter folder (<span class="custom-code">cd starter</span>) and install all dependencies
using:
<span class="custom-code">npm install</span></p>

<h2 id="adapt_configuration" class="custom-subtitle">Adapt the configuration</h2>
<p>Most of the configuration files at the root of the starter either fully reuse or extend Stark's configuration
files.</p>
<p>Most of the time you won't need to change these, but they allow you to customize things when needed.</p>
<p>Here is the file structure for the Starter project: </p>
<stark-pretty-print class="custom-pretty-print" [data]="structure"></stark-pretty-print>

<h2 id="app_running" class="custom-subtitle">Running the application</h2>
<p>Have you already installed all dependencies? Then you can run the app! Run <span
class="custom-code">npm run server</span> to start a local (development) server using <span
class="custom-code">webpack-dev-server</span> which will watch,
build (in-memory), and reload for you. The port will be displayed to you as <span class="custom-code">http;//0.0.0.0:3000</span>
(or if you prefer IPv6, if you're using <span class="custom-code">express</span> server, then it is
<span class="custom-code">http://[::1]:3000</span>).</p>
<p>You may enable Hot Module Replacement (HMR) using:</p>
<stark-pretty-print [data]="runningHMR" format="html" [enableHighlighting]="true"></stark-pretty-print>

<p>You may also start the server in production mode using the following</p>
<stark-pretty-print [data]="runningProject" format="html" [enableHighlighting]="true"></stark-pretty-print>

<p>To build the files themselves, simply use:</p>
<stark-pretty-print [data]="buildFiles" format="html" [enableHighlighting]="true"></stark-pretty-print>

<p>To run the watch mode:</p>
<stark-pretty-print [data]="watchMode" format="html" [enableHighlighting]="true"></stark-pretty-print>

<h2 id="unit_tests" class="custom-subtitle">Unit testing</h2>

<p>Simply enter the following command line: </p>
<stark-pretty-print [data]="unitTestRunning" format="html" [enableHighlighting]="true"></stark-pretty-print>
<p>And you can also enable the watch mode for the following</p>
<stark-pretty-print [data]="watchAndRunTests" format="html" [enableHighlighting]="true"></stark-pretty-print>

<h2 id="e2e_tests" class="custom-subtitle">E2E testing</h2>
<p>The command line to execute E2E tests is similar than the one for unit tests: </p>
<stark-pretty-print [data]="runEndToEndTests" format="html" [enableHighlighting]="true"></stark-pretty-print>

<p>Be aware that you can execute both unit tests and E2E tests with the same command line: </p>
<stark-pretty-print [data]="continuousIntegrationTests" format="html"
[enableHighlighting]="true"></stark-pretty-print>
</section>

<section class="stark-section custom-section">
<h1 id="good_to_know" class="custom-title">Good to know</h1>
<h2 id="aot_donts" class="custom-subtitle">AoT Don'ts</h2>
<p>In the following list are some actions that will make AoT compile fail:</p>
<ul>
<li>Don’t use require statements for your templates or styles, use styleUrls and templateUrls, the
angular2-template-loader plugin will change it to require at build time.
</li>
<li>Don’t use default exports.</li>
<li>Don’t use <span class="custom-code">form.controls.controlName</span>, use <span class="custom-code">form.get(‘controlName’)</span>
</li>
<li>Don’t use <span class="custom-code">control.errors?.someError</span>, use <span class="custom-code">control.hasError(‘someError’)</span>
</li>
<li>Don’t use functions in your providers, routes or declarations, export a function and then reference
that
function name
</li>
<li>@Inputs, @Outputs, View or Content Child(ren), Hostbindings, and any field you use from the template
or
annotate for Angular should be public
</li>
</ul>

<h2 id="typedef" class="custom-subtitle">Type definitions</h2>
<p>When including 3rd party modules you also need to include the type definition for the module.
When you include a module that doesn't include TypeScript type definitions inside of the module you can
include
external type definitions with @types</p>
<stark-pretty-print [data]="installType" format="html"
[enableHighlighting]="true"></stark-pretty-print>

<p>If you can't find the type definition in the registry then you can make use of an ambient definition in
the
custom-typings.d.ts file.</p>
<p>For example:</p>
<stark-pretty-print [data]="moduleDeclaration" format="typescript"
[enableHighlighting]="true"></stark-pretty-print>

<p>If you're prototyping and you will fix the types later you can also declare it as type any:</p>
<stark-pretty-print [data]="prototyping" format="typescript"
[enableHighlighting]="true"></stark-pretty-print>

<p>If you're importing a module that uses Node.js modules which are CommonJS you need to import as</p>
<stark-pretty-print [data]="moduleImport" format="typescript"
[enableHighlighting]="true"></stark-pretty-print>

<h2 id="external_stylesheets" class="custom-subtitle">External Stylesheets</h2>
<p>If you wish to import your own stylesheets in the Starter Project, go to the following location in the project: </p>
<stark-pretty-print class="custom-pretty-print" [data]="stylesheetImport" format="typescript"></stark-pretty-print>
<p>In the <span class="custom-code">styles.css</span> file, you can import what you need from other libraries but also
your own styles: </p>
<stark-pretty-print [data]="stylesCSS" format="CSS"
[enableHighlighting]="true"></stark-pretty-print>
<p>In that file, it is mandatory to import the <span class="custom-code">stark-styles.scss</span> file, as it is in that file that
the styles from the Stark components will be imported. You can edit that file as well and take only the files that your project
needs. So if you like one of our components but not the style associated to it, you can define your own style for it! </p>
<p>The <span class="custom-code">stark-styles.scss</span> file looks like the following; </p>
<stark-pretty-print [data]="starkStylesCSS" format="CSS"
[enableHighlighting]="true"></stark-pretty-print>
</section>

<section class="stark-section custom-section">
<h1 id="faq" class="custom-title">FAQ</h1>

<ul>
<li> How do I start the app when I get <span class="custom-code">EACCES</span> and <span
class="custom-code">EADDRINUSE</span>
errors?
<ul>
<li>The <span class="custom-code">EADDRINUSE</span> error means the port <span
class="custom-code">3000</span>
is currently being used and <span class="custom-code">EACCES</span> is lack of permission
for
webpack to build files to <span class="custom-code">./dist/</span></li>
</ul>
</li>
<li> Error: Cannot find module 'tapable'
<ul>
<li>Remove <span class="custom-code">node_modules/</span> and run <span class="custom-code">npm cache clean</span>
then <span class="custom-code">npm install</span></li>
</ul>
</li>
<li> How do I turn on Hot Module Replacement
<ul>
<li>Run <span class="custom-code">npm run server:dev:hmr</span></li>
</ul>
</li>
<li><span class="custom-code">RangeError: Maximum call stack size exceeded</span>
<ul>
<li>This is a problem with minifying Angular and its recent JIT templates.
If you set <span class="custom-code">mangle</span> to <span class="custom-code">false</span>
then
you should be good
</li>
</ul>
</li>
<li>Why is the size of my app larger in development?
<ul>
<li>We are using inline source-maps and hot module replacement which will increase the bundle
size.
</li>
</ul>
</li>
<li>If you're in China
<ul>
<li>check out <a class="custom-link" href="https://github.com/cnpm/cnpm"
target="_blank">cnpm</a></li>
</ul>
</li>
<li>node-pre-gyp ERR in npm install (Windows)
<ul>
<li>install Python x86 version between 2.5 and 3.0 on windows</li>
<li>or try <span class="custom-code">--no-optional</span></li>
</ul>
</li>
</ul>

</section>
</div>



Loading

0 comments on commit 8c98965

Please sign in to comment.