From 68e2c28a8e74cee79ac32eca3972d4be57233342 Mon Sep 17 00:00:00 2001 From: Samet Alemdar Date: Tue, 7 Mar 2017 02:08:24 +0300 Subject: [PATCH] Update README.md --- README.md | 316 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 314 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2fd81b3a..521f078d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,314 @@ -# ngx-cookie -Implementation of Angular 1.x $cookies service to Angular 2 +# ngx-cookie [![Build Status](https://travis-ci.org/salemdar/ngx-cookie.svg?branch=master)](https://travis-ci.org/salemdar/ngx-cookie) [![npm version](https://img.shields.io/npm/v/ngx-cookie.svg)](https://www.npmjs.com/package/ngx-cookie) [![Downloads](http://img.shields.io/npm/dm/ngx-cookie.svg)](https://npmjs.org/package/ngx-cookie) + +> Implementation of Angular 1.x $cookies service to Angular. Successor of [angular2-cookie](https://github.com/salemdar/angular2-cookie) + +## Table of contents: +- [Get Started](#get-started) + - [Installation](#installation) + - [Usage](#usage) + - [AngularUniversal](#universal) + - [Examples](#examples) + - [angular-quickstart](#quickstart) + - [angular-seed](#seed) + - [angular-cli](#cli) +- [CookieService](#cookieservice) + - [get()](#get) + - [getObject()](#getobject) + - [getAll()](#getall) + - [put()](#put) + - [putObject()](#putobject) + - [remove()](#remove) + - [removeAll()](#removeall) +- [Options](#options) + +## Get Started + +### Installation + +You can install this package locally with npm. + +```bash +# To get the latest stable version and update package.json file: +npm install ngx-cookie --save +``` + +After installing the library, it should be included in the SystemJS configurations. + +```javascript +/** + * System configuration for Angular samples + * Adjust as necessary for your application needs. + * Taken from: https://github.com/angular/quickstart/blob/master/systemjs.config.js + */ +(function (global) { + System.config({ + paths: { + // paths serve as alias + 'npm:': 'node_modules/' + }, + // map tells the System loader where to look for things + map: { + // our app is within the app folder + app: 'app', + + // angular bundles + '@angular/core': 'npm:@angular/core/bundles/core.umd.js', + '@angular/common': 'npm:@angular/common/bundles/common.umd.js', + '@angular/compiler': 'npm:@angular/compiler/bundles/compiler.umd.js', + '@angular/platform-browser': 'npm:@angular/platform-browser/bundles/platform-browser.umd.js', + '@angular/platform-browser-dynamic': 'npm:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js', + '@angular/http': 'npm:@angular/http/bundles/http.umd.js', + '@angular/router': 'npm:@angular/router/bundles/router.umd.js', + '@angular/forms': 'npm:@angular/forms/bundles/forms.umd.js', + + // other libraries + 'rxjs': 'npm:rxjs', + 'angular2-in-memory-web-api': 'npm:angular2-in-memory-web-api', + 'ngx-cookie': 'npm:ngx-cookie' + }, + // packages tells the System loader how to load when no filename and/or no extension + packages: { + app: { + main: './main.js', + defaultExtension: 'js' + }, + rxjs: { + defaultExtension: 'js' + }, + 'angular2-in-memory-web-api': { + main: './index.js', + defaultExtension: 'js' + }, + 'ngx-cookie': { + main: './index.js', + defaultExtension: 'js' + } + } + }); +})(this); +``` + +### Usage + +**CookieService** class is an injectable service with angular `@Injectable()` decorator. Therefore, it needs to be registered in the providers array (encouraged way). +Then, it will be available in the constructor of the component class. + +```typescript +import { NgModule } from '@angular/core'; +import { BrowserModule } from '@angular/platform-browser'; + +import { CookieModule } from 'ngx-cookie'; + +import { AppComponent } from './app.component'; + +@NgModule({ + imports: [ BrowserModule, CookieModule.forRoot() ], + declarations: [ AppComponent ], + bootstrap: [ AppComponent ] +}) +export class AppModule { } +``` + +```typescript +import { Component } from '@angular/core'; +import { CookieService } from 'ngx-cookie'; + +@Component({ + selector: 'my-very-cool-app', + template: '

My Angular2 App with Cookies

