From d3c7bacc0ac1469a7aae6f6c31f5b5b4e5b6e445 Mon Sep 17 00:00:00 2001 From: Will Abson Date: Wed, 1 Jun 2016 16:22:25 +0100 Subject: [PATCH] Add README info on component usage Refs #90 --- ng2-components/ng2-alfresco-search/README.md | 287 +++++++++++++++++- .../alfresco-search-control.component.ts | 2 +- 2 files changed, 279 insertions(+), 10 deletions(-) diff --git a/ng2-components/ng2-alfresco-search/README.md b/ng2-components/ng2-alfresco-search/README.md index 6f5b6ec368..0d4e5894f0 100644 --- a/ng2-components/ng2-alfresco-search/README.md +++ b/ng2-components/ng2-alfresco-search/README.md @@ -16,9 +16,276 @@ npm set registry http://devproducts.alfresco.me:4873 npm install --save ng2-alfresco-core ng2-alfresco-search ``` +Components included: + +- [Search control](#search-control) +- [Search results](#search-results) + +### Search control + +This component displays a search box on the page, which the user can use to enter a search query. It is decoupled from +the related [search results](#search-results) component which performs a query and displays results. + +#### Dependencies + +Make sure your `systemjs.config` has the following configuration: + +```javascript + System.config({ + defaultJSExtensions: true, + map: { + 'ng2-alfresco-core': 'node_modules/ng2-alfresco-core', + 'ng2-alfresco-upload': 'node_modules/ng2-alfresco-search', + 'rxjs': 'node_modules/rxjs', + 'angular2' : 'node_modules/angular2', + 'ng2-translate': 'node_modules/ng2-translate', + 'app': 'dist/src' + }, + packages: { + 'app': { + defaultExtension: 'js' + }, + 'ng2-alfresco-core': { + defaultExtension: 'js' + }, + 'ng2-alfresco-search': { + defaultExtension: 'js' + }, + 'rxjs': { + defaultExtension: 'js' + }, + 'angular2': { + defaultExtension: 'js' + } + } + }); +``` + +#### Style +The style of this component is based on Google Material Design, so if you want to visualize it correctly you have to add +the material-design-lite dependency to your project: + +```sh +npm install --save material-design-icons material-design-lite +``` + +Also make sure you include these dependencies in your .html page: + +```html + + + + +``` + +#### Basic usage + +```html + + +``` + +Example of an component that uses the search control. In this example the search term is simply logged to the console +but instead the component could emit an event to be consumed upstream, or it could trigger a change inside a search +results component embedded inside the same component. + +```ts +import { Component, OnInit } from 'angular2/core'; +import { bootstrap } from 'angular2/platform/browser'; +import { HTTP_PROVIDERS } from 'angular2/http'; + +import { + ALFRESCO_CORE_PROVIDERS, + AlfrescoSettingsService, + AlfrescoAuthenticationService, + AlfrescoPipeTranslate, + AlfrescoTranslationService +} from 'ng2-alfresco-core/dist/ng2-alfresco-core'; + +import { + ALFRESCO_SEARCH_PROVIDERS, + ALFRESCO_SEARCH_DIRECTIVES, + AlfrescoService +} from 'ng2-alfresco-search/dist/ng2-alfresco-search'; + +@Component({ + selector: 'alfresco-search-demo', + template: ` + + + `, + directives: [ALFRESCO_SEARCH_DIRECTIVES] +}) +class SearchDemo implements OnInit { + + public searchTerm: string = 'foo bar'; + + constructor() { + } + + searchTermChange(event) { + console.log('Search term changed', event); + this.searchTerm = event.value; + } +} + +bootstrap(SearchDemo, [ + HTTP_PROVIDERS, + ALFRESCO_CORE_PROVIDERS +]); +``` +#### Events + +**searchChange**: Emitted when the search term is changed and the form submitted, provided that the term is at least three characters in length
+ +#### Options + +**searchTerm**: {string} optional) default "". Search term to pre-populate the field with
+ +### Search results + +This component displays the results of a search to the user. + +#### Dependencies + +Make sure your `systemjs.config` has the following configuration: + +```javascript + System.config({ + defaultJSExtensions: true, + map: { + 'ng2-alfresco-core': 'node_modules/ng2-alfresco-core', + 'ng2-alfresco-upload': 'node_modules/ng2-alfresco-search', + 'rxjs': 'node_modules/rxjs', + 'angular2' : 'node_modules/angular2', + 'ng2-translate': 'node_modules/ng2-translate', + 'app': 'dist/src' + }, + packages: { + 'app': { + defaultExtension: 'js' + }, + 'ng2-alfresco-core': { + defaultExtension: 'js' + }, + 'ng2-alfresco-search': { + defaultExtension: 'js' + }, + 'rxjs': { + defaultExtension: 'js' + }, + 'angular2': { + defaultExtension: 'js' + } + } + }); +``` + +You must also add the following dependency to your index.html: + +```html + +``` + +#### Style +The style of this component is based on Google Material Design, so if you want to visualize it correctly you have to add +the material-design-lite dependency to your project: + +```sh +npm install --save material-design-icons material-design-lite +``` + +Also make sure you include these dependencies in your .html page: + +```html + + + + +``` + +#### Basic usage + +```html + +``` + +Example of an component that displays search results, using the Angular2 router to supply a 'q' parameter containing the +search term. If no ruter is present pon the page of if the router does not provide such a parameter then an empty +results page will be shown. + +```ts +import { Component } from 'angular2/core'; +import { bootstrap } from 'angular2/platform/browser'; +import { HTTP_PROVIDERS } from 'angular2/http'; + +import { ALFRESCO_CORE_PROVIDERS } from 'ng2-alfresco-core/dist/ng2-alfresco-core'; +import { ALFRESCO_SEARCH_DIRECTIVES } from 'ng2-alfresco-search/dist/ng2-alfresco-search'; + +@Component({ + selector: 'alfresco-search-demo', + template: ` + + `, + directives: [ALFRESCO_SEARCH_DIRECTIVES] +}) +class SearchDemo { + searchTerm: string = ''; + constructor() { + } +} + +bootstrap(SearchDemo, [ + HTTP_PROVIDERS, + ALFRESCO_CORE_PROVIDERS +]); +``` + +Example of an component that displays search results, taking the search term from a `@Input` property provided by the container. + +When the input is updated by the application, the search control will run a new search and display the results. + +```ts +import { Component, Input } from 'angular2/core'; +import { bootstrap } from 'angular2/platform/browser'; +import { HTTP_PROVIDERS } from 'angular2/http'; + +import { ALFRESCO_CORE_PROVIDERS } from 'ng2-alfresco-core/dist/ng2-alfresco-core'; +import { ALFRESCO_SEARCH_DIRECTIVES } from 'ng2-alfresco-search/dist/ng2-alfresco-search'; + +@Component({ + selector: 'alfresco-search-demo', + template: ` + + `, + directives: [ALFRESCO_SEARCH_DIRECTIVES] +}) +class SearchDemo { + @Input() + searchTerm: string = ''; + constructor() { + } +} + +bootstrap(SearchDemo, [ + HTTP_PROVIDERS, + ALFRESCO_CORE_PROVIDERS +]); +``` + +#### Events + +None + +#### Options + +**searchTerm**: {string} (optional) default "". Search term to use when executing the search. Updating this value will +run a new search and update the results.
+ ## Build from sources -Alternatively you can build component from sources with the following commands: +Alternatively you can build the component from source with the following commands: ```sh npm install @@ -37,14 +304,6 @@ npm test npm test-browser ``` -#### Basic usage - - -```html - -``` - - This task rebuilds all the code, runs tslint, license checks and other quality check tools before performing unit testing. @@ -53,3 +312,13 @@ before performing unit testing. ```sh npm run coverage ``` + +## Demo + +The `demo` folder contains a complete app with both components running on a single page and linked together: + +```sh +cd demo +npm install +npm start +``` \ No newline at end of file diff --git a/ng2-components/ng2-alfresco-search/src/components/alfresco-search-control.component.ts b/ng2-components/ng2-alfresco-search/src/components/alfresco-search-control.component.ts index 7904c7686b..509d5c09c8 100644 --- a/ng2-components/ng2-alfresco-search/src/components/alfresco-search-control.component.ts +++ b/ng2-components/ng2-alfresco-search/src/components/alfresco-search-control.component.ts @@ -33,7 +33,7 @@ declare var componentHandler: any; export class AlfrescoSearchControlComponent { @Input() - searchTerm = 'Default search'; + searchTerm = ''; @Output() searchChange = new EventEmitter();