systelab-components
TypeScript icon, indicating that this package has built-in type declarations

17.1.5 • Public • Published

systelab-components

systelab-components is a set of components that use wide accepted and adopted standard technologies like Angular and Bootstrap, as well as other popular libraries. Please read the ATTRIBUTION.md file for a complete list of dependencies.

Bootstrap 4 knowledge will be very useful to understand and use the library, as is based on it.

Using the library

In order to use the library, the first step will be to add the dependency in your package.json

npm install systelab-components --save

After, you must add the following styles, stylePreprocessorOptions and scripts in the angular.json file,

"styles": [
        "node_modules/ag-grid-community/dist/styles/ag-grid.css",
        "node_modules/ag-grid-community/dist/styles/ag-theme-fresh.css",
        "node_modules/primeng/resources/themes/nova-light/theme.css",
        "node_modules/primeng/resources/primeng.min.css",
        "node_modules/primeicons/primeicons.css,
        "node_modules/systelab-components/icons/icomoon.css",
        "node_modules/@fortawesome/fontawesome-free/css/all.css"
      ],
"stylePreprocessorOptions": {
  "includePaths": [
    "node_modules"
  ]
},      
"scripts": [
        "node_modules/jquery/dist/jquery.min.js",
        "node_modules/popper.js/dist/umd/popper.js",
        "node_modules/bootstrap/dist/js/bootstrap.js",
        "node_modules/pako/dist/pako.min.js"
      ],

Be careful because you will not probably need all fontawesome 5.x. Instead, you can add:

  • brands.css
  • fontawesome.css
  • regular.css
  • solid.css

After, you must import SystelabComponentsModule, as well as other libraries, in your Application Module:

