Support

Guides

Technical

Custom Forms

Overview

Custom forms can be created using SameGoal's XML dialect. In a single XML file, a form author can specify:

  • Form look and layout
  • Form fields and user data collection
  • How the form will be broken up across tabs in the user interface, including tab names and abbreviations
  • Headers and footers, including automatic page numbering
  • Form fields which should appear in document lists (snippet fields)
  • How information can copy between the fields in a form or from one form to another

This single XML file is then used by the SameGoal rendering engine to:

  • Generate on-screen user interface
  • Generate printed copy PDF
  • Automatically allocate backend storage for all fields
  • Allow SQL-based reporting of all data fields in the form

Key benefits include:

  • Ability to rapidly create custom forms with only XML dialect knowledge.
  • All forms are on the same platform. While forms differ, core collaboration, navigation, features and functionality are the same across forms. Low learning curve for staff.
  • XML dialect automatically generates complex user interfaces containing HTML, JS, CSS which empower fast data entry.
  • Generated user interface is cross-browser compatible. Forms rendered on the SameGoal platform can be authored in all recent versions of modern web browsers.
  • All the plumbing of the SameGoal platform. This includes secure hosting, automated backups, a user permissions model, integration, and much more.
  • Cross browser and cross platform support without specialized knowledge, testing or bug fixing.

XML Dialect Specification

Custom forms are created using a proprietary SameGoal XML dialect, described in the SameGoal XML schema.


Main Elements

Main elements (form, section, subsection) are used to create the main structure of each form.

form

Definition: A block-level element. First node of xml form.

Usage: All forms must be enclosed in a form element.

Attributes:

  • name (required) [default: ""]: string. The name of the form. This cannot change after uploading form. Used as a key for the form in the database.
  • abbr [default: ""]: string. An abbreviation of the form name. Used on list pages throughout the program to shorten the form name.
  • tips [default: ""]: string. A url to tips available for this form.
  • alt_view_for [default: ""]: string. Form name of related form. Only used when the form is an alternate view (eg an "at a glance" page) for another form (eg "Form A").
  • font_size [default: "medium"]: font_size enum value. Font size of form.
  • default_layout [default: "portrait"]: default_layout enum value. Default page layout for printing.
  • page_size [default: "letter"]: page_size enum value. Page size.
  • max_incomplete [default: "1"]: max_incomplete enum value. Maximum number of documents of this form type which can be incomplete for a given student at a time.

section

Definition: A block-level element. Child of a form element.

Usage: A form is broken into one or more sections. A typical form will have one header section, one footer section, and N body sections (denoted with the "part" attribute). Header and footer sections will not be visible onscreen; only visible when the form is printed. Each body section will generate as a separate tab in the user interface when the form generates. A form with a cover page and four sections would likely use five body sections.

Attributes:

  • name [default: ""]: string. The name of the section. If section is a body section, this name will appear in the tool tip on hover of the section tab in the user interface. If the section is repeated, name will appear on the "add" button to add a repeated section.
  • abbr [default: ""]: string. An abbreviation of the section name. If section is a body section, this abbreviation will appear on the section tab in the user interface.
  • page_break [default: "soft"]: page_break enum value. How to perform a page break after the section. "Soft" page breaking attempts to keep sections together rather than splitting them across pages.
  • media [default: "all"]: media enum value. Whether the content of the section should be visible on the screen, when printed, or in all media contexts.
  • part [default: "body"]: part enum value. Whether the section is a header, footer or body section.
  • repeated [default: not set]: repeated enum value. Whether the section repeats. If this is set, also use the name attribute to set the text on the "add" button.
  • tips [default: ""]: string. A url to tips available for this section.

subsection

Definition: A block-level element. Child of a section element.

Usage: A section is broken into one or more subsections. While you cannot currently see subsections directly in the user interface, future work may expose functionality to the user to view and complete each subsection at a time. Additionally, subsections are used during print rendering to group nested information together, so it is helpful to group short amounts of related information together in each subsection.

Attributes:

  • name [default: ""]: string. The name of the subsection. If subsection is repeated, name will appear on "add" button to add repeated subsection.
  • abbr [default: ""]: string. An abbreviation of the subsection name.
  • page_break [default: "soft"]: page_break enum value. How to perform a page break after the subsection. "Soft" page breaking attempts to keep subsections together rather than splitting them across pages.
  • media [default: "all"]: media enum value. Whether the content of the section should be visible on the screen, when printed, or in all media contexts.
  • repeated [default: not set]: repeated enum value. Whether the section repeats. If this is set, also use the name attribute to set the text on the "add" button.

Input Elements

