formsett™ Actuator

/* @name     FS_Email
   @title    Email address validation
   @category Validation
   @order    10
   @description Checks an email field holds one plausibly formed address (name@domain.tld) and trims stray spaces. Blank is allowed, so pair it with Required for mandatory fields.
   @usage    Field Properties > Validate > Run custom validation script:
     FS_ValidateEmail();
*/
function FS_ValidateEmail() {
  var v = String(event.value).replace(/^\s+|\s+$/g, "");
  event.value = v;
  if (v === "") return;
  if (!/^[^\s@]+@[^\s@]+\.[A-Za-z]{2,}$/.test(v)) {
    app.alert("Please enter a valid email address, for example name@example.com.au", 1);
    event.rc = false;
  }
}

/* @name     FS_Phone
   @title    Australian phone number validation
   @category Validation
   @order    20
   @description Accepts Australian landline, mobile, 13/1300 and 1800 numbers, with or without spaces, brackets or +61, and reformats them consistently (e.g. 0412 345 678, 07 3123 4567, 1300 123 456).
   @usage    Field Properties > Validate > Run custom validation script:
     FS_ValidatePhone();
*/
function FS_ValidatePhone() {
  var raw = String(event.value).replace(/^\s+|\s+$/g, "");
  if (raw === "") { event.value = ""; return; }
  var d = raw.replace(/[\s\-\(\)\.]/g, "");
  if (/^\+?61/.test(d)) d = "0" + d.replace(/^\+?61/, "");
  var out = null;
  if (/^04\d{8}$/.test(d)) out = d.substr(0, 4) + " " + d.substr(4, 3) + " " + d.substr(7);
  else if (/^0[2378]\d{8}$/.test(d)) out = d.substr(0, 2) + " " + d.substr(2, 4) + " " + d.substr(6);
  else if (/^1[38]00\d{6}$/.test(d)) out = d.substr(0, 4) + " " + d.substr(4, 3) + " " + d.substr(7);
  else if (/^13\d{4}$/.test(d)) out = d.substr(0, 2) + " " + d.substr(2, 2) + " " + d.substr(4);
  if (out === null) {
    app.alert("Please enter an Australian phone number, for example 0412 345 678 or 07 3123 4567.", 1);
    event.rc = false;
    return;
  }
  event.value = out;
}

/* @name     FS_ABN
   @title    ABN and ACN validation
   @category Validation
   @order    30
   @description Validates Australian Business Numbers and Australian Company Numbers with the official check-digit algorithms, and formats them (12 345 678 901 / 123 456 789). Catches typos, not unregistered numbers.
   @usage    ABN field, Validate > Run custom validation script:
     FS_ValidateABN();
   ACN field:
     FS_ValidateACN();
   Test a value elsewhere: FS_IsABN("51 824 753 556") returns true/false.
*/
function FS_IsABN(s) {
  var d = String(s).replace(/\s/g, "");
  if (!/^\d{11}$/.test(d)) return false;
  var w = [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19], sum = 0;
  for (var i = 0; i < 11; i++) sum += (Number(d.charAt(i)) - (i === 0 ? 1 : 0)) * w[i];
  return sum % 89 === 0;
}
function FS_IsACN(s) {
  var d = String(s).replace(/\s/g, "");
  if (!/^\d{9}$/.test(d)) return false;
  var sum = 0;
  for (var i = 0; i < 8; i++) sum += Number(d.charAt(i)) * (8 - i);
  return (10 - (sum % 10)) % 10 === Number(d.charAt(8));
}
function FS_ValidateABN() {
  var d = String(event.value).replace(/\s/g, "");
  if (d === "") { event.value = ""; return; }
  if (!FS_IsABN(d)) {
    app.alert("That ABN isn't valid. Please check the 11 digits.", 1);
    event.rc = false;
    return;
  }
  event.value = d.substr(0, 2) + " " + d.substr(2, 3) + " " + d.substr(5, 3) + " " + d.substr(8);
}
function FS_ValidateACN() {
  var d = String(event.value).replace(/\s/g, "");
  if (d === "") { event.value = ""; return; }
  if (!FS_IsACN(d)) {
    app.alert("That ACN isn't valid. Please check the 9 digits.", 1);
    event.rc = false;
    return;
  }
  event.value = d.substr(0, 3) + " " + d.substr(3, 3) + " " + d.substr(6);
}

