sc-markdown

This document is a user guide for the Formbird "sc-markdown" component release version 7.1.40.

1 Purpose

The "sc-markdown" component provides the ability to write and edit Markdown.

Markdown is an easy-to-use markup language that is used to add formatting elements (e.g. headings, bulleted lists, numbered lists, bold text, italic text, URLs) to plain text without the use of HTML tags. You can also use it to add images, videos and links.

Markdown allows you to write easy-to-read, easy-to-write Markdown-formatted plain text, then convert it to structurally valid XHTML (or HTML) for display.

Thus, Markdown is two things:

1. A plain text formatting language; and
2. A software tool that converts the plain text formatting for HTML displaty.

The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

The links below provide details pertaining to Markdown basics and Markdown's formatting syntax.

1. Github Markdown Cheatsheet
2. Daring Fireball Markdown Reference
3. Wordpress Markdown Quick Reference

The "sc-markdown" component places a Markdown field on a form. A button allows the user to toggle the "sc-markdown" field between "Edit" mode and "Preview" mode.

In "Edit" mode (shown below):

1. The "sc-markdown" field allows the user to write or edit Markdown-formatted text (as shown below).

   

2. A drag handle (bottom right corner) allows the user to manually resize the height and width of the "sc-markdown" field.

3. Four formatting buttons (top right corner) provide quick access to four of the many Markdown-formatting options. Alternatively, these four and the many other Markdown-formatting options can be entered directly into the "sc-markdown" field using Markdown-formatting syntax.

4. Clicking the "Markdown is supported" button (bottom left corner) will open a Markdown quick reference guide (Github Markdown Cheatsheet).

5. Files such as image files can be inserted by pasting or dragging and dropping them into the "sc-markdown" field.

6. To preview the Markdown-formatted text as HTML display, click the "Preview" button (top right corner).

In "Preview" mode (shown below):

1. The"sc-markdown" field converts the Markdown-formatted text shown above for HTML display (shown below).

   

2. Clicking the Formbird.com link will open the web page at URL address https://www.formbird.com/.

3. To edit the HTML display, click the "Edit" button (top right corner) to toggle the "sc-markdown" field back to "Edit" mode, displaying the HTML as Markdown-formatted text.

Entering or editing a value (i.e. Markdown-formatted text) in a "sc-markdown" field will trigger the document "Save" button to display and flash . Clicking the flashing document "Save" button will save the "sc-markdown" field value to the document and database (see Example 1).

The Formbird "sc-markdown" component definition provides fields for setting the properties of a "sc-markdown" field on a form and is fully described below.

2 Definition

The Formbird "sc-markdown" component is defined by a set of name/value pair fields consisting of:

• Required system fields
• Required customizable fields
• Optional customizable fields

Note:

1. Default values for fields described in the tables below are shown in bold text.

2.1 Required System Fields

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

Field	Valid Values	Description
defaultValue	Markdown-formatted text	The Markdown-formatted text value to initially load in the "sc-markdown" field. Example: "defaultValue": "# A Markdown Level 1 Heading\nSome body text\n\n1. A markdown ordered list - Item 1\n2. A markdown ordered list - Item 2\n" Note: In "Preview" mode, the text string "\n" will be interpreted as a new line.
		Defaults to no value is initially loaded in the "sc-markdown" field.
disableSave	true	Changing the "sc-markdown" field value (i.e. by entering or editing Markdown-formatted text) does not trigger the document "Save" button to flash. Exiting the form without saving changes to the "sc-markdown" field value does not trigger a warning message to display. Note: Should the document "Save" button display and flash as a result of changing the value of another field on the form, then: In the Angular version of the "sc-markdown" component, clicking the flashing document "Save" button will not save the "sc-markdown" field value to the document. In the AngularJS version of the "sc-markdown" component, clicking the flashing document "Save" button will save the "sc-markdown" field value to the document. Example: "disableSave": true
	false	Default value. Changing the "sc-markdown" field value (i.e. entering or editing markdown-formatted text) does trigger the document "Save" button to flash . Exiting the form without saving changes to the "sc-markdown" field value does trigger a warning message to display. Note: In both the Angular and AngularJS versions of the "sc-markdown" component, clicking the document "Save" button will save the "sc-markdown" field value to the document.
