public/assets/plugins/angular-elastic-builder-back/README.md

   1 # Angular Elasticsearch Query Builder
   2
   3 [![NPM version][npm-image]][npm-url]
   4 ![Bower version][bower-image]
   5 [![Downloads][downloads-image]][downloads-url]
   6 [![Tips][gratipay-image]][gratipay-url]
   7
   8 This is an Angular.js directive for building an [Elasticsearch](https://www.elastic.co/) query.
   9 You just give it the fields and can generate a query for it. Its layout is defined using [Bootstrap](http://getbootstrap.com/) classes, but you may also choose to just style it yourself.
  10
  11 It's still pretty early on, as it doesn't support a whole lot of use-cases, but we need to make it awesome. Contributions accepted.
  12
  13 ## Try it Out
  14 [View an example here](http://dncrews.com/angular-elastic-builder/examples/)
  15
  16 ## Usage
  17
  18 ### Dependency
  19 Notice: this plugin requires the [Angular Recursion](https://github.com/marklagendijk/angular-recursion) module.
  20
  21 ### Installation
  22 First you'll need to download the [dist](https://github.com/dncrews/angular-elastic-builder/tree/master/dist) files and include this JS file to your app (don't forget to substitute `x.x.x` with the current version number), along with the RecursionHelper, if you're not already using it.
  23 ```html
  24 <script type="text/javascript" src="/angular-recursion.min.js"></script>
  25 <script type="text/javascript" src="/angular-elastic-builder.min.js"></script>
  26 ```
  27
  28 Then make sure that it's included in your app's dependencies during module creation.
  29
  30 ```js
  31 angularmodule('appName', [ 'angular-elastic-builder' ]);
  32 ```
  33
  34 Then you can use it in your app
  35 ```js
  36 /* Controller code */
  37
  38 /**
  39  * The elasticBuilderData object will be modified in place so that you can use
  40  * your own $watch, and/or your own saving mechanism
  41  */
  42 $scope.elasticBuilderData = {};
  43 $scope.elasticBuilderData.query = [];
  44
  45 /**
  46  * This object is the lookup for what fields
  47  * are available in your database, as well as definitions of what kind
  48  * of data they are
  49  */
  50 $scope.elasticBuilderData.fields = {
  51   'some.number.field': { type: 'number' },
  52   'some.term.field': { type: 'term' },
  53   'some.boolean.field': { type: 'term', subType: 'boolean' },
  54   'multi.selector': { type: 'multi', choices: [ 'AZ', 'CA', 'CT' ]}
  55 };
  56 ```
  57
  58 ```html
  59 <div data-elastic-builder="elasticBuilderData"></div>
  60 ```
  61
  62 The above elasticFields would allow you create the following form:
  63 ![Screenshot][screenshot-image]
  64
  65 Which represents the following Elasticsearch Query:
  66 ```json
  67 [
  68   {
  69     "terms": {
  70       "multi.selector": [
  71         "AZ",
  72         "CT"
  73       ]
  74     }
  75   },
  76   {
  77     "term": {
  78       "some.boolean.field": "0"
  79     }
  80   },
  81   {
  82     "not": {
  83       "filter": {
  84         "term": {
  85           "some.term.field": "Hello World"
  86         }
  87       }
  88     }
  89   },
  90   {
  91     "and": [
  92       {
  93         "range": {
  94           "some.number.field": {
  95             "gte": 0
  96           }
  97         }
  98       },
  99       {
 100         "range": {
 101           "some.number.field": {
 102             "lt": 100
 103           }
 104         }
 105       }
 106     ]
 107   }
 108 ]
 109 ```
 110
 111
 112 ### Field Options
 113   - `type`: This determines how the fields are displayed in the form.
 114     - Currently supported:
 115       - `'number'`: in addition to Generic Options, gets "&gt;", "&ge;", "&lt;", "&le;", "="
 116       - `'term'`: in addition to Generic Options, gets "Equals" and "! Equals"
 117       - `'boolean'`: Does not get Generic Options. Gets `true` and `false`
 118         - These are actually "equals 0" and "equals 1" for the database query
 119
 120 Generic Options
 121   - In addition to any specific options for fields, all fields also get a "Exists" and "! Exists" option
 122
 123
 124 ## External Changes && Initial State
 125 If you want to pass in an initial state (or if you make changes to the query externally), you'll need to
 126 set the configuration flag `needsUpdate` to `true`. Any time this flag changes to `true`, this directive
 127 will overwrite the current state and data with whatever is now defined in your configuration object.
 128
 129
 130 ## Local Development
 131 To work on this module locally, you will need to clone it and run `gulp watch`. This will ensure that your changes get compiled properly. You will also need to make sure you run `gulp` to build the "dist" files before commit.
 132
 133
 134 [npm-image]: https://img.shields.io/npm/v/angular-elastic-builder.svg
 135 [npm-url]: https://www.npmjs.org/package/angular-elastic-builder
 136 [bower-image]: https://img.shields.io/bower/v/angular-elastic-builder.svg
 137 [downloads-image]: https://img.shields.io/npm/dm/angular-elastic-builder.svg
 138 [downloads-url]: https://www.npmjs.org/package/angular-elastic-builder
 139 [gratipay-image]: https://img.shields.io/gratipay/dncrews.svg
 140 [gratipay-url]: https://www.gratipay.com/dncrews/
 141 [screenshot-image]: https://raw.githubusercontent.com/dncrews/angular-elastic-builder/master/screenshot.png