/* @name     FS_Postcode
   @title    Australian postcode validation
   @category Validation
   @order    40
   @description Postcode must be four digits. Optionally checks it against a state field (QLD 4xxx/9xxx, NSW 1xxx/2xxx, ACT 02xx/26xx/29xx, VIC 3xxx/8xxx, TAS 7xxx, SA 5xxx, WA 6xxx, NT 08xx/09xx).
   @usage    Postcode field, Validate > Run custom validation script:
     FS_ValidatePostcode();
   To also check against a state field (values such as QLD, NSW):
     FS_ValidatePostcode("State");
*/
function FS_PostcodeMatchesState(pc, st) {
  var n = Number(pc);
  st = String(st).toUpperCase().replace(/[^A-Z]/g, "");
  var r = {
    NSW: [[1000, 2599], [2619, 2899], [2921, 2999]],
    ACT: [[200, 299], [2600, 2618], [2900, 2920]],
    VIC: [[3000, 3999], [8000, 8999]],
    QLD: [[4000, 4999], [9000, 9999]],
    SA:  [[5000, 5999]],
    WA:  [[6000, 6999]],
    TAS: [[7000, 7999]],
    NT:  [[800, 999]]
  }[st];
  if (!r) return true; // unknown or blank state: don't block
  for (var i = 0; i < r.length; i++) if (n >= r[i][0] && n <= r[i][1]) return true;
  return false;
}
function FS_ValidatePostcode(stateFieldName) {
  var v = String(event.value).replace(/\s/g, "");
  event.value = v;
  if (v === "") return;
  if (!/^\d{4}$/.test(v)) {
    app.alert("Please enter a four-digit postcode.", 1);
    event.rc = false;
    return;
  }
  if (stateFieldName) {
    var f = event.target.doc.getField(stateFieldName);
    if (f && f.valueAsString !== "" && !FS_PostcodeMatchesState(v, f.valueAsString)) {
      app.alert("Postcode " + v + " doesn't match the state " + f.valueAsString + ". Please check both.", 1);
      event.rc = false;
    }
  }
}

/* @name     FS_Required
   @title    Required-fields check before print or submit
   @category Validation
   @order    50
   @description Lists every visible required field that is still empty, highlights them, and moves to the first one. Returns true when the form is complete, so a button can print, save or submit only then.
   @usage    Print button, Mouse Up > Run a JavaScript:
     if (FS_CheckRequired()) this.print();
   Submit button:
     if (FS_CheckRequired()) this.mailDoc({ cTo: "forms@example.gov.au" });
   Remove the highlights again: FS_ClearRequiredHighlights();
*/
var FS_REQ_HIGHLIGHT = ["RGB", 1, 0.9, 0.9];
var FS_reqHighlighted = [];

function FS__isEmpty(f) {
  if (f.type === "checkbox" || f.type === "radiobutton") return f.value === "Off";
  if (f.type === "signature") {
    try { return f.signatureInfo().status === 0; } catch (e) { return false; }
  }
  return f.valueAsString === "";
}

function FS_CheckRequired(doc) {
  var d = doc || (typeof event !== "undefined" && event.target ? (event.target.doc || event.target) : this);
  FS_ClearRequiredHighlights(d);
  var missing = [], first = null;
  for (var i = 0; i < d.numFields; i++) {
    var f = d.getField(d.getNthFieldName(i));
    if (!f || f.type === "button" || !f.required || f.readonly) continue;
    if (f.display === display.hidden || f.display === display.noView) continue;
    if (!FS__isEmpty(f)) continue;
    missing.push(f.userName || f.name);
    if (first === null) first = f;
    if (f.type !== "checkbox" && f.type !== "radiobutton" && f.type !== "signature") {
      FS_reqHighlighted.push([f.name, f.fillColor]);
      f.fillColor = FS_REQ_HIGHLIGHT;
    }
  }
  if (missing.length === 0) return true;
  var list = missing.slice(0, 15).join("\n• ");
  if (missing.length > 15) list += "\n• and " + (missing.length - 15) + " more";
  app.alert("Please complete the following required fields:\n\n• " + list, 1);
  if (first) first.setFocus();
  return false;
}

