From d910496ddc910e8e9b15290780505ea3fb45cbd8 Mon Sep 17 00:00:00 2001 From: Scott Hatcher Date: Tue, 14 Jul 2015 09:28:38 -0700 Subject: [PATCH] Extended definitions with info from formlyApiCheck. --- angular-formly/angular-formly-test.ts | 67 ++-- angular-formly/angular-formly.d.ts | 439 ++++++++++++++------------ 2 files changed, 286 insertions(+), 220 deletions(-) diff --git a/angular-formly/angular-formly-test.ts b/angular-formly/angular-formly-test.ts index 4d40538234..6038402080 100644 --- a/angular-formly/angular-formly-test.ts +++ b/angular-formly/angular-formly-test.ts @@ -2,49 +2,76 @@ var app = angular.module('app', ['formly']); +interface IScope extends ng.IScope { + to: { label: string; } +} + class AppController { fields: AngularFormly.IFieldConfigurationObject[]; constructor($scope: ng.IScope) { var vm = this; vm.fields = [ { - field: 'label', + key: 'email', type: 'input', templateOptions: { - maxlength: 8, - minlength: 3 + label: 'Email', + required: true, + type: 'email', + maxlength: 10, + minlength: 6, + placeholder: 'example@example.com' } }, { - template: '
' - }, - { - field: 'project', + key: 'ip', type: 'input', - defaultValue: 'Project 1', + validators: { + ipAddress: { + expression: function(viewValue, modelValue) { + var value = modelValue || viewValue; + return /(\d{1,3}\.){3}\d{1,3}/.test(value); + }, + message: '$viewValue + " is not a valid IP Address"' + } + }, templateOptions: { - placeholder: 'Enter a project name...' + label: 'IP Address', + required: true, + type: 'text', + placeholder: '127.0.0.1', + }, + validation: { + messages: { + required: function($viewValue: any, $modelValue: any, scope: IScope) { + return scope.to.label + ' is required' + } + } } }, { - template: () => 'hello' - }, - { + key: 'mac', type: 'input', - key: 'zip', templateOptions: { - type: 'number', - label: 'Zip', - max: 99999, - min: 0, - pattern: '\\d{5}' + label: 'MAC Address', + required: true, + placeholder: '49-8A-BD-4E-00-1D', + pattern: '([0-9A-F]{2}[:-]){5}([0-9A-F]{2})' } }, { type: 'checkbox', - key: 'happyUser', + key: 'checked', templateOptions: { - label: 'Are you happy?' + label: 'Check this' + } + }, + { + key: 'checked2', + type: 'checkbox', + wrapper: null, + templateOptions: { + label: 'no wrapper here...' } } ] diff --git a/angular-formly/angular-formly.d.ts b/angular-formly/angular-formly.d.ts index 807171d075..b34cb1406c 100644 --- a/angular-formly/angular-formly.d.ts +++ b/angular-formly/angular-formly.d.ts @@ -12,11 +12,46 @@ declare module 'AngularFormly' { declare module AngularFormly { + interface IFieldGroup { + data?: Object; + className?: string; + elementAttributes?: { [key: string]: string }; + fieldGroup: IFieldConfigurationObject[]; + form?: Object; + hide?: boolean; + hideExpression?: string | IExpresssionFunction; + key?: string | number; + model?: string | Object; + options?: IFormOptionsAPI + } + + + interface IFormOptionsAPI { + data?: Object; + fieldTransform?: Function; + formState?: Object; + removeChromeAutoComplete?: boolean; + resetModel?: Function; + templateManipulators?: ITemplateManipulators; + updateInitialValue?: Function; + wrapper?: string | string[]; + } + + /** * see http://docs.angular-formly.com/docs/formly-expressions#expressionproperties-validators--messages */ interface IExpresssionFunction { - ($viewValue: any, $modelValue: any, scope: ng.IScope): any; + ($viewValue: any, $modelValue: any, scope: Object): any; + } + + + interface IModelOptions { + updateOn?: string; + debounce?: number; + allowInvalid?: boolean; + getterSetter?: string; + timezone?: string; } @@ -26,19 +61,24 @@ declare module AngularFormly { * * see http://docs.angular-formly.com/docs/ngmodelattrs */ - interface INGModelAttrs { - [key: string]: { - attribute?: string; - expresssion?: string; - value?: string; - } - } + // interface INGModelAttrs { + // [key: string]: { + // attribute?: string; + // expresssion?: string; + // value?: string; + // } + // } interface ITemplateManipulator { (template: string | HTMLElement, options: Object, scope: ng.IScope): string | HTMLElement; } + interface ITemplateManipulators { + preWrapper?: ITemplateManipulator[]; + postWrapper?: ITemplateManipulator[]; + } + /** * see http://docs.angular-formly.com/docs/ngmodelattrstemplatemanipulator @@ -46,11 +86,11 @@ declare module AngularFormly { interface ITemplateOptions { // both attribute or regular attribute - disabled?: boolean | string; - maxlength?: number | string; - minlength?: number | string; + disabled?: boolean; + maxlength?: number; + minlength?: number; pattern?: string; - required?: boolean | string; + required?: boolean; //attribute only max?: number; @@ -68,6 +108,7 @@ declare module AngularFormly { onKeypress?: string; onKeyup?: string; + label?: string; [key: string]: any; } @@ -77,7 +118,8 @@ declare module AngularFormly { * see http://docs.angular-formly.com/docs/field-configuration-object#validators-object */ interface IValidator { - expression?: string | { (viewValue: any, modelValue: any): boolean }; + expression: string | IExpresssionFunction; + message?: string | IExpresssionFunction; } @@ -91,8 +133,8 @@ declare module AngularFormly { */ interface IWatcher { deep?: boolean; //Defaults to false - expression?: string | { (field: string, scope: ng.IScope): boolean }; - listener: (field: string, newValue: any, oldValue: any, scope: ng.IScope, stopWatching: Function) => void; + expression?: string | { (field: string, scope: Object): boolean }; + listener: (field: string, newValue: any, oldValue: any, scope: Object, stopWatching: Function) => void; type?: string; //Defaults to $watch but can be set to $watchCollection or $watchGroup } @@ -100,45 +142,22 @@ declare module AngularFormly { // see http://docs.angular-formly.com/docs/field-configuration-object interface IFieldConfigurationObject { - /** - * The type of field to be rendered. This is the recommended method - * for defining fields. Types must be pre-defined using formlyConfig. + * This is a great way to add custom behavior to a specific field. It is injectable with the $scope of the + * field, and anything else you have in your injector. * - * see http://docs.angular-formly.com/docs/field-configuration-object#type-string + * see http://docs.angular-formly.com/docs/field-configuration-object#controller-controller-name-as-string--controller-f */ - type?: string; + controller?: string | Function; /** - * Can be set instead of type or templateUrl to use a custom html - * template form field. Recommended to be used with one-liners mostly - * (like a directive), or if you're using webpack with the ability to require templates :-) + * This is reserved for the developer. You have our guarantee to be able to use this and not worry about + * future versions of formly overriding your usage and preventing you from upgrading :-) * - * If a function is passed, it is invoked with the field configuration object and can return - * either a string for the template or a promise that resolves to a string. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#template-string--function + * see http://docs.angular-formly.com/docs/field-configuration-object#data-object */ - template?: string | { (fieldConfiguration: IFieldConfigurationObject): string | ng.IPromise }; - - - /** - * Can be set instead of type or template to use a custom html template form field. Works - * just like a directive templateUrl and uses the $templateCache - * - * see http://docs.angular-formly.com/docs/field-configuration-object#templateurl-string--function - */ - templateUrl?: string | { (fieldConfiguration: IFieldConfigurationObject): string | ng.IPromise }; - - - /** - * Can be set instead of type or template to use a custom html template form field. Works - * just like a directive templateUrl and uses the $templateCache - * - * see http://docs.angular-formly.com/docs/field-configuration-object#key-string - */ - key?: string; + data?: Object; /** @@ -150,6 +169,30 @@ declare module AngularFormly { defaultValue?: any; + /** + * You can specify your own class that will be applied to the formly-field directive (or ng-form of + * a fieldGroup). + * + * see http://docs.angular-formly.com/docs/field-configuration-object#classname-string + */ + className?: string; + + + elementAttributes?: string; + + + /** + * An object where the key is a property to be set on the main field config and the value is an + * expression used to assign that property. The value is a formly expressions. The returned value is + * wrapped in $q.when so you can return a promise from your function :-) + * + * see http://docs.angular-formly.com/docs/field-configuration-object#expressionproperties-object + */ + expressionProperties?: { + [key: string]: string | IExpresssionFunction | IValidator; + } + + /** * Uses ng-if. Whether to hide the field. Defaults to false. If you wish this to be conditional, use * hideExpression. See below. @@ -169,6 +212,42 @@ declare module AngularFormly { hideExpression?: string | IExpresssionFunction; + /** + * This allows you to specify the id of your field (which will be used for its name as well unless + * a name is provided). Note, you can also override the id generation code using the formlyConfig + * extra called getFieldId. + * + * AVOID THIS + * If you don't have to do this, don't. Specifying IDs makes it harder to re-use things and it's + * just extra work. Part of the beauty that angular-formly provides is the fact that you don't need + * to concern yourself with making sure that this is unique. + * + * see http://docs.angular-formly.com/docs/field-configuration-object#id-string + */ + id?: string; + + + initialValue?: any; + + + /** + * Can be set instead of type or template to use a custom html template form field. Works + * just like a directive templateUrl and uses the $templateCache + * + * see http://docs.angular-formly.com/docs/field-configuration-object#key-string + */ + key?: string | number; + + + /** + * This allows you to specify a link function. It is invoked after your template has finished compiling. + * You are passed the normal arguments for a normal link function. + * + * see http://docs.angular-formly.com/docs/field-configuration-object#link-link-function + */ + link?: ng.IDirectiveLinkFn; + + /** * By default, the model passed to the formly-field directive is the same as the model passed to the * formly-form. However, if the field has a model specified, then it is used for that field (and that @@ -184,39 +263,14 @@ declare module AngularFormly { /** - * An object where the key is a property to be set on the main field config and the value is an - * expression used to assign that property. The value is a formly expressions. The returned value is - * wrapped in $q.when so you can return a promise from your function :-) + * Allows you to take advantage of ng-model-options directive. Formly's built-in templateManipulator (see + * below) will add this attribute to your ng-model element automatically if this property exists. Note, + * if you use the getter/setter option, formly's templateManipulator will change the value of ng-model + * to options.value which is a getterSetter that formly adds to field options. * - * see http://docs.angular-formly.com/docs/field-configuration-object#expressionproperties-object + * see http://docs.angular-formly.com/docs/field-configuration-object#modeloptions */ - expressionProperties?: { - [key: string]: string | IExpresssionFunction; - } - - - /** - * You can specify your own class that will be applied to the formly-field directive (or ng-form of - * a fieldGroup). - * - * see http://docs.angular-formly.com/docs/field-configuration-object#classname-string - */ - className?: string; - - - /** - * This allows you to specify the id of your field (which will be used for its name as well unless - * a name is provided). Note, you can also override the id generation code using the formlyConfig - * extra called getFieldId. - * - * AVOID THIS - * If you don't have to do this, don't. Specifying IDs makes it harder to re-use things and it's - * just extra work. Part of the beauty that angular-formly provides is the fact that you don't need - * to concern yourself with making sure that this is unique. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#id-string - */ - id?: string; + modelOptions?: IModelOptions; /** @@ -232,48 +286,6 @@ declare module AngularFormly { name?: string; - /** - * This is reserved for the developer. You have our guarantee to be able to use this and not worry about - * future versions of formly overriding your usage and preventing you from upgrading :-) - * - * see http://docs.angular-formly.com/docs/field-configuration-object#data-object - */ - data?: any; - - - /** - * This is reserved for the templates. Any template-specific options go in here. Look at your specific - * template implementation to know the options required for this. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#templateoptions-object - */ - templateOptions?: ITemplateOptions; - - - /** - * Allows you to specify custom template manipulators for this specific field. (use defaultOptions in a - * type configuration if you want it to apply to all fields of a certain type). - * - * see http://docs.angular-formly.com/docs/field-configuration-object#templatemanipulator-object-of-arrays-of-functions - */ - templateManipulator?: { - preWrapper: ITemplateManipulator[]; - postWrapper: ITemplateManipulator[]; - } - - - /** - * This makes reference to setWrapper in formlyConfig. It is expected to be the name of the wrapper. If - * given an array, the formly field template will be wrapped by the first wrapper, then the second, then - * the third, etc. You can also specify these as part of a type (which is the recommended approach). - * Specifying this property will override the wrappers for the type for this field. - * - * http://docs.angular-formly.com/docs/field-configuration-object#wrapper-string--array-of-strings - */ - wrapper?: string | string[]; - - - //TODO:Scott Figure out what this really does. /** * This is used by ngModelAttrsTemplateManipulator to automatically add attributes to the ng-model element * of field templates. You will likely not use this often. This object is a little complex, but extremely @@ -281,47 +293,12 @@ declare module AngularFormly { * * see http://docs.angular-formly.com/docs/field-configuration-object#ngmodelattrs-object */ - ngModelAttrs?: any; - - - /** - * This is a great way to add custom behavior to a specific field. It is injectable with the $scope of the - * field, and anything else you have in your injector. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#controller-controller-name-as-string--controller-f - */ - controller?: string | { Function: void }; - - - /** - * This allows you to specify a link function. It is invoked after your template has finished compiling. - * You are passed the normal arguments for a normal link function. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#link-link-function - */ - link?: ng.IDirectiveLinkFn; - - - /** - * Allows you to specify extra types to get options from. Duplicate options are overridden in later priority - * (index 1 will override index 0 properties). Also, these are applied after the type's defaultOptions and - * hence will override any duplicates of those properties as well. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#optionstypes-string--array-of-strings - */ - optionsTypes?: string | string[]; - - - //TODO:Scott Still need to define - /** - * Allows you to take advantage of ng-model-options directive. Formly's built-in templateManipulator (see - * below) will add this attribute to your ng-model element automatically if this property exists. Note, - * if you use the getter/setter option, formly's templateManipulator will change the value of ng-model - * to options.value which is a getterSetter that formly adds to field options. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#modeloptions - */ - modelOptions?: any; + ngModelAttrs?: { + attribute?: any; + bound?: any; + expression?: any; + value?: any; + }; /** @@ -335,29 +312,62 @@ declare module AngularFormly { /** - * An object which has at least two properties called expression and listener. The watch.expression is added - * to the formly-form directive's scope (to allow it to run even when hide is true). You can specify a type - * ($watchCollection or $watchGroup) via the watcher.type property (defaults to $watch) and whether you want - * it to be a deep watch via the watcher.deep property (defaults to false). + * Allows you to specify extra types to get options from. Duplicate options are overridden in later priority + * (index 1 will override index 0 properties). Also, these are applied after the type's defaultOptions and + * hence will override any duplicates of those properties as well. * - * see http://docs.angular-formly.com/docs/field-configuration-object#watcher-objectarray-of-watches + * see http://docs.angular-formly.com/docs/field-configuration-object#optionstypes-string--array-of-strings */ - watcher?: IWatcher | IWatcher[]; + optionsTypes?: string | string[]; - //TODO:Scott Look at defining validators as an Object to see if additional interface needs to be created /** - * An object where the keys are the name of the validator and the values are Formly Expressions; + * Can be set instead of type or templateUrl to use a custom html + * template form field. Recommended to be used with one-liners mostly + * (like a directive), or if you're using webpack with the ability to require templates :-) * - * Async Validation - * All function validators can return true/false/Promise. A validator passes if it returns true or a promise - * that is resolved. A validator fails if it returns false or a promise that is rejected. + * If a function is passed, it is invoked with the field configuration object and can return + * either a string for the template or a promise that resolves to a string. * - * see http://docs.angular-formly.com/docs/field-configuration-object#validators-object + * see http://docs.angular-formly.com/docs/field-configuration-object#template-string--function */ - validators?: { - [key: string]: IValidator | string; - } + template?: string | { (fieldConfiguration: IFieldConfigurationObject): string | ng.IPromise }; + + + /** + * Allows you to specify custom template manipulators for this specific field. (use defaultOptions in a + * type configuration if you want it to apply to all fields of a certain type). + * + * see http://docs.angular-formly.com/docs/field-configuration-object#templatemanipulator-object-of-arrays-of-functions + */ + templateManipulators?: ITemplateManipulators; + + + /** + * This is reserved for the templates. Any template-specific options go in here. Look at your specific + * template implementation to know the options required for this. + * + * see http://docs.angular-formly.com/docs/field-configuration-object#templateoptions-object + */ + templateOptions?: ITemplateOptions; + + + /** + * Can be set instead of type or template to use a custom html template form field. Works + * just like a directive templateUrl and uses the $templateCache + * + * see http://docs.angular-formly.com/docs/field-configuration-object#templateurl-string--function + */ + templateUrl?: string | { (fieldConfiguration: IFieldConfigurationObject): string | ng.IPromise }; + + + /** + * The type of field to be rendered. This is the recommended method + * for defining fields. Types must be pre-defined using formlyConfig. + * + * see http://docs.angular-formly.com/docs/field-configuration-object#type-string + */ + type?: string; /** @@ -365,13 +375,21 @@ declare module AngularFormly { */ validation?: { + /** + * This is set by angular-formly. This is a boolean indicating whether an error message should be shown. Because + * you generally only want to show error messages when the user has interacted with a specific field, this value + * is set to true based on this rule: field invalid && (field touched || validation.show) (with slight difference + * for pre-angular 1.3 because it doesn't have touched support). + */ + errorExistsAndShouldBeVisible?: boolean; + /** * A map of Formly Expressions mapped to message names. This is really useful when you're using ng-messages * like in this example. */ messages?: { - [key: string]: IExpresssionFunction; + [key: string]: IExpresssionFunction | string; } @@ -382,17 +400,23 @@ declare module AngularFormly { */ show?: boolean; - - /** - * This is set by angular-formly. This is a boolean indicating whether an error message should be shown. Because - * you generally only want to show error messages when the user has interacted with a specific field, this value - * is set to true based on this rule: field invalid && (field touched || validation.show) (with slight difference - * for pre-angular 1.3 because it doesn't have touched support). - */ - errorExistsAndShouldBeVisible?: boolean; - } + + /** + * An object where the keys are the name of the validator and the values are Formly Expressions; + * + * Async Validation + * All function validators can return true/false/Promise. A validator passes if it returns true or a promise + * that is resolved. A validator fails if it returns false or a promise that is rejected. + * + * see http://docs.angular-formly.com/docs/field-configuration-object#validators-object + */ + validators?: { + [key: string]: string | IExpresssionFunction | IValidator; + } + + /** * This is a getter/setter function for the value that your field is representing. Useful when using getterSetter: true * in the modelOptions (in fact, if you don't disable the ngModelAttrsTemplateManipulator that comes built-in with formly, @@ -404,6 +428,28 @@ declare module AngularFormly { value?(val: any): void; //Setter + /** + * An object which has at least two properties called expression and listener. The watch.expression is added + * to the formly-form directive's scope (to allow it to run even when hide is true). You can specify a type + * ($watchCollection or $watchGroup) via the watcher.type property (defaults to $watch) and whether you want + * it to be a deep watch via the watcher.deep property (defaults to false). + * + * see http://docs.angular-formly.com/docs/field-configuration-object#watcher-objectarray-of-watches + */ + watcher?: IWatcher | IWatcher[]; + + + /** + * This makes reference to setWrapper in formlyConfig. It is expected to be the name of the wrapper. If + * given an array, the formly field template will be wrapped by the first wrapper, then the second, then + * the third, etc. You can also specify these as part of a type (which is the recommended approach). + * Specifying this property will override the wrappers for the type for this field. + * + * http://docs.angular-formly.com/docs/field-configuration-object#wrapper-string--array-of-strings + */ + wrapper?: string | string[]; + + //ALL PROPERTIES BELOW ARE ADDED (So you should not be setting them yourself.) @@ -412,7 +458,7 @@ declare module AngularFormly { * * see http://docs.angular-formly.com/docs/field-configuration-object#formcontrol-ngmodelcontroller */ - formControl?: ng.IFormController; + formControl?: ng.IFormController | ng.IFormController[]; /** @@ -424,15 +470,6 @@ declare module AngularFormly { resetModel?: () => void; - /** - * Will reset the field's initialValue to the current state of the model. Useful if you load the model asynchronously. - * Invoke this when the model gets set. This is used by the formly-form's options.updateInitialValue function. - * - * see http://docs.angular-formly.com/docs/field-configuration-object#updateinitialvalue-function - */ - updateInitialValue?: () => void; - - /** * It is not likely that you'll ever want to invoke this function. It simply runs the expressionProperties expressions. * It is used internally and you shouldn't have to use it, but you can if you want to, and any breaking changes to the @@ -443,12 +480,14 @@ declare module AngularFormly { runExpressions?: () => void; - - ////////////////// BOOTSTRAP SPECIFIC /////////////////////// - fieldGroup?: IFieldConfigurationObject[]; + /** + * Will reset the field's initialValue to the current state of the model. Useful if you load the model asynchronously. + * Invoke this when the model gets set. This is used by the formly-form's options.updateInitialValue function. + * + * see http://docs.angular-formly.com/docs/field-configuration-object#updateinitialvalue-function + */ + updateInitialValue?: () => void; } - - } \ No newline at end of file