FormService

The FormService is an angular service that constitutes as a high level api on top of the Priority Web SDK for forms. It provides functions that perform several related actions on a form for easier usage of the SDK.

It also deals with storing locally the form’s data that was retrieved, to enable sharing it between different pages and components in your app.

Another great built in feature of the FormService is that it handles all massages returned by the server from the MessagesCallback, by alerting them using the MessageHandler.

In addition it also handles updating the local form’s data returned by the server from the UpdateFormCallback, making sure your local data is always up to date.


Form

The top level of the FormService is the Form.

Usage
import { FormService, Form } from 'priority-ionic';

// use the FormService in any of your Services, Pages or Components
export class ... {
	
	form: Form;

	// inject it using Angular's Dependency injector
	constructor(private formService: FormService) {}

	init() {
		this.formService.startFormAndGetRows('CUSTOMERS', 'company_name').then((form: Form) => {
			this.form = form;
		});
	}
}
Instance Members


getForm(formName: string): Form

Returns the locally stored Form.


startParentForm(formName: string, company: string, autoRetriveFirstRows?: number): Promise<From>

Starts a parent form and stores the form object locally.

Returns Promise - that resolves to the started Form.


startFormAndGetRows(formName: string, company: string, filter: Filter = null, autoRetriveFirstRows?: number): Promise<any>

Starts a parent form and retrieves its rows according to the specified filter (if it is specified). Form and rows are stored localLy.

Returns Promise - that resolves to the started Form.


endForm(form: Form): Promise<any> Ends the form.


Form Rows

Form rows contain the form’s data records.

Instance Members


getLocalRows(form: Form)

Returns the locally stored Rows for this form.


getRows(form: Form, fromRow: number, isMerge: boolean = true): Promise<any>

Retrieves the next 115 rows of the form, starting at the specified row number. If a filter is specified, rows will be retrieved according to the filter.

Rows are stored locally. If isMerge is true, the new rows are added to previously stored rows; if false, the new rows replaces the old ones.

Returns Promise - that resolves with the Rows.


clearRows(form: Form): Promise<any>

Clears the rows of a given form.

Returns Promise - with an empty object.


getRowsAndReplace(form: Form): Promise<any>

Clears rows of a given form and then retrieves new ones.

Returns Promise - that resolves with the new Rows.


Form Row

The form row provides a single record stored in the form.

Instance Members


getFormRow(form: Form, rowInd)

Returns the locally stored Row for this form, according to its index number.


<!– Chanamel 20/06/2017 - commenting out as doesn’t seem to be documented yet setIsRowChangesSaved(form: Form, rowInd, isSaved: boolean) getIsRowChangesSaved(form: Form, rowInd) getIsNewRow(form: Form, rowInd) setNotNewRow(form: Form, rowInd)

Should be changes to setKey, getKey and deleteKey!!! –>


deleteLastFormRow(form: Form)

Deletes the local last form row, It is used mainly as a workaround for some issues where the local rows are updated….


setActiveRow(form: Form, rowInd): Promise<any>

Defines a specific row (according to its index) as the active row in the form.

Returns Promise - with the active row object.


updateField(form: Form, newValue, columnName): Promise<any>

Modifies a field’s value for the currently active row in the form.

Returns Promise - with empty object.


saveRow(form: Form, rowInd, isBackToPrevForm: number): Promise<any>

Saves all the changes (upates) that were made to the currently active row.

Returns Promise - with empty object.


undoRow(form: Form): Promise<any>

Undoes all changes (updates) made to the currently active row.

Returns Promise - with empty object.


newRow(form: Form): Promise<any>

Creates a new row and adds it to the rows of the specified form.

Returns Promise - that resolves with the new row’s index.


deleteRow(form: Form): Promise<any>

Deletes the currently active row from the specificed form.

Returns Promise - with empty object.


deleteListRow(form: Form, rowInd): Promise<any>

Deletes the specfied row from the specified form.

Returns Promise - with empty object.