Imput elements (date, text_input, rte, options_list, option) are the only elements which can be used to capture information from the user.

date

Definition: A inline element for a user to enter a date. Generates corresponding calendar in user interface for fast entry.

Usage: Use to capture a date field.

Attributes:

  • id [default: ""]: string. Used for advanced work; ignore.
  • description [default: ""]: string. Field description (think label for the field).
  • orientation [default: "horizontal"]: orientation enum value. Whether the description should be horizontally or vertically aligned with the field.
  • desc_fixed_width [default: not set]: A hard-coded width for the description, in pixels.
  • snippet [default: ""]: string. If this field should appear in the list pages for this document, give it a priority in the list (eg "1", "2", or "3"). Snippet values will appear in ascending order from left to right in the user interface as long as there is room in the document row. Also set label attribute if using snippet attribute.
  • label [default: ""]: string. The label for the snippet value on document list pages. Only use with snippet attribute.

text_input

Definition: A inline element for a user to enter a small amount of text (single-line/several words). Generates corresponding organization bank, user bank, and autocomplete user interface.

Usage: Use to capture a field which should be several words/single-line. Does not allow rich text editing.

Attributes:

  • id [default: ""]: string. Used for advanced work; ignore.
  • description [default: ""]: string. Field description (think label for the field).
  • orientation [default: "horizontal"]: orientation enum value. Whether the description should be horizontally or vertically aligned with the field.
  • desc_fixed_width [default: not set]: A hard-coded width for the description, in pixels.
  • snippet [default: ""]: string. If this field should appear in the list pages for this document, give it a priority in the list (eg "1", "2", or "3"). Snippet values will appear in ascending order from left to right in the user interface as long as there is room in the document row. Also set label attribute if using snippet attribute.
  • label [default: ""]: string. The label for the snippet value on document list pages. Only use with snippet attribute.

rte

Definition: A block-level element for a user to enter unlimited text. Generates corresponding organization bank and user bank user interface.

Usage: Use to capture a field which may require multiple lines of text. Allows for rich text editing within the field. Amount of input in field is unlimited.

Attributes:

  • id [default: ""]: string. Used for advanced work; ignore.
  • description [default: ""]: string. Field description (think label for the field).
  • orientation [default: "vertical"]: orientation enum value. Whether the description should be horizontally or vertically aligned with the field.
  • desc_fixed_width [default: not set]: A hard-coded width for the description, in pixels.
  • height [default: "40"]: string. Default minimum height (in pixels) of the rte field in PDF.
  • snippet [default: ""]: string. If this field should appear in the list pages for this document, give it a priority in the list (eg "1", "2", or "3"). Snippet values will appear in ascending order from left to right in the user interface as long as there is room in the document row. Also set label attribute if using snippet attribute.
  • label [default: ""]: string. The label for the snippet value on document list pages. Only use with snippet attribute.

options_list

Definition: A block-level element for a user to enter checkbox, radio or select values.

Usage: Use to create a checkbox, radio or select field (set by "option_type").

Attributes:

  • id [default: ""]: string. Used for advanced work; ignore.
  • description [default: ""]: string. Field description (think label for the field).
  • orientation [default: "horizontal"]: orientation enum value. Whether the description should be horizontally or vertically aligned with the field.
  • display [default: "block"]: display enum value. Whether to show the options_list as block or inline.
  • desc_fixed_width [default: not set]: A hard-coded width for the description, in pixels.
  • option_type (required): option_type enum value. The type of options list (checkbox, radio or select).
  • columns [default: "1"]: string. The number of columns this options list should be divided into. Currently not supported (work underway).
  • layout [default: "vertical"]: layout enum value. Whether checkboxes and radios should be vertically or horizontally listed. A no-op for selects.
  • snippet [default: ""]: string. If this field should appear in the list pages for this document, give it a priority in the list (eg "1", "2", or "3"). Snippet values will appear in ascending order from left to right in the user interface as long as there is room in the document row. Also set label attribute if using snippet attribute.
  • label [default: ""]: string. The label for the snippet value on document list pages. Only use with snippet attribute.

option

Definition: An element used to describe each option in an options_list.

Usage: Used once for each option in an options_list (eg one radio button, or one checkbox, in a list).

Attributes:

  • value (required): string. The value stored in the database for this option. Cannot change once form is in use, or may cause data loss.
  • description [default: ""]: string. Option description (think label for the option).

Text Elements

Text elements (b, i, u, sup) format nested text.

b

Definition: An inline element used to bold nested text.

Usage: Use to bold text. Same effect as HTML b tag.

Attributes: None.

i

Definition: An inline element used to italicize nested text.

