Form Code

👨‍💻️ What is form code ?

The form code allows you to run and execute some custom javascript code while the survey is starting and running.

Your custom code must extends the NGSFormCode object to be executed.

/*
 Sample that shows how to post respondent 
 answers to a third party REST API.

 The Form code can also be used to insert third party 
 API codes to your form page using the onInit or onLoaded events
*/
class CustomFormCode extends NGSFormCode { 
  /* Form has been loaded */
  onInit() {}

  /* A security item requires authentication will be called 
     when a survey requires authentication from an security item  
  */
  onAuthenticate(securityItem) {}

  /* A security item requires authentication will be called 
     a security item has been succesfully authenticated. 
     Returning a string from this method will block the 
     access the survey with the message defined by the 
     returning string.  
  */
  onAuthenticated(securityItem, securityItemAuthorization) {}

  /* Form has been authorized by all security items and loaded  
    with questions of its first visible page */
  onLoaded() {}

  /* Trigger when a new page is being loaded a null value for the page 
    indicates that the end thank you page is being loaded 
  */
  onPageLoad(page) {}

  /* Trigger once the respondent session answers have been saved on the server.
  action defines the action that triggered the save progress it can be any of following values
  None = 0, Button = 1, PageChange = 2, QuestionChange = 3, Email = 4, Auto = 5 
  */
  onSaveProgress(ngsRespondent, action) {}

  /* Trigger once the respondent answers have been saved on the server. */
  onSubmit(ngsRespondent) {
    // Respondent details
    console.log(ngsRespondent.respondent);

    // Respondent answers
    console.log(ngsRespondent.answers);

    // security items data attributes values
    console.log(ngsRespondent.dataAttributes);
    
    this.formContext.httpClient.post('http://www.yourrestsite.com/yourapi/saveanswers', 
        ngsRespondent.answers, {}).subscribe();
  }

  /* Trigger once the respondent answers have been updated on the server. */
  onUpdate(ngsRespondent) {console.log('update', ngsRespondent);}
}

The NGSForm base class provide following properties that you can reuse in your derived class.

class NGSFormCode {
    // Current survey
    survey;
    // Form context helper class
    formContext;
    // Current respondent answers
    respondentAnswers;
    // Current respondent
    respondent;
    // Current running language code
    language;
    // Current data attribute values from security items
    dataAttributesValues;
 }

FormContext provides following properties that you can use from your NGSFormCode derived class through the formContext property.

export class FormContext {
    // Current respondent answers
    private respondentAnswers$: Observable<RespondentAnswer[]>,
    // Current security items data attributes
    private dataAttributesValues$: Observable<RespondentAnswer[]>,
    // Current respondent language
    private language$: Observable<Language>,
    // Angular HTTP client
    private httpClient: HttpClient,
}

Respondent is the respondent properties

export interface Respondent {
  id: string;
  surveyId?: string;
  panelistId?: string;
  contextUsername?: string;
  resumeUId?: string;
  resumePageId?: string;
  resumeQuestionId?: string;
  startDate: Date;
  voteDate?: Date;
  archiveDate?: Date;
  iPSource?: string;
  changeUID?: string;
  progressSaveDate?: Date;
  languageCode: string;
  timeToEnd?: number;
  validated: boolean;
  userAgent?: string;
  platform?: string;
  platformOS?: number;
  mobileOS?: boolean;
  longitude?: number;
  latitude?: number;
}

Respondent is the respondent properties

export interface Respondent {
  id: string;
  surveyId?: string;
  panelistId?: string;
  contextUsername?: string;
  resumeUId?: string;
  resumePageId?: string;
  resumeQuestionId?: string;
  startDate: Date;
  voteDate?: Date;
  archiveDate?: Date;
  iPSource?: string;
  changeUID?: string;
  progressSaveDate?: Date;
  languageCode: string;
  timeToEnd?: number;
  validated: boolean;
  userAgent?: string;
  platform?: string;
  platformOS?: number;
  mobileOS?: boolean;
  longitude?: number;
  latitude?: number;
}

SecurityItemAuthorization ikeeps track of all the properties returned by an authenticated security item.

export interface SecurityItemAuthorization {
  securityItemId?: string;
  authorizationToken?: string;
  sessionCode?: string;
  sessionRespondent?: NGSRespondent;
  sessionPanelist: NGSPanelist;
  dataAttributesValues?: SecurityItemDataAttributeValue[];
}