function FS_ClearRequiredHighlights(doc) {
  var d = doc || (typeof event !== "undefined" && event.target ? (event.target.doc || event.target) : this);
  for (var i = 0; i < FS_reqHighlighted.length; i++) {
    var f = d.getField(FS_reqHighlighted[i][0]);
    if (f) f.fillColor = FS_reqHighlighted[i][1];
  }
  FS_reqHighlighted = [];
}

/* @name     FS_Dates
   @title    Australian date helpers
   @category Dates
   @order    10
   @description Parses and formats dd/mm/yyyy dates, fills today's date, calculates age and day counts, and rejects future dates (e.g. date of birth). Works alongside Acrobat's built-in date format.
   @usage    Today's date (Calculate > Custom calculation script, or on open):
     event.value = FS_Today();
   Age in years from a date-of-birth field (Calculate):
     event.value = FS_AgeOn(this.getField("DOB").valueAsString);
   Age on a given date: FS_AgeOn("01/05/2020", "31/01/2026")
   Days between two dates: FS_DaysBetween("01/01/2026", "15/01/2026")  // 14
   Reject future dates (Validate):
     FS_ValidateNotFuture();
   Parse to a Date object (or null): FS_ParseDate("31/01/2026")
*/
function FS_ParseDate(s) {
  var m = String(s).replace(/^\s+|\s+$/g, "").match(/^(\d{1,2})[\/\.\-](\d{1,2})[\/\.\-](\d{2}|\d{4})$/);
  if (!m) return null;
  var dd = Number(m[1]), mm = Number(m[2]), yy = Number(m[3]);
  if (m[3].length === 2) yy += (yy > 50 ? 1900 : 2000);
  var d = new Date(yy, mm - 1, dd, 12, 0, 0);
  if (d.getFullYear() !== yy || d.getMonth() !== mm - 1 || d.getDate() !== dd) return null;
  return d;
}

function FS_FormatDate(d, fmt) {
  return util.printd(fmt || "dd/mm/yyyy", d);
}

function FS_Today(fmt) {
  return util.printd(fmt || "dd/mm/yyyy", new Date());
}

function FS_AgeOn(dob, onDate) {
  var b = FS_ParseDate(dob);
  if (!b) return "";
  var o = onDate ? FS_ParseDate(onDate) : new Date();
  if (!o) return "";
  var age = o.getFullYear() - b.getFullYear();
  if (o.getMonth() < b.getMonth() || (o.getMonth() === b.getMonth() && o.getDate() < b.getDate())) age--;
  return age < 0 ? "" : age;
}

function FS_DaysBetween(from, to) {
  var a = FS_ParseDate(from), b = FS_ParseDate(to);
  if (!a || !b) return "";
  return Math.round((b - a) / 86400000);
}

function FS_ValidateNotFuture() {
  if (String(event.value) === "") return;
  var d = FS_ParseDate(event.value);
  if (!d) return; // leave format errors to the field's own date format
  var today = new Date();
  today.setHours(23, 59, 59, 0);
  if (d > today) {
    app.alert("This date can't be in the future.", 1);
    event.rc = false;
  }
}

/* @name     FS_Sum
   @title    Totals and number helpers
   @category Calculation
   @order    10
   @description Sums a list of fields or a whole field group (e.g. every Amount.0, Amount.1 ...), treating blanks and stray text as zero. Shorter, safer custom calculations for totals rows.
   @usage    Total of named fields (Calculate > Custom calculation script):
     event.value = FS_SumFields(["Fee1", "Fee2", "Fee3"]);
   Total of a whole group, including rows on spawned pages that keep the group name:
     event.value = FS_SumGroup("Amount");
   Numeric value of one field (blank = 0):
     var n = FS_Num("Hours");
   Round to 2 decimal places: FS_Round(n, 2)
*/
function FS__docOf() {
  return (typeof event !== "undefined" && event.target) ? (event.target.doc || event.target) : this;
}

function FS_ToNumber(v) {
  var n = Number(String(v).replace(/[^0-9.\-]/g, ""));
  return isNaN(n) ? 0 : n;
}

function FS_Num(name) {
  var f = FS__docOf().getField(name);
  return f ? FS_ToNumber(f.value) : 0;
}

function FS_SumFields(names) {
  var total = 0;
  for (var i = 0; i < names.length; i++) total += FS_Num(names[i]);
  return FS_Round(total, 10);
}