Search and Choose

Instance Members


openSearchOrChoose(form: Form, colName, fieldVal): Promise<any>

Opens a Search list or a Choose list for a field in the currently active row, according to the specified colName.

If a fieldVal is specified, the returned list contains only results that match this value. If the field already contains a value, fieldVal will automatically be assigned this value unless specified otherwise.

Note: A different fieldVal than the current value in the field will update the field’s value to the specified fieldval.

Returns a Promise that resolves to a SearchResult object.


search(form: Form, value: string): Promise<any>

Performs a search in the currently open Search list according to the specified value.

Returns a Promise with the search results.


SubForm

Instance Members


startSubform(parentForm: Form, subformName: string, onWarnings = null): Promise<Form>

Starts ‘subformName’, a subForm of the parentForm.

Returns a Promise with the subform’s Form object.


startSubFormAndGetRows(parentForm: Form, subformName, onWarnings = null): Promise<Form>

Starts ‘subformName’ subForm and retrieves its rows.

Returns a Promise with the subform’s Form object including the retrieved rows.


getSubforms(form: Form, subformNames: string[]): Promise<{[key: string]: Form}>

Retrieve multiple subforms’ rows (of the same parent form). For each subform it starts the subform, gets its rows, and then ends the subform. Retrieves the parentForm obj and an array of the subformNames to retrieve.

Returns a Promise with a subforms object. Each subform has it’s name as the key and it’s Form object including the retrieved rows as the value.


setActiveSubformRow(parentForm: Form, subformName, rowInd): Promise<Form>

Starts the specified subform and sets the activeRow to the specified index.

Returns a Promise with the subform’s Form object.


addSubformRow(parentForm: Form, subformName): Promise<number>

Starts the specified subform and creates a new row.

Returns a Promise with the new row’s index.


deleteSubformListRow(parentForm: Form, subformName, rowInd): Promise<any>

Deletes the specified subform row according to the index. Starts the subform, sets the row as active, deletes the row, and then ends the subform.

Returns a Promise with an empty object.


Filter

Instance Members


buildSearchFilter(form: Form, columnNames: string[], search: string)

Creates a filter for searching for a specific string in the specified column names.

Returns a Promise with the Filter object.


setFilter(form: Form, columnNames: string[], search: string): Promise<any>

Sets a filter on the form that searches for the specified search string in the specified column names, then retrieves form rows that match the filter. If the specified string is empty, the currently active filter in the form is cleared, instead.

Returns a Promise with the retrieved rows.


clearSearchFilter(form: Form): Promise<any>

Clears the active search filter for the specified form.

Returns a Promise with an empty object.


setSearchFilter(form: Form, filter: Filter)

Sets a previously created search filter for row retrieval as the active filter for the specified form.

Returns a Promise with an empty object.


Text

Instance Members


saveText(form: Form, text, addTextFlag? = 1, signatureFlag? = 1): Promise<any>

Saves text to a text form. By default, text is added to existing text, along with the user’s signature. If addTextFlag is set to 0, the new text will replace existing text. If signatureFlag is set to 0, the user’s signature will not be appended to the text.

Returns a Promise with an empty object.


Files

Instance Members


uploadFile(form: Form, file): Observable<FileUploadResult>

Uploads a single file (from the javascript FileList object, returned from HTML5 file input).

Returns an Observable that results to the FileUploadResult.


uploadImage(form: Form, imageData: string, type: string): Observable<FileUploadResult>

Uploads an image as data-url. Receives the data and its type.

Returns an Observable that results to the FileUploadResult.


cancelUpload(form: Form)

Cancels a file or image upload.


getFileUrl(form: Form, currentSrc): string

Translates the relative path of an attachment in the Priority server into its full path.

Returns a string with the file’s full path.


Direct Activations

Instance Members


executeDirectActivation(form: Form, activationName: string, type: string): Promise<any>

Runs a direct activation for the currently active form row, according to the specified ‘activationName’.

Returns a Promise with an empty object.