NgModule({
    imports: [
        BrowserModule,
        FormsModule,
        HttpClientModule,
        DragDropModule,
        SystelabTranslateModule,
        SystelabPreferencesModule,
        SystelabLoginModule,
        SystelabComponentsModule.forRoot({productionMode: false}),
        AgGridModule.withComponents([
            GridContextMenuCellRendererComponent,
            GridHeaderContextMenuComponent
        ]),
    ...

You can config some application parameters using the forRoot method:

    enum ToastSize {
        small = 'small',
        large = 'large'
    }
  {
    productionMode: boolean;
    toast?: {
      autoWidth: boolean,
      fixedSize: ToastSize,
      showCloseButton: boolean,
      timeout: number,
    }
  }

The forRoot method is optional. By default, the module is configured with:

{
    productionMode: true,
    toast: {
        autoWidth: false,
      fixedSize: ToastSize.small,
      showCloseButton: false,
      timeout: 5000,
    }
}

If you need to import SystelabComponentsModule in a lazy loaded module you must use it without call the forRoot method again. If you call twice or more, you will receive an error in your console.

NgModule({
    imports: [
        SystelabComponentsModule
    ]
})

Finally, you must import the systelab-components sass file in the general styles file in src/styles.scss.

In the following example, for the component AppComponent we are not setting styleUrl due to the component will use the styles defined in src/styles.scss.

@Component({
    selector:      'app-root',
    templateUrl:   'app.component.html'
})
export class AppComponent {

    constructor(protected preferencesService: PreferencesService, protected i18nService: I18nService) {
        ...
    }
}

src/styles.scss file is visible to AppComponent because is referenced in styles of angular.json file.

"styles": [
        "node_modules/ag-grid/dist/styles/ag-grid.css",
        "node_modules/ag-grid/dist/styles/ag-theme-fresh.css",
        "node_modules/primeng/resources/themes/omega/theme.css",
        "node_modules/primeng/resources/primeng.min.css",
        "node_modules/systelab-components/icons/icomoon.css",
        "src/styles.scss"
      ],

In the sass file src/styles.scss, we have imported systelab-components sass style.

@import "systelab-components/sass/systelab-components";

Import the modern styles in order to be in the last version:

@import "systelab-components/sass/modern/systelab-components";

Bootstrap package is a dependency for systelab-components, and npm will download it.

Changing the default style

Depending on the imported sass file, the style will be the default classic one or the modern one.

Remember that for the modern style, it is mandatory to specify the modifier classes for the buttons. Please review https://getbootstrap.com/docs/4.0/components/buttons/ for the available class options.

In both options it is possible to change the default Bootstrap or systelab-components settings (like colors, border-radius, etc...) by adding or changing the value of any property defined in the scss file before importing the standard. For example:

$slab-size-percentage: 1;
$primary: rgb(0, 154, 181);

@import "systelab-components/sass/modern/systelab-components";

All values defined in Bootstrap _variables.scss and systelab-components _variables.scss (classic style) or _variables.scss (modern style) can be overwritten.

Anyway, think it twice before you change this settings and think in the value of having a homogeneous look and feel.

Schematics

In order to generate some components, install systelab-schematics

npm install -D systelab-schematics --save

Components

A bunch of different components and utilities are provided as part of the library. In the folder with the implementation of each component, you will find documentation about how to use it. In the showcase you will find examples.

As this components will be placed in a container, in the following sections you will find some tips about how to do it. Please check our application frame, dialog as a base containers of the layout.

The following table summarizes all the components included in the library.

Component Description
systelab-add-remove-list A list with elements to add and remove
systelab-app-frame Application frame, using a header and a sidebar
systelab-app-header Application header
systelab-app-sidebar Application side bar
systelab-button Component to trigger an action
systelab-breadcrumb Component to allows users to keep track and maintain awareness of their locations
systelab-calendar-header Calendar header with navigation
systelab-calendar-table Month view custom calendar
systelab-colorpicker Color picker
systelab-combobox Classes that lets you create a combo box component
systelab-context-menu Context menu
systelab-datepicker Date picker
systelab-date-time Date and time picker
systelab-file-selector File selector
systelab-grid Classes that lets you create a grid component
systelab-image-viewer Component to display and manipulate images
systelab-listbox Classes that lets you create a list box component
systelab-loading Widget to show that an action is being performed
systelab-dialog Classes to show a dialog
systelab-message-popup Classes to show a popup
systelab-month-selector Component to show a Month Selector
systelab-navbar Component to show a Navbar
systelab-numpad Component to show a Numeric Keyboard dialog for an Input Text
systelab-paginator Component for page navigation
systelab-percentage-circle Component to show a percentage indicator
systelab-searcher Abstract classes that lets you create a Searcher component
systelab-select Component to select a value form a predefined list
systelab-signature-canvas Component to show a canvas where the user can draw their signature
systelab-slider Component to select a numerical value inside a range
systelab-sortable-list Abstract class that lets you create a Listbox with sortable elements
systelab-spinner Component to select a numerical value inside a range
systelab-switch Component to select between two values
systelab-tabs Component to show more than one panel
systelab-timeline Component to show a vertical timeline
systelab-toast Component to show a small toast
systelab-toggle-button Component to select between two values
systelab-toggle-selector Component to select between a list of options
systelab-tooltip Directive to show tooltip on hover event
systelab-tree Abstract class that lets you create a Tree component
abstract-systelab-tree Abstract class that lets you create a Tree component with CDK
systelab-twolist Component to select a group of elements from elements list
systelab-week-selector Component to show a Week Selector
systelab-wizard-steps Component to show a Wizard

Layout

To manage the layout, alignment, and sizing of grid columns, navigation, components, ... you can use the Bootstrap Grid or Flexbox.

As a general tip:

  • If you want to let your content control the way it is displayed, on a row by row or column by column basis, that’s flexbox.
  • Or, if you want to define a grid, and either allow items to be auto-placed into the cells defined by that grid, or control their positioning using line-based positioning or grid template areas, that’s grid.

If still is not clear for you what to do, we suggest:

Use the grid for forms or layouts where the height is defined by the components. Use flex if the height is important for you, for example when you are defining a application like layout.

For the grid, refer to https://getbootstrap.com/docs/4.0/layout/grid/.

For the Flexbox, refer to https://css-tricks.com/snippets/css/a-guide-to-flexbox/ as a general guide and check https://getbootstrap.com/docs/4.0/utilities/flex/ to better know the utility classes that Bootstrap provides.

As a super basic summary:

  • Use .d-flex to set a flex box container. By default the container will arrange the elements in a single row. Use flex-column to arranges the items in a column.
  • Use justify-content-end, justify-content-center, justify-content-between, justify-content-around if they are needed.
  • Place your elements inside the box container and use .slab-flex-1 in the element that you want to grow (internally applies the style flex: 1).
  • Apply the same pattern to the containers that you place inside to get more complex layouts.

In the following example, the div in the middle will grow:

<div class="d-flex flex-column">
    <div class="bg-info">Info</div>
    <div class="slab-flex-1 bg-success"></div>
    <div class="bg-white">White</div>
</div>

Combine as needed. In this case will have elements placed in the north (info), south (white), west (warning), east (danger) and in the center (success).

<div class="d-flex flex-column">
    <div class="bg-info">Info</div>
    <div class="slab-flex-1 d-flex flex-row">
        <div class="bg-warning">Warning</div>
        <div class="slab-flex-1 bg-success">
        </div>
        <div class="bg-danger">Danger</div>
    </div>
    <div class="bg-white">White</div>
</div>

Use .ml-auto in a flex container if you want to push the item to the left. This will be helpful for example to push a button and place it to the bottom right of a dialog.

Use .slab-overflow-container for the element that could/should scroll.

Forms

Check the folder forms to get an introduction and some examples about how to design forms forms.

Borders

Check the Bootstrap utilities at https://getbootstrap.com/docs/4.0/utilities/borders/ to add some borders.

As a super basic summary:

Add .border and .rounded, and probably some margin classes, if you want a classical gray rounded border.

Responsiveness:

Use bootstrap utilities to add responsiveness to your layout. Equivalence between versions 3.x and 4.x are:

  • Show/hide for breakpoint and down:

    • hidden-xs-down (hidden-xs) = d-none d-sm-block
    • hidden-sm-down (hidden-sm hidden-xs) = d-none d-md-block
    • hidden-md-down (hidden-md hidden-sm hidden-xs) = d-none d-lg-block
    • hidden-lg-down = d-none d-xl-block
    • hidden-xl-down (n/a 3.x) = d-none (same as hidden)
  • Show/hide for breakpoint and up:

    • hidden-xs-up = d-none (same as hidden)
    • hidden-sm-up = d-sm-none
    • hidden-md-up = d-md-none
    • hidden-lg-up = d-lg-none
    • hidden-xl-up (n/a 3.x) = d-xl-none
  • Show/hide only for a single breakpoint:

    • hidden-xs (only) = d-none d-sm-block (same as hidden-xs-down)
    • hidden-sm (only) = d-block d-sm-none d-md-block
    • hidden-md (only) = d-block d-md-none d-lg-block
    • hidden-lg (only) = d-block d-lg-none d-xl-block
    • hidden-xl (n/a 3.x) = d-block d-xl-none
    • visible-xs (only) = d-block d-sm-none
    • visible-sm (only) = d-none d-sm-block d-md-none
    • visible-md (only) = d-none d-md-block d-lg-none
    • visible-lg (only) = d-none d-lg-block d-xl-none
    • visible-xl (n/a 3.x) = d-none d-xl-block

Package Sidebar

Install

npm i systelab-components

Weekly Downloads

711

Version

17.1.5

License

MIT

Unpacked Size

6.96 MB

Total Files

394

Last publish

Collaborators

  • aserra
  • systelab-technologies
  • olgapuig