function FS_SumGroup(parentName) {
  var f = FS__docOf().getField(parentName);
  if (!f) return 0;
  var kids = f.getArray ? f.getArray() : null;
  if (!kids) return FS_ToNumber(f.value);
  var total = 0;
  for (var i = 0; i < kids.length; i++) total += FS_ToNumber(kids[i].value);
  return FS_Round(total, 10);
}

function FS_Round(n, places) {
  var p = Math.pow(10, places || 0);
  return Math.round(n * p) / p;
}

/* @name     FS_Case
   @title    Text case and character filters
   @category Formatting
   @order    10
   @description Keystroke filters for UPPER CASE entry and digits-only entry, plus a Title Case tidy-up for names and addresses when the field is left.
   @usage    Upper case as you type (Format > Custom > Custom keystroke script):
     FS_UpperKeystroke();
   Digits only, e.g. for reference numbers (Custom keystroke script):
     FS_DigitsKeystroke();
   Title Case on exit (Validate > Run custom validation script):
     FS_TitleCase();
*/
function FS_UpperKeystroke() {
  if (event.change) event.change = event.change.toUpperCase();
}

function FS_DigitsKeystroke() {
  if (event.willCommit || !event.change) return;
  var clean = event.change.replace(/\D/g, "");
  if (clean !== event.change) {
    event.change = clean;
    if (clean === "") app.beep(0);
  }
}