enabled	false	The "sc-markdown" field value cannot be entered or edited. A "Stop" icon displays on mouseover of all areas of the "sc-markdown" field. The "sc-markdown" field opens in "Preview" mode. The "sc-markdown" field is greyed out. ALL the "sc-markdown" field buttons are hidden. Example: "enabled": false
	true	Default value. The "sc-markdown" field value can be entered or edited. A "Stop" icon does not display on mouseover of the "sc-markdown" field. The "sc-markdown" field opens in "Preview" mode. The "sc-markdown" field is not greyed out. ALL "sc-markdown" field buttons are not hidden.
fullWidth	true	The "sc-markdown" field displays full width on the form. In most situations the "sc-markdown" field is defined as full width so that the resulting HTML is displayed full width. Example: "fullWidth": true
	false	Default value. The "sc-markdown" field does not display full width on the form.
hideLabel	true	Works in conjuction with the "label"field. If the "sc-markdown" field has no value, then: In "Edit" mode, the field label will display top and left justified inside the field. In "Preview" mode, the field label is hidden. If the "sc-markdown" field has a value, then in both "Edit" and "Prevew" mode, the field label is hidden. Example: "hideLabel": true
	false	Default value. In both "Edit" and "Preview" mode, the field label will display left justified immediately above the "sc-markdown" field.
label	Any value	Defines the name of the "sc-markdown" field on the form i.e. the field label. Works in conjuction with the "hideLabel"field. Example: "label": "sc-markdown Typical Defn"
		Defaults to no field label is displayed.
mandatory	true	The "sc-markdown" field displays as mandatory (i.e. label in red text suffixed with an asterisk). Saving without a value, a message prompts the user to enter a value for the "sc-markdown" field. Example: "mandatory": true
	false	Default value. The "sc-markdown" field displays as optional (i.e. label in black text). Saving without a value, a message does not prompt the user to enter a value for the "sc-markdown" field..
visible	false	The "sc-markdown" field is not visible on the form. Example: "visible": false
	true	Default value. The "sc-markdown" field is visible on the form.

3 Typical Definition

Below is a typical "sc-markdown" component definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-markdown",
    "label": "sc-markdown Typical Defn",
    "name": "scMarkdownTypicalDefinition",
    "fullWidth": true
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

    "defaultValue": "#A Level 1 Heading\nSome body text\n\n1. numbered list item 1\n2. numbered list item 2\n"
    "disableSave":true,
    "enabled":false,
    "hideLabel": true,
    "mandatory": true,
    "visible":false  

4 Examples

Example 1

The typical "sc-markdown" definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-markdown",
    "label": "sc-markdown Typical Defn",
    "name": "scMarkdownTypicalDefinition",
    "fullWidth": true
}

Resulting "sc-markdown" field on the form:

The "sc-markdown" field displays in "Edit" mode allowing the user to enter a value.

Clicking the "Preview" button toggles the "sc-markdown" field from "Edit" mode to "Preview" mode.

Resulting "sc-markdown" field on the form:

Toggling the "sc-markdown" field back to "Edit" mode, allows the user to enter Markdown-formatted text in the "sc-markdown" field.

Resulting "sc-markdown" field on the form after entering Markdown-formatted text:

The markdown-formatted text shown above includes:

• A level 1 heading
• An unordered list
• A level 2 heading
• An ordered list
• Some Bold and some italic text
• A table with column headings and column data
• A hyperlink to the Formbird web site

Clicking the "Preview" button toggles the "sc-markdown" field from "Edit" mode to "Preview" mode and converts the Markdown-formatted text for HTML display.

Resulting "sc-markdown" field on the form:

Clicking the flashing document "Save" button will save the entered Markdown-formatted text to the document.

Resulting "sc-markdown"field in the document and database after saving the document:

"scMarkdownTypicalDefinition": "# A Level 1 Heading\n* Item 1 of an unordered list\n* Item 2 of an unordered list\n## A Level 2 Heading\n1. Item 1 of an ordered list\n1. Item 2 of an ordered list\n\n**Bold text** and *italic text*\n\n| Column 1 Heading | Column 2 Heading |\n|---|---|\n| row 1 column 1 data | row 1 column 2 data |\n| row 2 column 1 data | row 2 column 2 data |\n\n[Formbird.com](https://www.formbird.com/)"

Note:

On save, each new line is automatically prefixed with \n.