' +}) + +export class AppComponent { + constructor(private _cookieService:CookieService){} + + getCookie(key: string){ + return this._cookieService.get(key); + } +} +``` + + +### Examples + +Here you can find some usage examples with popular boilerplate libraries. + +#### Angular2-quickstart + +A boilerplate provided by Angular team. +_(Link: [https://github.com/angular/quickstart](https://github.com/angular/quickstart))_ + +Just edit the `systemjs.config.js` file and add the `ngx-cookie` there. + +```typescript +/** + * System configuration for Angular 2 samples + * Adjust as necessary for your application needs. + */ +(function (global) { + System.config({ + paths: { + // paths serve as alias + 'npm:': 'node_modules/' + }, + // map tells the System loader where to look for things + map: { + // our app is within the app folder + app: 'app', + + // angular bundles + '@angular/core': 'npm:@angular/core/bundles/core.umd.js', + '@angular/common': 'npm:@angular/common/bundles/common.umd.js', + '@angular/compiler': 'npm:@angular/compiler/bundles/compiler.umd.js', + '@angular/platform-browser': 'npm:@angular/platform-browser/bundles/platform-browser.umd.js', + '@angular/platform-browser-dynamic': 'npm:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js', + '@angular/http': 'npm:@angular/http/bundles/http.umd.js', + '@angular/router': 'npm:@angular/router/bundles/router.umd.js', + '@angular/forms': 'npm:@angular/forms/bundles/forms.umd.js', + + // other libraries + 'rxjs': 'npm:rxjs', + 'angular2-in-memory-web-api': 'npm:angular2-in-memory-web-api', + 'ngx-cookie': 'npm:ngx-cookie/bundles/ngx-cookie.umd.js' + }, + // packages tells the System loader how to load when no filename and/or no extension + packages: { + app: { + main: './main.js', + defaultExtension: 'js' + }, + rxjs: { + defaultExtension: 'js' + }, + 'angular2-in-memory-web-api': { + main: './index.js', + defaultExtension: 'js' + } + } + }); +})(this); +``` + +#### Angular2-seed + +A popular seed project. +_(Link: [https://github.com/mgechev/angular2-seed](https://github.com/mgechev/angular2-seed))_ + +Add the following settings to the (constructor of) `ProjectConfig` class (path: `./tools/config/project.config.ts`). + +```typescript +let additionalPackages: ExtendPackages[] = [{ + name: 'ngx-cookie', + // Path to the package's bundle + path: 'node_modules/ngx-cookie/bundles/ngx-cookie.umd.js' +}]; + +this.addPackagesBundles(additionalPackages); +``` + +Do not forget to inject the `CookieModule` in the module `AppModule` and `SharedModule`. + +#### Angular-cli + +A CLI tool for Angular2. +_(Link: [https://github.com/angular/angular-cli](https://github.com/angular/angular-cli))_ + +Edit the `.angular-cli.json` and add `ngx-cookie` to the `scripts`. + +```javascript +// ... +"scripts": [ + "../node_modules/ngx-cookie/bundles/ngx-cookie.umd.js", + // ... +] +// ... +``` + + +## CookieService + +There are 7 methods available in the `CookieService` (6 standard methods from **Angular 1** and 1 extra `removeAll()` method for convenience) + +### get() +Returns the value of given cookie key. + +```typescript +/** + * @param {string} key Id to use for lookup. + * @returns {string} Raw cookie value. + */ +get(key: string): string; +``` + +### getObject() +Returns the deserialized value of given cookie key. + +```typescript +/** + * @param {string} key Id to use for lookup. + * @returns {Object} Deserialized cookie value. + */ +getObject(key: string): Object; +``` + +### getAll() +Returns a key value object with all the cookies. + +```typescript +/** + * @returns {Object} All cookies + */ +getAll(): any; +``` + +### put() +Sets a value for given cookie key. + +```typescript +/** + * @param {string} key Id for the `value`. + * @param {string} value Raw value to be stored. + * @param {CookieOptionsArgs} options (Optional) Options object. + */ +put(key: string, value: string, options?: CookieOptionsArgs): void; +``` + +### putObject() +Serializes and sets a value for given cookie key. + +```typescript +/** + * @param {string} key Id for the `value`. + * @param {Object} value Value to be stored. + * @param {CookieOptionsArgs} options (Optional) Options object. + */ +putObject(key: string, value: Object, options?: CookieOptionsArgs): void; +``` + +### remove() +Remove given cookie. + +```typescript +/** + * @param {string} key Id of the key-value pair to delete. + * @param {CookieOptionsArgs} options (Optional) Options object. + */ +remove(key: string, options?: CookieOptionsArgs): void; +``` + +### removeAll() +Remove all cookies. + +```typescript +/** + */ +removeAll(): void; +``` + +## Options + +Options object should be a type of `CookieOptionsArgs` interface. The object may have following properties: + +- **path** - {string} - The cookie will be available only for this path and its sub-paths. By default, this is the URL that appears in your `` tag. +- **domain** - {string} - The cookie will be available only for this domain and its sub-domains. For security reasons the user agent will not accept the cookie if the current domain is not a sub-domain of this domain or equal to it. +- **expires** - {string|Date} - String of the form "Wdy, DD Mon YYYY HH:MM:SS GMT" or a Date object indicating the exact date/time this cookie will expire. +- **secure** - {boolean} - If `true`, then the cookie will only be available through a secured connection.