function FS_TitleCase() {
  var v = String(event.value);
  if (v === "") return;
  event.value = v.toLowerCase().replace(/(^|[\s\-'\(\/])([a-z])/g, function (all, sep, ch) {
    return sep + ch.toUpperCase();
  }).replace(/\bMc([a-z])/g, function (all, ch) { return "Mc" + ch.toUpperCase(); })
    .replace(/\b(Qld|Nsw|Act|Nt|Sa|Wa|Tas|Vic|Po)\b/g, function (s) { return s.toUpperCase(); });
}

/* @name     FS_ShowHide
   @title    Show, hide and require fields
   @category Behaviour
   @order    10
   @description Shows or hides one or more fields (or whole groups) and optionally makes them required only while visible, clearing them when hidden so stale answers don't print. Typical for "If yes, please explain" questions.
   @usage    Yes/No radio group, Mouse Up on each button (or Validate on a combo box):
     FS_ShowIf(event.target.value === "Yes", ["Explain", "ExplainDate"], true);
   Arguments: condition, field names (or one name), make required while shown.
   Plain show/hide: FS_Show(["Notes"], true)   FS_Show("Notes", false)
*/
function FS__showDoc() {
  return (typeof event !== "undefined" && event.target) ? (event.target.doc || event.target) : this;
}

function FS_Show(names, visible) {
  if (typeof names === "string") names = [names];
  var d = FS__showDoc();
  for (var i = 0; i < names.length; i++) {
    var f = d.getField(names[i]);
    if (f) f.display = visible ? display.visible : display.hidden;
  }
}

function FS_ShowIf(condition, names, requireWhenShown) {
  if (typeof names === "string") names = [names];
  var d = FS__showDoc();
  for (var i = 0; i < names.length; i++) {
    var f = d.getField(names[i]);
    if (!f) continue;
    f.display = condition ? display.visible : display.hidden;
    if (requireWhenShown) f.required = !!condition;
    if (!condition) {
      if (f.type === "checkbox" || f.type === "radiobutton") f.value = "Off";
      else if (f.type !== "button") f.value = "";
    }
  }
}

/* @name     FS_Reset
   @title    Clear form with confirmation
   @category Behaviour
   @order    20
   @description A Clear Form button that asks before wiping anything, and can clear just some fields or groups instead of the whole form.
   @usage    Clear button, Mouse Up > Run a JavaScript:
     FS_ResetConfirm();
   Clear only some fields or groups:
     FS_ResetConfirm(["Section2", "Section3"], "Clear sections 2 and 3?");
*/
function FS_ResetConfirm(fieldNames, message) {
  var d = (typeof event !== "undefined" && event.target) ? (event.target.doc || event.target) : this;
  var msg = message || "This will clear every entry in the form. Do you want to continue?";
  if (app.alert({ cMsg: msg, cTitle: "Clear form", nIcon: 2, nType: 2 }) !== 4) return false;
  if (fieldNames) d.resetForm(fieldNames); else d.resetForm();
  return true;
}

/* @name     FS_Spawn
   @title    Add and remove pages from a hidden template
   @category Behaviour
   @order    30
   @description Adds a page from a hidden page template (an extra attendance or continuation sheet, say) with renamed fields so each copy keeps its own entries, and lets a button on the added page remove that page again.
   @usage    "Add page" button, Mouse Up:
     FS_SpawnTemplate("Continuation");
   Insert after the current page instead of at the end:
     FS_SpawnTemplate("Continuation", this.pageNum + 1);
   "Remove this page" button placed on the template page itself (works on each added copy, does nothing on the hidden original):
     FS_RemoveThisPage("Continuation");
   Number of copies added so far: FS_SpawnCount("Continuation")
*/
function FS__spawnDoc() {
  return (typeof event !== "undefined" && event.target) ? (event.target.doc || event.target) : this;
}

function FS_SpawnTemplate(templateName, atPage) {
  var d = FS__spawnDoc();
  var t = d.getTemplate(templateName);
  if (!t) {
    app.alert("Page template \"" + templateName + "\" was not found in this form.", 0);
    return false;
  }
  var nPage = (typeof atPage === "number") ? atPage : d.numPages;
  t.spawn({ nPage: nPage, bRename: true, bOverlay: false });
  d.pageNum = nPage;
  return true;
}

// Spawned copies with bRename carry field names "P<n>.<template>.<field>".
function FS__spawnedPages(d, templateName) {
  var re = new RegExp("^P\\d+\\." + templateName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\.");
  var pages = {};
  for (var i = 0; i < d.numFields; i++) {
    var name = d.getNthFieldName(i);
    if (!re.test(name)) continue;
    var f = d.getField(name);
    if (!f) continue;
    var p = f.page;
    if (typeof p === "number") pages[p] = true;
    else if (p && p.length) for (var j = 0; j < p.length; j++) pages[p[j]] = true;
  }
  return pages;
}

function FS_SpawnCount(templateName) {
  var pages = FS__spawnedPages(FS__spawnDoc(), templateName), n = 0;
  for (var k in pages) if (pages.hasOwnProperty(k) && Number(k) >= 0) n++;
  return n;
}

function FS_RemoveThisPage(templateName) {
  var d = FS__spawnDoc();
  var page = event.target.page;
  if (typeof page !== "number") page = page && page.length ? page[0] : d.pageNum;
  if (!FS__spawnedPages(d, templateName)[page]) return false; // not an added copy
  if (app.alert({ cMsg: "Remove this page and everything entered on it?", cTitle: "Remove page", nIcon: 2, nType: 2 }) !== 4) return false;
  d.deletePages(page);
  return true;
}

/* @name     FS_PrintClean
   @title    Keep buttons off the printout
   @category On open
   @order    10
   @description When the form opens, sets every visible button to "Visible but doesn't print", so Print, Clear and Submit buttons never appear on paper or in printed PDFs. Runs automatically; nothing to call.
   @usage    Runs automatically when the form opens. To exempt a button, give it a name starting with "Print_" (e.g. Print_Logo).
*/
(function () {
  try {
    for (var i = 0; i < this.numFields; i++) {
      var f = this.getField(this.getNthFieldName(i));
      if (f && f.type === "button" && f.display === display.visible && !/^Print_/.test(f.name)) {
        f.display = display.noPrint;
      }
    }
  } catch (e) {}
}).call(this);

/* @name     FS_ViewerWarning
   @title    Non-Adobe viewer warning
   @category On open
   @order    20
   @description Lets a visible warning ("Please open this form in Adobe Acrobat Reader") show only in viewers that can't run the form's scripts. Adobe viewers run this script and hide the warning on open; browsers and preview apps never do.
   @usage    Add a read-only text field named FS_ViewerWarning (or several: FS_ViewerWarning.1, FS_ViewerWarning.2 ...) set to Visible, containing your message. This script hides it whenever the form opens in a viewer that runs JavaScript.
*/
(function () {
  try {
    var f = this.getField("FS_ViewerWarning");
    if (f) f.display = display.hidden;
  } catch (e) {}
}).call(this);

/* @name     FS_FirstPage
   @title    Always open at page 1
   @category On open
   @order    30
   @description Opens the form at the first page, even if someone saved it while looking at page 4. Runs automatically.
   @usage    Runs automatically when the form opens.
*/
(function () {
  try {
    this.pageNum = 0;
  } catch (e) {}
}).call(this);