This add-on integrates the angular-strap-select and the angular-ui-select components to provide fully featured drop downs to angular-schema-form.
It is drop-in compliant with angular-schema-forms existing selects, which makes using it a breeze, no adaptations are needed.
All settings are kept in the form, separating validation and UI-configuration.
Note about UI-select: The ui-select support is quite new and while many things work, it is still somewhat partial, so WRT the features below, they apply to angular-strap-select. For that reason, ui-select has a special section in the documentation.
There is a live example at http://demo.optimalbpm.se/angular-schema-form-dynamic-select/.
The example code is in the repository, it's made up of the index.html, app.js, test/testdata.json and test/testdata_mapped.json files.
To run it locally, simply clone the repository:
git clone https://github.com/OptimalBPM/angular-schema-form-dynamic-select.git
cd angular-schema-form-dynamic-select
bower update
..and open index.html in a browser or serve using your favorite IDE.
However, to make the entire example work properly, as it contains UI-select components, please install the ui-select dependencies as well.
(you will need to have bower installed, of course)
What are my options if I feel I need help?
The prerequisite for understanding the ASFDS documentation below is that you have a basic understanding of how to use Angular Schema Form.
So if you understand that, and still cannot understand the documentation of ASFDS, it is probably not your fault. Please create an issue in those cases.
If you have a question and cannot find an answer for it in the documentation below, please create an issue.
Questions and their answers have great value for the community.
Please create an issue. Be sure to provide ample information, remember that any help won't be better than your explanation.
Unless something is obviously wrong, you are likely to be asked to provide a plunkr-example, displaying the erroneous behaviour.
While this might feel troublesome, a tip is to always make a plunkr that have the same external requirements as your project.
It is great for troubleshooting those annoying problems where you don't know if the problem is at your end or the components'.
And you can then easily fork and provide as an example.
You will answers and resolutions way quicker, also, many other open source projects require it.
Good stuff! Please create an issue!
(features are more likely to be added the more users they seem to benefit)
The gitter page is good for when you want to talk, but perhaps doesn't feel that the discussion has to be indexed for posterity.
ASFDS is an add-on to the angular-schema-form. To use it (in production), follow these steps:
Easiest way is to install is with bower, this will also include dependencies:
$ bower install angular-schema-form-dynamic-select
If you want to use the develop branch:
$ bower install angular-schema-form-dynamic-select#develop
#develop is not recommended for production, but perhaps you want to use stuff from the next version in development.
You can also use npm for installation:
$ npm i angular-schema-form-dynamic-select
Usage is straightforward, simply include and reference:
<link href="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/blob/master/bower_components/bootstrap/dist/css/bootstrap.css" media="all" rel="stylesheet" />
<script type="text/javascript" src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular/angular.min.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular-sanitize/angular-sanitize.min.js"></script>
<script src='bower_components/angular-strap/dist/angular-strap.min.js'></script>
<script src='bower_components/angular-strap/dist/angular-strap.tpl.min.js'></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/tv4/tv4.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/objectpath/lib/ObjectPath.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular-schema-form/dist/schema-form.min.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular-schema-form/dist/bootstrap-decorator.min.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular-schema-form-dynamic-select/angular-schema-form-dynamic-select.js"></script>
Note: Make sure you load angular-schema-form-dynamic-select.js after loading angular schema form.
When you create your module, be sure to make it depend on mgcrea.ngStrap as well:
angular.module('yourModule', ['schemaForm', 'mgcrea.ngStrap']);
Note: Se the ui-select dependencies section for ui-select instructions
ASFDS is configured using form settings. There are no ASFDS-specific settings in the schema.
This is to keep the schemas clean from UI-specific settings and kept usable anywhere in the solution and/or organization.
The add-on contributes the following new form types, strapselect
, uiselect
, uiselectmulti
.
The strapselect implements angular-strap-selects and uiselect* implements angular-ui-select.
Built-in select-controls gets the bootstrap look but retain their functionality.
All settings reside in the form definition. See the app.js file for this example in use.
$scope.form = [
The drop down items are defined by and array of value/name objects residing in the form
{
"key": 'select',
"type": 'strapselect',
"titleMap": [
{"value": 'value1', "name": 'text1'},
{"value": 'value2', "name": 'text2'},
{"value": 'value3', "name": 'text3'}
]
},
Like the above, but allows multiple items to be selected.
{
"key": 'multiselect',
"type": 'strapselect',
"options": {
"multiple": "true"
}
"titleMap": [
{"value": 'value1', "name": 'text1'},
{"value": 'value2', "name": 'text2'},
{"value": 'value3', "name": 'long very very long label3'}
]
},
Callback must return an array of value/name objects (see static list above). The "options" structure is passed to it as a parameter.
{
"key": "selectDynamic",
"type": 'strapselect',
"options": {
"callback": $scope.callBackSD
}
},
For examples of how the different kinds of callbacks are implemented, please look at the relevant code in app.js,
Like strapselectdynamic above, but allowed multiple items to be selected.
{
"key": "multiselectDynamic",
"type": 'strapmultiselect',
"options": {
"multiple": "true"
"callback": $scope.callBackMSD
}
},
The asyncCallback must return a http-style promise and the data the promise provides must be a JSON array of value/name objects.
{
"key": "multiselectDynamicAsync",
"type": 'strapselect',
"options": {
"multiple": "true"
"asyncCallback": "callBackMSDAsync"
}
}
},
Note that in this example, the reference to the callback is a string, meaning a callback in the using controller scope. Also note, again, because this is a common misunderstanding, that asyncCallback should not return the array of items, but a http-promise, like the one $http.get()/$http.post() or jquery's deferred.promise. Returning the array would be a synchronous operation, see "callback" above.
Convenience function, makes a get request, no need for callback. Expects the server to return a JSON array of value/name objects.
{
"key": "multiselectDynamicHttpGet",
"type": 'strapselect',
"options": {
"multiple": "true"
"httpGet": {
"url" : "test/testdata.json"
}
}
},
Like the get variant above function, but makes a JSON POST request passing the "parameter" as JSON.
This example makes use of the optionsCallback property.
It is a callback that like the others, gets the options structure
as a parameter, but allows its content to be modified and returned for use in the call.
Here, the otherwise mandatory httpPost.url is not set in the options but in the callback.
See the stringOptionsCallback function in app.js for an example. The options-instance that is passed to the parameter is a copy of the instance in the form, so the form instance is not affected by any modifications by the callback.
{
"key": "multiselectDynamicHttpPost",
"type": 'strapselect',
"options": {
"multiple": "true"
"httpPost": {
"optionsCallback" : "stringOptionsCallback",
"parameter": { "myparam" : "Hello"}
}
}
},
The angular-schema-form titleMap naming standard is value/name, but that is sometimes difficult to get from a server,
it might not support it.
Therefore, a "map"-property is provided.
The property in valueProperty says in what property to look for the value, and nameProperty the name.
In this case:
{"nodeId" : 1, "nodeName": "Test", "nodeType": "99"}
which cannot be used, is converted into:
{"value" : 1, "name": "Test", "nodeId" : 1, nodeName: "Test", "nodeType": "99"}
which is the native format with the old options retained to not destroy auxiliary information. For example, a field like "nodeType" might be used for filtering(see Filters section, below). The options for that mapping look like this:
{
"key": "multiselectdynamic_http_get",
"type": "strapselect",
"options": {
"multiple": "true"
"httpGet": {
"url": "test/testdata_mapped.json"
},
"map" : {"valueProperty": "nodeId", nameProperty: "nodeName"}
}
},
The nameProperty can also be an array, in which case ASFDS looks for the first value. For example, in this case, one wants to first show the caption, and if that is not available, the name:
"map" : {"valueProperty": "nodeId", nameProperty: ["nodeCaption", "nodeName"]}
For more complicated mappings, and situations where the source data is in a completely different format, the callback and asyncCallback options can be used instead.
Filters, like conditions, handle visibility, but for each item in the options list.
It works by evaluating the filter expression for each row, if it evaluates to true, the option remains in the list. One could compare it with an SQL join.
The options are:
"model.select==item.category"
"model.select"
Example:
{
"key": 'multiselect',
"type": 'strapselect',
options: {
"multiple": "true"
"filterTriggers": ["model.select"],
"filter" : "model.select==item.category"
},
"titleMap": [
{"value": 'value1', "name": 'text1', "category": "value1"},
{"value": 'value2', "name": 'text2', "category": "value1"},
{"value": 'value3', "name": 'long very very long label3'}
]
},
Note on filterTrigger and why not having a watch on the entire expression:
One usable property that is set by ASFDS is the options.scope-attribute.
Its value is the scope of the controller, which provides far-reaching control over ASFDS behavior.
In the example, the multiselectDynamicAsync's onChange event is implemented so that another ASFDS controller is told to repopulate its select list items when the value is changed. This is valuable, for example, when there is too much data or for some other reason, filters are inappropriate.
If a there is a form item that only has type "string" defined, but has an enum value, then a single select will be shown for that value.
{
"key": 'select'
},
The schema declaration(the enum values will be both value and name for the options):
select: {
title: 'Single Select Static',
type: 'string',
enum: ["value1", "value2", "value3"],
description: 'Only single item is allowed. Based on schema enum and form default.(change here and observe how the select list below is filtered)'
},
These settings affects only strapselect and controls the number of items that are shown in the selected list of items. If that list is full, the number of list items + the test in inlineMaxLengthHtml is shown. If, for example, inlineMaxLength is set to 2 and the number of selected items is 4, the text shown will be:
4 items are too many items to show....
Example(the same as in the example file):
"key": 'multiselect_overflow',
"type": 'strapselect',
"placeholder": "Please select some items.",
"options": {
"multiple": "true",
"inlineMaxLength": "2",
"inlineMaxLengthHtml": " items are too many items to show...."
},
"titleMap": [
{"value": 'value1', "name": 'text1'},
{"value": 'value2', "name": 'text2'},
{"value": 'value3', "name": 'text3'},
{"value": 'value4', "name": 'text4'},
]
The placement option can be used to position a strapselect. Possible values for placement are top, bottom, left, right, auto or any combination (e.g. bottom-right). Further details can be found in the angularStrap select documentation.
Example (the same as in the example file):
"key": "select_placement",
"placeholder": "Please select from the right.",
"options": {
"placement": "right"
}
Not needed, of course, but is commonly used.
{
type: "submit",
style: "btn-info",
title: "OK"
}
And ending the form element array:
];
The form.titleMap property in a form holds the list items(also in the dynamic variants). The name titleMap is the same as the built-in angular-schema-form select.
These types are dynamic and fetches their data from different back ends.
Callbacks can be defined either by name("loadGroups"
) or absolute reference ($scope.loadGroups
).
The name is actually is an expression evaluated in the user scope that must return a function reference.
This means that it can be "getLoadFunctions('Groups')"
, as long as that returns a function reference.
But the main reason for supporting referring to functions both by name and reference is that forms
are often stored in a database and passed from the server to the client in pure JSON format,
and there, callback: $scope.loadGroups
is not allowed.
The results of all callbacks can be remapped using the "map" property described above. All callbacks(also optionsCallback) has two parameters:
The two kinds of callback mechanisms are:
TIP: in an asyncCallback, you need to intercept and change an async server response before passing it on to the add-on, use the transformResponse function.
For asyncCallback, httpGet and httpPost, there is an option, onPopulationError
.
If set to a callback function, and in case of a http error, the callback is called. Its parameters are: the form of the field(where they key and options are), the data and the status.
See app.js for an example of its usage. Try and rename test/testdata.js and you'll see it being called.
This is done by either using the JSON-schema enum-property, or by manually setting form.titleMap.
The support for angular-ui-select was added in the 0.9.0-version, and is currently partial, but getting there.
The currently supported UI-select specific/native options are:
UI-select is not installed by default in ASFDS, even though it is featured in the demo and example, here is how to make it work:
Its dependencies aren't included in the package.json, and will hence have to be installed manually, here is a script:
$ bower install angular-ui-select angular-underscore underscore angular-ui-utils angular-translate angular-ui-select angular-ui-utils angular-sanitize
Include all relevant files:
<link href="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/blob/master/bower_components/angular-ui-select/dist/select.css" rel="stylesheet" />
<script src="https://code.jquery.com/jquery-2.1.4.js"></script>
<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/underscore/underscore-min.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular-underscore/angular-underscore.js"></script>
<script src="https://github.com/OptimalBPM/angular-schema-form-dynamic-select/raw/master/bower_components/angular-ui-utils/ui-utils.js"></script>
<script src='bower_components/angular-ui-select/dist/select.js'></script>
UI-select have several additional dependencies that need to be added to your module configuration:
angular.module('yourModule', ['schemaForm', 'mgcrea.ngStrap', 'mgcrea.ngStrap.modal', 'pascalprecht.translate', 'ui.select', 'ui.highlight','mgcrea.ngStrap.select']);
It is used as strapselect, but by including the form types uiselect and uiselectmultiple instead.
{
"key": 'uiselectmultiple',
"type": 'uiselectmultiple',
"titleMap": [
{ value: 'one', name: 'option one'},
{ value: 'two', name: 'option two'},
{ value: 'three', name: 'option three'}
]
},
It supports dynamically fetching items from a backend using callbacks and http-methods, but works a little bit different from AngularStrap internally, so filters, for example, aren't implemented yet.
See the example app in the source for more details on how to use it.
Building and minifying is done using gulp
To install gulp, you need npm to be installer, however, we want a local bower install:
sudo npm install bower
node_modules/bower/bin/bower install
And then install the rest of the depencies
sudo npm install
The instructions are for Linux, to install under windows, the same commands adjusted for windows should work
In the project root folder, run:
$ gulp default
Pull requests are always very welcome. Try to make one for each thing you add, don't do like this author(me) did.
Remember that the next version is in the develop branch, so if you want to add new features, do that there.
If you want to fix a bug, do that against the master branch and it will be merged into the develop branch later.
Unit testing is done using Karma and Jasmine. The main configuration file for running tests is karma.conf.js, and test/tests.js holds the test code. First, make sure the relevant development dependencies are installed:
$ npm update
To run the tests:
$ node_modules/karma/bin/karma start karma.conf.js
Important: Over the early minor versions, there has been considerable changes:
Note: no further API changes are planned.
This component was originally created by chengz.
stevehu then added functionality to his project to connect to his light framework.
This inspired nicklasb to merge stevehu:s code and rewrite the plugin in order to:
The rest is extremely recent history(i.e. > 0.3.0).