Skip to content

sc-markdown

1 Purpose

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, Markdown is two things: (1) a plain text formatting syntax; and (2) a software tool that converts the plain text formatting to HTML. 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. Daring Fireball Markdown Reference
  2. Wordpress Markdown Quick Reference
  3. Github Markdown Cheatsheet

sc-markdown places a markdown field on a form and can be used in either edit or view mode.

Edit mode is for the writing or editing of markdown text. On save, the markdown text will be saved to the database as entered with new line characters (i.e. \n) automatically inserted.

View mode converts the markdown text for html display.

The Formbird User Guide documents, including this document, were created using a sc-markdown field.

The sc-markdown definition provides fields for setting the properties the markdown field and is fully described below.

 

2 Definition

sc-markdown 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

Field Valid Values Description
componentName sc-markdown The component name.
Example: "componentName": "sc-markdown"

2.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case Defines the name of the markdown field in the document and database.
Example: "name": "testScMarkdown"

2.3 Optional Customizable Fields

Field Valid Values Description
defaultValue Any Markdown text In view mode, the markdown field converts the Markdown text for display, interpreting any imbedded new line characters (i.e. \n) and markdown formatting syntax.
Example: "defaultValue": "#A Markdown Heading\nSome body text\n\n1. A markdown number list - Item 1 \n2. A markdown number list - Item 2\n"
Default value. The markdown field displays no value.
disableSave true Editing the markdown field does not trigger the Save icon to flash.
Exiting the form without saving the edited markdown field does not trigger a warning message to display.
Example: "disableSave": true
false Default value. Editing the markdown field does trigger the Save icon to flash.
Exiting the form without saving the edited markdown field does trigger a warning message to display.
enabled false The markdown field's label and value are visible but its Edit/View icon is hidden.
The markdown field's value cannot be edited.
Example: "enabled": false
true Default value. The markdown field's label, value and its Edit/View icon are all visible.
The markdown field's value can be edited.
fullWidth true The markdown field displays full width on the form. In most situations the markdown field is defined as full width so that the resulting html is displayed full width.
Example: "fullWidth": true
false Default value. The markdown field does not display full width on the form.
label Any value Defines the name of the markdown field on the form i.e. the field label.
Example: "label": "Test sc-markdown"
'name' field value Defaults to the value defined for the 'name' field, with the first letter displayed in upper case and any upper case letters displayed in lower case prefixed with an underscore.
Example: "Test_sc_markdown" is the default value if the "name" field value was "testScMarkdown".
mandatory true The markdown field displays as mandatory (i.e. label in red text with an asterisk) and the text 'This field is mandatory' displays below the markdown field.
Saving without a value, a message prompts the user to enter a value for the field.
Example: "mandatory": true
false Default value. The 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 field.
visible false The markdown field is not visible on the form.
Example: "visible": false
true Default value. The markdown field is visible on the form.

 

3 Typical sc-markdown Definition

Below is a 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": "Enter documentation here",
    "name": "testScMarkdown",
    "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"
    "mandatory": true,
    "disableSave":true,
    "enabled":false,
    "visible":false

 

4 Examples

Example 1

sc-markdown with only its required system fields and required customizable fields defined.

        {
            "componentName": "sc-markdown",
            "name": "testScMarkdown",
            "label": " "
        {

Note: In the above definition, the label field value is one space. Hence the markdown field label on the form will display a space, not its default value "Test _ sc _ markdown".

Resulting field on the form:

alt text

Example 2

sc-mark-down with its required fields two optional fields ("defaultValue", "fullWidth") defined.

        {
            "componentName": "sc-markdown",
            "label": "Enter documentation here",
            "name": "testScMarkdown",
            "fullWidth": true,
            "defaultValue": "#A Level 1 Heading\nSome body text\n\n1. numbered list item 1\n2. numbered list item 2\n"
        }

Note: The defaultValue field value can be formatted using markdown syntax and new line characters (i.e. \n).

Resulting field on the form:

alt text