Usage: Use to bold text. Same effect as HTML i tag.

Attributes: None.

u

Definition: An inline element used to underline nested text.

Usage: Use to underline text. Same effect as HTML u tag.

Attributes: None.

sup

Definition: An inline element used to superscript nested text.

Usage: Use to superscript text. Same effect as HTML sup tag.

Attributes: None.


Misc Elements

Miscellaneous elements (br, hr, page_number, img, items_list, item) are used for line breaks, horizontal rules, automatic page numbering, lists, and inlining images.

br

Definition: An inline element used to line break.

Usage: Use to line break. Same effect as HTML br tag. If used after an inline element, next element will be on next line. If used after block-level element, next element will be after a one-line skip.

Attributes: None.

hr

Definition: A block-level element used to provide a horizontal rule.

Usage: Use as a horizontal rule. Same effect as HTML hr tag.

Attributes: None.

page_number

Definition: An inline element used to provide automatic page numbering.

Usage: Use in a header or footer section to add automatic page numbering to your printed document.

Attributes: None.

img

Definition: An inline element used to inline an image into the form.

Usage: Use to inline an image from any url into the form.

Attributes:

  • title [default: ""]: string. Title for the image (displayed on hover). Important for screen reader accessibility.
  • source [default: ""]: string. Url of image.

items_list

Definition: A block-level element used for static lists of items.

Usage: Use for bulleted, numbered, etc. lists of static information.

item

Definition: A block-level element used for each list item.

Usage: Used once for each item in an items_list (eg each bullet point).

Attributes: None.


Layout Elements

Layout elements (container, table, tr, td) are used to assist with layout of the page.

container

Definition: A block-level (by default) element which encloses information.

Usage: Often used as a formatted container of information (eg to enclose text for a heading that should be bigger than other parts of the form, with a background color). Good for supplying backgrounds and font face/color/size changes to nested text. Also, can be used to enclose repeated information.

Attributes:

  • display [default: "block"]: display enum value. Whether to show the container as block or inline.
  • valign [default: "bottom"]: valign enum value. How to align enclosed text vertically.
  • border_style [default: "solid"]: border_style enum value. Border style.
  • border_side [default: "none"]: border_side enum value. Border side to display border on. If border attributes are set, but border_side is "none", border attributes will apply to no sides.
  • border_width [default: "thin"]: border_width enum value. Border width.
  • border_color [default: "black"]: color enum value. Border color.
  • padding_side [default: "all"]: side enum value. Side to apply padding to.
  • padding_width [default: "small"]: padding_width enum value. Padding width to add to each container side. If padding_width is set, but padding_side is "none", padding width will apply to no sides.
  • halign [default: "left"]: halign enum value. How to horizontally align enclosed text.
  • background_color [default: "transparent"]: color enum value. Background color.
  • font_face [default: "arial"]: font_face enum value. Font face.
  • font_size [default: "medium"]: font_size enum value. Font size.
  • font_color [default: "black"]: color enum value. Font color.
  • page_break [default: "soft"]: page_break enum value. How to perform a page break after the container. "Soft" page breaking attempts to keep containers together rather than splitting them across pages.
  • repeated [default: not set]: repeated enum value. Whether the container repeats. If this is set, also use the name attribute to set the text on the "add" button.
  • name [default: ""]: string. The name of the container. If container is repeated, name will appear on "add" button to add repeated container.

table

Definition: A block-level element. Table. Similar to HTML table tag.

Usage: Use sparingly, when table is needed in form or for advanced page layout.

Attributes:

  • border_style [default: "solid"]: border_style enum value. Border style.
  • border_side [default: "none"]: border_side enum value. Border side to display border on. If border attributes are set, but border_side is "none", border attributes will apply to no sides.
  • border_width [default: "thin"]: border_width enum value. Border width.
  • border_color [default: "black"]: color enum value. Border color.
  • background_color [default: "transparent"]: color enum value. Background color.
  • percent_width [default: not set]: string. Table width. Use a value 0 through 100.
  • fixed_width [default: not set]: string. Table fixed width in pixels. Use sparingly.
  • cell_borders [default: "no"]: cell_borders enum value. Whether to apply cell borders to all cells of table.
  • cell_padding [default: "yes"]: cell_padding enum value. Whether to apply cell padding to all cells of table.

tr

Definition: Table row. Child of table element. Similar to HTML tr tag.

Usage: Each table requires at least one table row.

