Skip to content

Latest commit

 

History

History
222 lines (162 loc) · 7.55 KB

getStarted.adoc

File metadata and controls

222 lines (162 loc) · 7.55 KB
Raw

Getting started as a Web Developer

Purpose

You’re a Web Developer and you want to use DB UI Core in your own application. Especially for JavaScript application development, we’re recommending to have a look at DB UI Elements instead.

Options

There are multiple options how to use DB UI Core:

  • Manually copy the artifacs to your project

  • Use npm package

How to use

Download DB UI Core to get the compiled CSS (and the small parts of JavaScript), source code, or include it with npm package manager (repository on npmjs.com or yarn).

Previous to that you would need to have node.js installed on your local machine. In case you haven’t we recommend installing node via [nvm](https://github.com/nvm-sh/nvm).

Use npmjs.com or yarn (installing npm package, recommended)

In case you’d like to use DB UI Core as a dependency in your (frontend) build process and you even also care about handling DB UI Core as a dependency (e.g. for updates etc.), you need to install it as a dependency to your project and then link it within your HTML (CSS file) or within your SCSS. Please have a look into the Docs / Get Started for detailed instructions.

npm i --save @db-ui/core

This should add a new entry to your package.json file:

"dependencies": {
	…
	"@db-ui/core": "^x.y.z"
}

  • You will find the relevant files at node_modules/@db-ui/core

  • Copy all of the files from node_modules/@db-ui/core/dist to your app or link them. Most of the build tools support automatic copying.

Download or CDN references

You could as well download all of the files that you would elsewhere retrieve via the node package directly or reference them from a CDN, as provided by the several different services listed e.g. at https://yarnpkg.com/package/@db-ui/core

Integration

The integration depends on your tech stack and varies from copying the files from node_modules/@db-ui/core/dist, through using a bundler like webpack or rollup to using a framework that totally abstracts that part away from your workflow.

Via HTML stylesheet include

<link rel="stylesheet" href="<PATH>/enterprise/db-ui-core.css" type="text/css">

Via SCSS import

@import "@db-ui/core/sources/css/enterprise/db-ui-core";

SCSS: node_modules include path / load path

Please keep in mind, that you would need to set your include path also known as load path depending on your setup for the sass compiler to find the correct node_modules folder, e.g. like the following (this is similar to how other frameworks and libraries like Bootstrap are handling this):

sass compiler

{
	"scripts": {
    	"css-compile": "sass --load-path=node_modules style.scss:style.css",
	}
}

node-sass Compiler

{
	"scripts": {
    	"css-compile": "node-sass --include-path node_modules style.scss -o assets/css/",
	}
}

Example: how to use DB UI Core in Angular

First install npm package as described above. Now you can choose if you want to use compiled css files or sass files.

Tip
 We recommend to import the scss files as in case of angular, the angular cli will optimize, compress and convert all assets automatically during the build process.

Independently you need to add to angular.json a new line to assets like this:

"assets": [
	"src/favicon.ico",
	"src/assets",
	"src/site.webmanifest",
	{ "glob": "**/*", "input": "node_modules/@db-ui/core/dist", "output": "." }
],
"stylePreprocessorOptions": {
    "includePaths": [
        "node_modules/"
    ]
}

It will copy on npm build the content of core/dist folder to dist folder in the angular app, that is deployed on ng serve and will give you access to assets like images, icons, etc. exported by DB UI Core. Don’t forget to add it to any necessary configuration part included, like e.g. projects.PROJECTNAME.architect.build.options as well as projects.PROJECTNAME.architect.test.options

Use scss files:

You can use the overall scss file or pick the relevant parts. E.g. you can import the overall scss files to your src/styles.scss by adding the following imports based on your bundler in use.

Webpack based bundlers (e.g. Angular or Vue CLI)

@import "@db-ui/core/sources/css/webpack.assets-paths";
@import "@db-ui/core/sources/css/enterprise/db-ui-core";

Please keep in mind, that you would need to set your include path within the angular.json configuration file, like this:

"stylePreprocessorOptions": {
    "includePaths": [
        "node_modules/"
    ]
}

Or within your vue.config.js (for Vue 2 or 3 CLI):

module.exports = {
  (...)
  css: {
    loaderOptions: {
      sass: {
        sassOptions: {
          includePaths: [path.resolve(__dirname, "node_modules")],
        },
      },
    },
  },
};

Rollup based bundlers (e.g. Vue with Vite)

For Rollup based bundlers like Vite or Parcel we’re providing the following SCSS endpoint:

@import "@db-ui/core/sources/css/rollup.assets-paths";
@import "@db-ui/core/sources/css/enterprise/db-ui-core";

Use css files:

If you want to use the compiled CSS directly, you can refence the css files in your index.html like this:

<link rel="stylesheet" href="css/enterprise/db-ui-core.css" type="text/css">

Example 2: how to use DB UI Core in Create React app

Create React App offers only limited access to the configuration of the production build. While it uses webpack under the hood, the webpack configuration is not exposed to the user. To manage your CRA to work with SASS include Path you have to update or create your .env file:

SASS_PATH=node_modules

In addition to get the asset paths working you have to load them separately. Further description is written above within the section webpack based bundlers.

@import "@db-ui/core/sources/css/webpack.assets-paths";
@import "@db-ui/core/sources/css/enterprise/db-ui-core";

Documentation

Please find our Architectural Decision Records within the adr subfolder.

We’re documenting our work via AsciiDoc files: http://asciidoc.org/ / https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

JavaScript polyfill necessary for Microsoft Internet Explorer 11 and Edge version 12 till 14

In general we’re using CSS variables / CSS Custom Properties which would need a polyfill for Microsoft Internet Explorer 11 and Edge version 12 till 14 support like ie11CustomProperties.