From 1c6b42106213055d4679b138df7f0988b5db87c2 Mon Sep 17 00:00:00 2001 From: Rene Haas Date: Wed, 9 Nov 2022 11:00:52 +0100 Subject: [PATCH] improve readme --- packages/overlayscrollbars-ngx/README.md | 176 +++++++++++++++++++-- packages/overlayscrollbars-react/README.md | 2 +- packages/overlayscrollbars-vue/README.md | 4 +- 3 files changed, 165 insertions(+), 17 deletions(-) diff --git a/packages/overlayscrollbars-ngx/README.md b/packages/overlayscrollbars-ngx/README.md index 6b0f9ec..ce22ad0 100644 --- a/packages/overlayscrollbars-ngx/README.md +++ b/packages/overlayscrollbars-ngx/README.md @@ -1,27 +1,175 @@ -# Test +
+ + OverlayScrollbars + + + Angular + +
+
+ + OverlayScrollbars + + + Angular + + + Downloads + + + Version + + + License + +
-This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.6. +# OverlayScrollbars for Angular -## Development server +This is the official OverlayScrollbars Angular wrapper. -Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files. +## Installation -## Code scaffolding +```sh +npm install overlayscrollbars-ngx +``` -Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`. +## Peer Dependencies -## Build +OverlayScrollbars for Angular has the following **peer dependencies**: -Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. +- The vanilla JavaScript library: [overlayscrollbars](https://www.npmjs.com/package/overlayscrollbars) -## Running unit tests +``` +npm install overlayscrollbars +``` -Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io). +- The Angular framework: [@angular/core](https://www.npmjs.com/package/@angular/core) -## Running end-to-end tests +``` +npm install @angular/core +``` -Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities. +## Usage -## Further help +The first step is to import the CSS file into your app: +```ts +import 'overlayscrollbars/overlayscrollbars.css'; +``` -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page. +> __Note__: In older node versions use `'overlayscrollbars/styles/overlayscrollbars.css'` as the import path for the CSS file. + +The module can be imported like: + +```js +import { NgModule } from "@angular/core"; +import { OverlayscrollbarsModule } from "overlayscrollbars-ngx"; + +@NgModule({ + imports: [OverlayscrollbarsModule], +}) +export class AppModule {} +``` + + +## Component + +The main entry point is the `OverlayScrollbarsComponent` which can be used in your application as a component: + +```js +import { OverlayScrollbarsComponent } from "overlayscrollbars-ngx"; +``` + +The component can be used with two different selectors: + +```html +
+ Like this you can choose the tag +
+ + + If the tag isn't important + +``` + +### Properties + +It has two optional properties: `element`, `options` and `events`. + +- `options`: accepts an `object` which represents the OverlayScrollbars options. +- `events`: accepts an `object` which represents the OverlayScrollbars events. + +```html + + +``` + +### Events + +Additionally to the `events` property the `OverlayScrollbarsComponent` emits "native" Angular events. To prevent name collisions with DOM events the events have a `os` prefix. + +> __Note__: It doesn't matter whether you use the `events` property or the Angular events or both. + +```html + +
+``` + +```ts +import type { EventListenerArgs } from 'overlayscrollbars'; + +// example listener +onUpdated([instance, onUpdatedArgs]: EventListenerArgs['updated']) {} +``` + +### Ref + +The `ref` of the `OverlayScrollbarsComponent` will give you an object with which you can access the OverlayScrollbars `instance` and the root `element` of the component. +The ref object has two properties: + +- `instance`: a function which returns the OverlayScrollbars instance. +- `element`: a function which returns the root element. + +## Directive + +In case the `OverlayScrollbarsComponent` is not enough, you can also use the `OverlayScrollbarsDirective` directive: + +```js +import { OverlayScrollbarsDirective } from "overlayscrollbars-ngx"; +``` + +```html + +
+``` + +The directive is for advanced usage and lets you control the whole initialization process. This is useful if you want to integrate it with other plugins. + +> __Note__: The directive won't initialize OverlayScrollbars on its own. You have to call the `initialize` function. + +### Properties + +Properties are optional and similar to the `OverlayScrollbarsComponent`. + +- `options`: accepts an `object` which represents the OverlayScrollbars options. +- `events`: accepts an `object` which represents the OverlayScrollbars events. + +### Instance + +The `OverlayScrollbarsDirective` exposes two functions: + +- `initialize` takes one argument which is the `InitializationTarget` and returns the OverlayScrollbars instance. +- `instance` returns the current OverlayScrollbars instance or `null` if not initialized. + +## License + +MIT diff --git a/packages/overlayscrollbars-react/README.md b/packages/overlayscrollbars-react/README.md index e139a7c..7826367 100644 --- a/packages/overlayscrollbars-react/README.md +++ b/packages/overlayscrollbars-react/README.md @@ -2,7 +2,7 @@ OverlayScrollbars - + React diff --git a/packages/overlayscrollbars-vue/README.md b/packages/overlayscrollbars-vue/README.md index 92d07c6..82f60a2 100644 --- a/packages/overlayscrollbars-vue/README.md +++ b/packages/overlayscrollbars-vue/README.md @@ -2,7 +2,7 @@ OverlayScrollbars - + Vue @@ -134,7 +134,7 @@ const Component = { initialize({ target: div.value }); }); - onBeforeUnmount(() => { + onUnmounted(() => { instance().destroy(); });