Attributes:

  • border_style [default: "solid"]: border_style enum value. Border style.
  • border_side [default: "none"]: border_side enum value. Border side to display border on. If border attributes are set, but border_side is "none", border attributes will apply to no sides.
  • border_width [default: "thin"]: border_width enum value. Border width.
  • border_color [default: "black"]: color enum value. Border color.
  • background_color [default: "transparent"]: color enum value. Background color.

td

Definition: Table cell. Child of table row element. Similar to HTML td tag.

Usage: Each table row requires at least one table cell.

Attributes:

  • valign [default: "bottom"]: valign enum value. How to align enclosed text vertically.
  • border_style [default: "solid"]: border_style enum value. Border style.
  • border_side [default: "none"]: border_side enum value. Border side to display border on. If border attributes are set, but border_side is "none", border attributes will apply to no sides.
  • border_width [default: "thin"]: border_width enum value. Border width.
  • border_color [default: "black"]: color enum value. Border color.
  • padding_side [default: "all"]: side enum value. Side to apply padding to.
  • padding_width [default: "small"]: padding_width enum value. Padding width to add to each container side. If padding_width is set, but padding_side is "none", padding width will apply to no sides.
  • halign [default: "left"]: halign enum value. How to horizontally align enclosed text.
  • background_color [default: "transparent"]: color enum value. Background color.
  • percent_width [default: not set]: string. Table cell width. Use a value 0 through 100.
  • fixed_width [default: not set]: string. Table cell fixed width in pixels. Use sparingly.
  • colspan [default: "1"]: string.
  • rowspan [default: "1"]: string.

Copy Elements

Copy elements (copy, copy_path) are used to facilitate automatic copying from other forms.

copy

Definition: Block-level copy element. If "text" attribute is set, displays as a button. If not, copy element not visible.

Usage: Use "text" attribute when creating a button to "Update" information in a form which a user should click as needed. When wishing to auto-copy information at form creation time, do not supply the "text" attribute and instead set "auto_copy" attribute to "true".

In many cases, it is helpful to both auto-copy and also give the option to click to update. When this is true, use two copy elements, each with the same copy_paths but differing copy element attributes.

Attributes:

  • text [default: not set]: string. If supplied, text displays on button in user interface.
  • auto_copy [default: "true"]: auto_copy enum. Whether to auto-copy, overwrite the destination's value each time, or to perform an asymmetric copy (advanced).
  • name [default: not set]: Deprecated; ignore.
  • inside_repeated_id [default: ""]: string. Used for advanced asymmetric copy only.

copy_path

Definition: Copy path element.

Usage: Represents one copy path to execute in a copy element.

Attributes:

  • from [default: ""]: string. Key to copy from, from form specified by "form_id" attribute.
  • to [default: ""]: string. Key to copy value to in this form.
  • form_id [default: ""]: string. Value of "form_name" attribute for form we are copying from.
  • insert [default: not set]: insert value enum. Whether to insert the copied value at the end of the field (rather than replacing the contents of the field altogether, which is the default behavior).

Attribute Enums

  • page_size: { "letter" | "envelope" }
  • default_layout: { "portrait" | "landscape" }
  • repeated: { "true" }
  • update_only: { "true" }
  • media: { "all" | "screen" | "print" }
  • part: { "body" | "header" | "footer" }
  • page_break: { "soft" | "hard" | "none" }
  • display: { "block" | "inline" }
  • list_type: { "bullet" | "number" | "lower_alpha" | "upper_alpha" | "lower_roman" | "upper_roman" }
  • halign: { "left" | "center" | "right" }
  • valign: { "top" | "middle" | "bottom" }
  • font_size: { "xsmall" | "small" | "medium" | "large" | "xlarge" }
  • input_size: { "xsmall" | "small" | "medium" | "large" | "xlarge" }
  • font_face: { "arial" | "times" | "arial_black" | "arial_narrow" | "comic_sans" | "courier" | "garamond" | "georgia" | "tahoma" | "trebuchet" | "verdana" }
  • border_width: { "none" | "thin" | "medium" | "thick" }
  • padding_width: { "none" | "small" | "medium" | "large" | "xlarge" }
  • side: { "none" | "all" | "top" | "right" | "bottom" | "left" }
  • border_style: { "solid" | "dashed" }
  • color: { "transparent" | "black" | "gray" | "white" | "blue" | "red" }
  • orientation: { "horizontal" | "vertical" | "vertical_inverted" }
  • option_type: { "checkbox" | "radio" | "select" }
  • cell_borders: { "no" | "yes" }
  • cell_padding: { "no" | "yes" }
  • auto_copy: { "true" | "overwrite_destination" | "asymmetric"}
  • insert: { "true" }
  • incomplete_count: { "1" | "unlimited" }


0.04 seconds - © 2017 SameGoal, Inc.