forms-angular 0.12.0-beta.19 → 0.12.0-beta.190

package/dist/client/index.d.ts

@@ -1,15 +1,19 @@
 declare module fng {
-  var formsAngular: angular.IModule;
+  export interface IFng extends angular.IModule {
+    beforeProcess? : (scope: IFormScope, cb: (err?: Error) => void) => void;
+    title?: {prefix?: string, suffix?: string}
+  }
+  var formsAngular: IFng;
 
   /*
   Type definitions for types that are used on both the client and the server
    */
+  type formStyle = 'inline' | 'vertical' | 'horizontal' | 'horizontalCompact' | 'stacked';
 
-  export interface IFngLookupReference {
-    type: 'lookup';
-    collection: string
+  export interface IBaseArrayLookupReference {
+    property: string;
+    value: string;
   }
-
   /*
   IInternalLookupreference makes it possible to look up from a list (of key / value pairs) in the current record.  For example
 
@@ -20,13 +24,11 @@ declare module fng {
   var ESchema = new Schema({
     warehouse_name: {type: String, list: {}},
     shelves: {type: [ShelfSchema]},
-    favouriteShelf: {type: Schema.Types.ObjectId, ref: {type: 'internal', property: 'shelves', value:'location'};
+    favouriteShelf: {type: Schema.Types.ObjectId, internalRef: {property: 'shelves', value:'location'};
   });
    */
-  export interface IFngInternalLookupReference {
-    type: 'internal';
-    property: string;
-    value: string;
+  export interface IFngInternalLookupReference extends IBaseArrayLookupReference {
+    noConvert? : boolean;    // can be used by a tricksy hack to get around nesting limitations
   }
 
   /*
@@ -36,18 +38,15 @@ declare module fng {
   const LSchemaDef : IFngSchemaDefinition = {
     descriptin: {type: String, required: true, list: {}},
     warehouse: {type: Schema.Types.ObjectId, ref:'k_referencing_self_collection', form: {directive: 'fng-ui-select', fngUiSelect: {fngAjax: true}}},
-    shelf: {type: Schema.Types.ObjectId, ref: {type: 'lookupList', collection:'k_referencing_self_collection', id:'$warehouse', property: 'shelves', value:'location'}},
+    shelf: {type: Schema.Types.ObjectId, lookupListRef: {collection:'k_referencing_self_collection', id:'$warehouse', property: 'shelves', value:'location'}},
   };
   */
-  export interface IFngLookupListReference {
-    type: 'lookupList';
+  export interface IFngLookupListReference extends IBaseArrayLookupReference {
     collection: string;   // collection that contains the list
     /*
     Some means of calculating _id in collection.  If it starts with $ then it is property in record
     */
     id: string;
-    property: string;
-    value: string;
   }
 
   /*
@@ -74,11 +73,15 @@ declare module fng {
   link allows the setting up of hyperlinks for lookup reference fields
   */
   export interface IFngLinkSetup {
-    linkOnly?: boolean;  // if true (which at the time of writing is the only option supported) then the input element is not generated.
+    linkOnly?: boolean;  // if true then the input element is not generated (this overrides label)
+    label?: boolean;   // Make a link out of the label (causes text to be overridden) (this overrides text)
     form?: string;    // can be used to generate a link to a custom schema
+    linktab?: string;    // can be used to generate a link to a tab on a form
     text?: string;   // the literal value used for the link. If this property is omitted then text is generated from the field values of the document referred to by the link.
   }
 
+  export type FieldSizeString = 'mini' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | 'block-level';  // sets control width.  Default is 'medium''
+
   export interface IFngSchemaTypeFormOpts {
     /*
       The input type to be generated - which must be compatible with the Mongoose type.
@@ -97,19 +100,21 @@ declare module fng {
      */
     type?: string;
 
-    hidden?: boolean;   // inhibits this schema key from appearing on the generated form.
-    label?: string | null;   // overrides the default input label. label:null suppresses the label altogether.
-    ref?: IFngLookupReference | IFngInternalLookupReference;
-
+    hidden?: boolean;         // inhibits this schema key from appearing on the generated form.
+    label?: string | null;    // overrides the default input label. label:null suppresses the label altogether.
+    ref?: string;             // reference to another collection
+    internalRef? : IFngInternalLookupReference;
+    lookupListRef?: IFngLookupListReference;
     id?: string; // specifies the id of the input field (which defaults to f_name)
 
     placeHolder?: string // adds placeholder text to the input (depending on data type).
     help?: string;  // adds help text under the input.
     helpInline?: string;  // adds help to the right of the input.
-    popup?: string;  // adds popup help as specified.
+    popup?: string;  // adds title (popup help) as specified.
+    ariaLabel?: string;  // adds aria-label as specified.
     order?: number;  // allows user to specify the order / tab order of this field in the form. This overrides the position in the Mongoose schema.
-    size?: 'mini' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | 'block-level';  // sets control width.  Default is 'medium''
-    readonly?: boolean;  // adds the readonly attribute to the generated input (currently doesn't work with date - and perhaps other types).
+    size?: FieldSizeString;
+    readonly?: boolean | string;  // adds the readonly or ng-readonly attribute to the generated input (currently doesn't work with date - and perhaps other types).
     rows?: number | 'auto';  // sets the number of rows in inputs (such as textarea) that support this. Setting rows to "auto" makes the textarea expand to fit the content, rather than create a scrollbar.
     tab?: string;  // Used to divide a large form up into a tabset with multiple tabs
     showWhen?: IFngShowWhen | string;  // allows conditional display of fields based on values elsewhere.  string must be an abular expression.
@@ -123,7 +128,7 @@ declare module fng {
 
     class?: string;  // allows arbitrary classes to be added to the input tag.
     inlineRadio?: boolean;  // (only valid when type is radio) should be set to true to present all radio button options in a single line
-    link?: IFngLinkSetup; // handles displaying links for IFngLookupReference lookups
+    link?: IFngLinkSetup; // handles displaying links for ref lookups
 
     /*
       With a select / radio type you can specify the options.
@@ -146,17 +151,28 @@ declare module fng {
     /*
     The next few options relate to the handling and display of arrays (including arrays of subdocuments)
      */
-    noAdd?: boolean; // inhibits an Add button being generated for arrays.
+    noAdd?: boolean | string; // inhibits an Add button being generated for arrays.
+    noneIndicator?: boolean; // show "None" where there's no add button and no array items
     unshift?: boolean; // (for arrays of sub documents) puts an add button in the sub schema header which allows insertion of new sub documents at the beginning of the array.
-    noRemove?: boolean;  // inhibits a Remove button being generated for array elements.
-    formstyle?: 'inline' | 'vertical' | 'horizontal' | 'horizontalCompact';  // (only valid on a sub schema) sets style of sub form.
-    sortable? : boolean;  // Allows drag and drop sorting of arrays - requires angular-ui-sortable
+    noRemove?: boolean | string;  // inhibits a Remove button being generated for array elements.
+    formstyle?: formStyle;  // (only valid on a sub schema) sets style of sub form.
+    sortable? : boolean | string;  // Allows drag and drop sorting of arrays - requires angular-ui-sortable
+    ngClass?: string; // Allows for conditional per-item styling through the addition of an ng-class expression to the class list of li elements created for each item in the array
+    subDocContainerType?: 'fieldset' | 'well' | 'well-large' | 'well-small' | string | ((info) => {before: '', after: ''}); // allows each element in the array to be nested in a container
+    subDocContainerProps?: any; // the parameters that will be passed if subDocContainerType is a function
 
     /*
     The next section relates to the display of sub documents
      */
     customSubDoc?: string; // Allows you to specify custom HTML (which may include directives) for the sub doc
+    customHeader?: string; // Allows you to specify custom HTML (which may include directives) for the header of a group of sub docs
     customFooter?: string; // Allows you to specify custom HTML (which may include directives) for the footer of a group of sub docs
+
+    /*
+      Suppresses warnings about attenpting deep nesting which would be logged to console in some circumstances when a
+      directive fakes deep nesting
+     */
+    suppressNestingWarning? : boolean;
   }
 
   // Schema passed from server - derived from Mongoose schema
@@ -169,12 +185,15 @@ declare module fng {
     step? : number;
   }
 
+  export type fieldType = 'string' | 'text' | 'textarea' | 'number' | 'select' | 'link' | 'date' | 'checkbox' | 'password' | 'radio';
+
   // Schema used internally on client - often derived from IFieldViewInfo passed from server
   export interface IFormInstruction extends IFieldViewInfo {
     id? : string;   // id of generated DOM element
-    type?: 'string' | 'text' | 'textarea' | 'number' | 'select' | 'link' | 'date' | 'checkbox' | 'password';
-    rows? : number
-    label: string;
+    type?: fieldType;
+    defaultValue? : any;
+    rows? : number;
+    label?: string;
     options?: any;
     ids?: any;
     hidden?: boolean;
@@ -182,11 +201,38 @@ declare module fng {
     add? : string;
     ref? : any;
     link? : any;
-    linkText?: string;
+    linktext?: string;
+    linklabel?: boolean;
     form?: string;           // the form that is linked to
     select2? : any;          // deprecated
+    schema?: IFormInstruction[];   // If the field is an array of fields
+    intType? : 'date';
+    [ directiveOptions: string] : any;
+  }
+
+  export interface IContainer {
+    /*
+      Type of container, which determines markup.  This is currently only available when the schema is generated by
+      the client for use independent of the BaseController
+      In the case of a string which does not match one of the predefined options
+      the generated container div is given the class of the name
+     */
+    containerType: 'fieldset' | 'well' | 'tabset' | 'tab' | 'well-large' | 'well-small' | string;
+    title?: string;
+
+    /*
+      h1...h6 will use a header style
+      anything else will be used as a paragraph stype
+     */
+    titleTagOrClass? : string;
+    content: IFormInstruction[];
   }
 
+  export type IFormSchemaElement = IFormInstruction | IContainer;
+
+  export type IFormSchema = IFormSchemaElement[];
+  export type IControlledFormSchema = IFormInstruction[];
+
   export interface IEnumInstruction {
     repeat: string;
     value: string;
@@ -198,13 +244,13 @@ declare module fng {
     allowLocationChange: boolean;   // Do we allow location change or prompt for permission
   }
   export interface IRecordHandler {
-    convertToMongoModel(schema: Array<IFieldViewInfo>, anObject: any, prefixLength: number, scope: IFormScope): any;
-    createNew(dataToSave: any, options: any, scope: IFormScope): void;
-    deleteRecord(model: any, id: any, scope: IFormScope, ctrlState: any): void;
-    updateDocument(dataToSave : any, options: any, scope: IFormScope, ctrlState: any) : void;
+    convertToMongoModel(schema: IControlledFormSchema, anObject: any, prefixLength: number, scope: IFormScope): any;
+    createNew(dataToSave: any, options: any, scope: IFormScope, ctrlState: IFngCtrlState): void;
+    deleteRecord(id: string, scope: IFormScope, ctrlState: IFngCtrlState): void;
+    updateDocument(dataToSave : any, options: any, scope: IFormScope, ctrlState: IFngCtrlState) : void;
     readRecord($scope: IFormScope, ctrlState);
     scrollTheList($scope: IFormScope);
-    getListData($scope: IFormScope, record, fieldName, listSchema);
+    getListData(record, fieldName, listSchema?, $scope?: IFormScope);
     suffixCleanId(inst, suffix);
     setData(object, fieldname, element, value);
     setUpLookupOptions(lookupCollection, schemaElement, $scope: IFormScope, ctrlState, handleSchema);
@@ -220,13 +266,14 @@ declare module fng {
 
   export interface IFormGenerator {
     generateEditUrl(obj, $scope:IFormScope): string;
+    generateViewUrl(obj, $scope:IFormScope): string;
     generateNewUrl($scope: IFormScope): string;
     handleFieldType(formInstructions, mongooseType, mongooseOptions, $scope: IFormScope, ctrlState);
     handleSchema(description: string, source, destForm, destList, prefix, doRecursion: boolean, $scope: IFormScope, ctrlState);
     updateDataDependentDisplay(curValue, oldValue, force, $scope: IFormScope);
-    add(fieldName, $event, $scope: IFormScope);
-    unshift(fieldName, $event, $scope: IFormScope);
-    remove(fieldName, value, $event, $scope: IFormScope);
+    add(fieldName: string, $event, $scope: IFormScope, modelOverride?: any);
+    unshift(fieldName: string, $event, $scope: IFormScope, modelOverride?: any);
+    remove(fieldName: string, value, $event, $scope: IFormScope, modelOverride?: any);
     hasError(formName, name, index, $scope: IFormScope);
     decorateScope($scope: IFormScope, formGeneratorInstance, recordHandlerInstance: IRecordHandler, sharedStuff);
   }
@@ -235,6 +282,9 @@ declare module fng {
     formInstructions: IFormInstruction;
     lastPart: string;
     possibleArray: string;
+    // If the looked-up record changes, we use these fields to see if the old lookup value also exists in the new lookup record
+    oldValue?: string | string[];
+    oldId?: string | string[];
   }
 
   export interface IFngLookupHandler {
@@ -260,7 +310,9 @@ declare module fng {
     modelName: string;
     formName: string;
     alertTitle: any;
+    errorVisible: boolean;
     errorMessage: any;
+    errorHideTimer: number;
     save: any;
     newRecord: boolean;
     initialiseNewRecord?: any;
@@ -271,11 +323,10 @@ declare module fng {
     isCancelDisabled: any;
     isNewDisabled: any;
     isSaveDisabled: any;
-    disabledText: any;
+    whyDisabled: string;
     unconfirmedDelete: boolean;
     getVal: any;
     sortableOptions: any;
-    tabDeselect: any;
     tabs?: Array<any>;              // In the case of forms that contain a tab set
     tab?: string;                   // title of the active tab - from the route
     activeTabNo?: number;
@@ -296,7 +347,8 @@ declare module fng {
     cancel: () => any;
     showError: (error: any, alertTitle? : string) => void;
     prepareForSave: (cb: (error: string, dataToSave?: any) => void) => void;
-    formSchema: IFormInstruction[];
+    setDefaults: (formSchema: IFormSchema, base?: string) => any;
+    formSchema: IControlledFormSchema;
     baseSchema: () => Array<any>;
     setFormDirty: any;
     add: any;
@@ -308,24 +360,37 @@ declare module fng {
     skipCols: any;
     setPristine: any;
     generateEditUrl: any;
+    generateViewUrl: any;
     generateNewUrl: any;
     scrollTheList: any;
     getListData: any;
-    dismissError: any;
+    phaseWatcher: any;
+    dismissError: () => void;
+    stickError: () => void;
+    clearTimeout: () => void;
     handleHttpError: (response: any) => void;
     dropConversionWatcher: () => void;
+    readingRecord?: Promise<any>;
+    onSchemaFetch?: (description: string, source: IFieldViewInfo[]) => void;
+    onSchemaProcessed?: (description: string, formSchema: IFormInstruction[]) => void;
+    updateQueryForTab?: (tab: string) => void;
+    tabDeselect?: ($event: any, $selectedIndex: number) => void;
+    setUpCustomLookupOptions?: (schemaElement: IFormInstruction, ids: string[], options: string[], baseScope: any) => void;
   }
 
   export interface IContextMenuDivider {
     divider: boolean;
   }
   export interface IContextMenuOption {
-    // For it to make any sense, a menu option needs one of the next two properties
+    // For it to make any sense, a menu option needs one of the next three properties
     url?: string;
     fn?: () => void;
+    urlFunc?: () => string;
 
-    text: string;
+    text?: string;
+    textFunc?: () => string;
     isDisabled?: () => boolean;
+    isHidden?: () => boolean;
 
     // Does the option appear in the following contexts?
     listing: boolean;
@@ -336,7 +401,8 @@ declare module fng {
   export interface IModelController extends IFormScope {
     onBaseCtrlReady? : (baseScope: IFormScope) => void;   // Optional callback after form is instantiated
     onAllReady? : (baseScope: IFormScope) => void;        // Optional callback after form is instantiated and populated
-    contextMenu? : Array<IContextMenuOption | IContextMenuDivider>
+    contextMenu? : Array<IContextMenuOption | IContextMenuDivider>;
+    contextMenuPromise? : Promise<Array<IContextMenuOption | IContextMenuDivider>>;
   }
 
   export interface IBaseFormOptions {
@@ -344,7 +410,7 @@ declare module fng {
      * The style of the form layout.  Supported values are horizontalcompact, horizontal, vertical, inline
      */
     //TODO supported values should be in an enum
-    formstyle?: string;
+    formstyle?: formStyle;
     /**
      * Model on form scope (defaults to record).
      * <li><strong>model</strong> the object in the scope to be bound to the model controller.  Specifying
@@ -359,6 +425,11 @@ declare module fng {
      * Normally first field in a form gets autofocus set.  Use this to prevent this
      */
     noautofocus?: string;
+    /*
+    Suppress the generation of element ids
+    (sometimes required when using nested form-inputs in a directive)
+     */
+    noid? : boolean;
   }
 
   export interface IFormAttrs extends IFormOptions, angular.IAttributes {
@@ -367,6 +438,7 @@ declare module fng {
      */
     schema : string;
     forceform?: string;    // Must be true or omitted.  Forces generation of the <strong>form</strong> tag when model is specified
+    noid? : boolean;
   }
 
   export interface IFormOptions extends IBaseFormOptions {
@@ -375,6 +447,8 @@ declare module fng {
     subkeyno?: number;
     subschema? : string;
     subschemaroot? : string;
+    viewform? : boolean;
+    suppressNestingWarning? : boolean;
   }
 
   export interface IBuiltInRoute {
@@ -400,6 +474,7 @@ declare module fng {
 
     variantsForDemoWebsite? : any;  // Just for demo website
     variants?: any;                 // Just for demo website
+    onDelete?: string;              // Supports literal (such as '/') or 'new' (which will go to a /new of the model) default is to go to the list view
   }
 
   export interface IFngRoute {
@@ -415,4 +490,4 @@ declare module fng {
 
 }
 
-declare var formsAngular: angular.IModule;
+declare var formsAngular: fng.IFng;