From 621e8dd1344ae0e346951a301d00b3745e567524 Mon Sep 17 00:00:00 2001 From: svetoldo4444ka Date: Thu, 5 Apr 2018 15:09:56 +0300 Subject: [PATCH] docs(getting-started): update readme.md and bootstrap.md files (#3933) * docs(documentation): update readme and bootstrap.md files * docs(readme): fix conflicts * docs(readme): fix conflicts * docs(getting-started): update readme.md and bootstrap.md files * docs(getting-started): update readme.md and bootstrap.md files according to the comments --- README.md | 77 +++++++++++------ docs/getting-started/bootstrap.md | 127 +++++++++++++++++++++++++++++ docs/getting-started/bootstrap4.md | 123 ---------------------------- 3 files changed, 178 insertions(+), 149 deletions(-) create mode 100644 docs/getting-started/bootstrap.md delete mode 100644 docs/getting-started/bootstrap4.md diff --git a/README.md b/README.md index 7f8973b7e6..d07631245c 100644 --- a/README.md +++ b/README.md @@ -35,35 +35,51 @@ Best way to quickly integrate Bootstrap 3 + Simple demo + +``` +You will need bootstrap styles: +- `Bootstrap 3` ``` ``` -Or Bootstrap 4 +- `Bootstrap 4` ``` ``` -To enable bootstrap 4 theme templates in ngx-bootstrap, please read -[this](https://github.com/valor-software/ngx-bootstrap/blob/development/docs/getting-started/bootstrap4.md) . -# Usage & Demo +## Usage & Demo Main source of API documentation and usage scenarios available here: [https://valor-software.com/ngx-bootstrap/](https://valor-software.com/ngx-bootstrap/) @@ -73,36 +89,41 @@ Additionally you can find demos and docs deployed from latest code with here -# API +## API Check demo page for API [reference](https://valor-software.com/ngx-bootstrap/) -## How to use it with: - - `angular-cli` please refer to [getting-started-with-ng-cli](https://github.com/valor-software/ngx-bootstrap/tree/development/docs/getting-started/ng-cli.md) +### How to use it with: + - `Bootstrap and angular-cli` please refer to [using-with-bootstrap-and-angular-cli](https://github.com/valor-software/ngx-bootstrap/tree/development/docs/getting-started/bootstrap.md) - `angular-seed` please refer to [getting-started-with-angular-seed](https://github.com/valor-software/ngx-bootstrap/tree/development/docs/getting-started/angular-seed.md) - `system.js` (and [angular2 quickstart](https://angular.io/docs/ts/latest/quickstart.html)) please checkout [sample repository](https://github.com/valor-software/angular2-quickstart) - - `plnkr` sample available [here](http://bit.ly/ngx-bootstrap-plnkr) + - `plnkr` sample available [here](https://plnkr.co/edit/0NipkZrnckZZROAcnjzB?p=preview) - `AoT using ngc and rollup` please refer to [ngx-bootstrap-with-aot](https://github.com/valor-software/ngx-bootstrap/tree/development/docs/getting-started/aot.md) - - `Bootstrap 4 and angular-cli` please refer to [using-with-bootstrap-4-and-angular-cli](https://github.com/valor-software/ngx-bootstrap/tree/development/docs/getting-started/bootstrap4.md) - `ASP.NET Core 2.0` please refer to [using-with-asp.net-core-2](https://github.com/csegyud/ASPNETCore_ngx-bootstrap_Sample/blob/master/README.md) -# How to build lib for development +### How to build lib for development -First time +First time: - clone repository - `npm install` - - `npm run test` it will build the lib and create a link in `node_modules` + - `npm run test` + +To update your fork and prepare it for local usage: + - `git pull upstream development` + - `rm -rf node_modules` + - `npm install` + - `npm run test` _*// it will build the lib, create a link in node_modules and run package's "test" script*_ - To run bootstrap 3 and 4 demo: - - `npm run demo.serve` to serve local demo. This is for testing only, without watchers. + To run the demo: + - `npm run demo.serve` _*// to serve local demo. This is for testing only, without watchers.*_ - For local development run - - `npm run build.watch` in first terminal - - `ng serve` in second + For local development run: + - `npm run build.watch` _*// in first terminal*_ + - `ng serve` _*// in second*_ If you want to run the demo with Angular Universal: - `npm run demo.serve-universal` -# Troubleshooting +## Troubleshooting So if you are in trouble, here's where you can look for help. @@ -111,16 +132,20 @@ You can also join [our Slack channel](https://ngx-slack.herokuapp.com/) and link If, **and only if**, none of the above helped, please open a [new issue](https://github.com/valor-software/ngx-bootstrap/issues/new). -# Contribution +## Contribution Are very welcome! And remember, contribution is not only PRs and code, but any help with docs or helping other developers to solve issues are very appreciated! Thanks in advance! Please read our [contribution guidelines](https://github.com/valor-software/ngx-bootstrap/blob/development/CONTRIBUTING.md). -## If you need more modules check [here](https://github.com/valor-software/ng2-plans) +### If you need more modules check [here](https://github.com/valor-software/ng2-plans) Please read central `ngx` modules [readme](https://github.com/valor-software/ng2-plans) for details, plans and approach -## Credits +### Credits Crossbrowser testing sponsored by [Browser Stack](https://www.browserstack.com) [Browser Stack](https://www.browserstack.com) + +### License + +MIT diff --git a/docs/getting-started/bootstrap.md b/docs/getting-started/bootstrap.md new file mode 100644 index 0000000000..ba7f343d11 --- /dev/null +++ b/docs/getting-started/bootstrap.md @@ -0,0 +1,127 @@ +# Using with Bootstrap and angular-cli + +This is extracted from the [angular-cli include bootstrap story](https://github.com/angular/angular-cli/wiki/stories-include-bootstrap) and demonstates one way to accomplish using Bootstrap 3 or 4 with ngx-bootstrap. The `Bootstrap's` version is defined automatically by the `ngx-bootstrap`. + +## Installing angular-cli + +*Recommended*: to use latest stable `angular-cli` version. + +*Note*: You can skip this part if you already have application generated by `ng-cli` and webpack. + +```bash +npm i -g @angular/cli +ng new my-app +cd my-app +ng serve +``` + +## Adding ngx-bootstrap and Bootstrap + + - install `ngx-bootstrap` and `Bootstrap` + + ```bash + npm install ngx-bootstrap bootstrap --save + ``` + +## Using with css +### Configuring Project + +Now that the project is set up it must be configured to include the Bootstrap CSS. You have two options: + + - add styles to .angular-cli.json: + - Open the file .angular-cli.json from the root of your project. + - Under the property apps the first item in that array is the default application. + - There is a property styles which allows external global styles to be applied to your application. + + - Specify the path to bootstrap.min.css + + It should look like the following when you are done: + ``` + "styles": [ + "../node_modules/bootstrap/dist/css/bootstrap.min.css", + "styles.css" + ], + ``` + + Note: When you make changes to .angular-cli.json you will need to re-start ng serve to pick up configuration changes. + + - add styles to index.html: + - for Bootstrap 3: + ``` + + ``` + + - or for Bootstrap 4: + ``` + + ``` + +## Using SASS + +### Configuring Project + +Ensure that the project is set up to use scss by default and that the main styles file is styles.scss + +The easiest way to do this is when creating a new project by +```bash +ng new my-app --style=scss +cd my-app +``` + +If the project has already been created then + +- rename `src/styles.css` to `src/styles.scss` +- in `.angular-cli.json` make the following changes +``` +"styles": [ + "styles.css" <-- rename this from .css to .scss +], +. +. +. +"defaults": { + "styleExt": "css" <-- set this to default to .scss +} +``` +Create an empty file `_variables.scss` in `src/`. + +In `styles.scss` add the following: + +``` +@import 'variables'; +@import '../node_modules/bootstrap/scss/bootstrap'; +``` + +## Checkout + +Open `src/app/app.module.ts` and add + +```typescript +import { BsDropdownModule } from 'ngx-bootstrap/dropdown'; +... + +@NgModule({ + ... + imports: [BsDropdownModule.forRoot(), ... ], + ... +}) +``` + +- open `src/app/app.component.html` and add +``` +
+ + +
+``` + +run the app in demo mode and ensure the dropdown button functions correctly. diff --git a/docs/getting-started/bootstrap4.md b/docs/getting-started/bootstrap4.md deleted file mode 100644 index abe680828e..0000000000 --- a/docs/getting-started/bootstrap4.md +++ /dev/null @@ -1,123 +0,0 @@ -## Using with Bootstrap 4 with angular-cli - -This extract from the [angular-cli include bootstrap story](https://github.com/angular/angular-cli/wiki/stories-include-bootstrap) demonstrates one way to use Bootstrap 4 together with ngx-bootstrap. - -> _Note_: Make sure that you let ngx-bootstrap know that Bootstrap v4 being used, as it assumes v3 by default. - -### Installing angular-cli - -_Important_: please check `angular-cli` version, it should be => "1.5.0" - -> _Note_: You can skip this part if you already have application generated by `ng-cli` and webpack. - -```bash -npm i -g @angular/cli -ng new my-app -cd my-app -ng serve -``` - -### Adding ngx-bootstrap and Bootstrap 4 - -- Install `ngx-bootstrap` and `Bootstrap 4` - - ```bash - npm install ngx-bootstrap bootstrap --save - ``` - -### Using with CSS - -#### Configuring Project - -Now that we have setup the project, we need to include the Bootstrap CSS support in it. - -- Open the file .angular-cli.json from the root of your project. - -- Under the property apps, the first item in that array is the default application. - -- `styles` property allows to apply external global styles to your application. - -- Specify the path to bootstrap.min.css - -It should look like the following when you are done: - -```CSS - "styles": [ - "../node_modules/bootstrap/dist/css/bootstrap.min.css", - "styles.css" - ], -``` - -> Note: When you make changes to .angular-cli.json you will need to restart `ng serve` to pick up configuration changes. - -### Using SASS - -#### Configuring project - -Ensure that the project is set up to use SCSS by default and that the main styles file is styles.scss - -The easiest way to do this is when creating a new project by: - -```bash -ng new my-app --style=scss -cd my-app -``` - -If the project has been already created then: - -- Rename `src/styles.css` to `src/styles.scss`; -- In `.angular-cli.json` make the following changes: - -```SCSS - "styles": [ - "styles.scss" <-- rename this from .css to .scss - ], -... - "defaults": { - "styleExt": "scss", <-- set this to default to .scss - "component": {} - } -``` - -- Create an empty file `_variables.scss` in `src/`; -- In `styles.scss` add the following: - -```SCSS - @import 'variables'; - @import '../node_modules/bootstrap/scss/bootstrap'; -``` - -### Testing - -- Open `src/app/app.module.ts` and add: - -```typescript -import { BsDropdownModule } from 'ngx-bootstrap/dropdown'; -... - -@NgModule({ - ... - imports: [BsDropdownModule.forRoot(), ... ], - ... -}) -``` - -- Open `src/app/app.component.html` and add: - -```html -
- - -
-``` - -- Run the app in demo mode and ensure the dropdown button functions properly.