Forms with Crayons v3

What we'll learn today

Using crayons library to build user interfaces that fit the Freshworks Design System
Using crayons to listen to UI events
Using crayons to update properties or customize CSS rules of specific components programmatically.

What we'll need

A modern web browser like Google Chrome, Firefox, Edge, or Safari
A text editor
Basic knowledge of HTML, CSS, and Javascript
Crayons Documentation

What we'll build

We will build a static web page to focus on using Crayons components to create sample forms. We will also look into how we can change HTML attributes and customize CSS rules of components.

Prerequisite Knowledge

Read the App Introductory Guide.
How to use simple Javascript libraries/frameworks.
Basic concepts of CSS Flexbox.

Get Sample Code Ready

git clone https://github.com/freshworks-developers/forms-with-crayons-v3.git

Alternatively,

Download the Zip file

Verify

Open Terminal.
Run npx http-server command in the current cloned directory.
The current directory will be served on port :8080
Open the web browser on suggested port on localhost
You should see: "Let's learn Crayons v3" text.

Crayons is a frontend library. So relevant libraries has to be include in the app's web pages.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="stylesheet" href="https://unpkg.com/@freshworks/crayons@v3/css/crayons-min.css">
  <link rel="stylesheet" href="./styles/index.css">
  <title>A Crayons Sample - Web</title>
</head>
<body>
  Let's start learning Crayons v3
</body>
<script async type="module" src="https://unpkg.com/@freshworks/crayons@v3/dist/crayons/crayons.esm.js">
</script>
<script async nomodule src="https://unpkg.com/@freshworks/crayons@v3/dist/crayons/crayons.js">
</script>
</html>

Notice the script tags at the bottom. They bring crayons library for your web application and hence allows usage of web components. The async attribute loads library independently. See async vs defer.
The stylesheets included in the head allows your components to use classes in HTML components to layout. See CSS Utils.

You would see the same page nothing changed.

As confirmation you will see the network tab of the browser developer tools loads the crayons libraries as part of network requests.

We are going to construct around 10 crayons components to build a registration page for teenagers to register themselves a character in the Marvel Universe. It should be a three pane layout with one horizontal strip on the top.

Crayons Components

CSS Utilities we will use

Each Component in the crayons library comes with

Events
Properties
Methods
Custom CSS Properties

Let's look at each of it closely by understanding following code snippet.

Open JSitor to interact with components easily

<body>

<!-- Normal -->
<fw-button color="secondary"> Let's start learning Crayons v3 </fw-button> </br><p></p>
<!-- End -->

<!-- CSS Custom Properties -->
<fw-button
color="secondary"
style="--fw-button-label-vertical-padding: 5rem"
>
  Let's start learning Crayons v3
  </fw-button> </br>
<p></p>
<!-- End -->

<!-- Properties -->
<fw-button color="danger" show-caret-icon="true" size="normal" type="button" disabled="true">
	Let's start learning Crayons v3
</fw-button> </br>
<p></p>
<!-- End -->

<!-- Events -->
<fw-button color="secondary" id="btn"> Let's start learning Crayons v3 </fw-button> </br>
<script>
	let button = document.querySelector('#btn');
  button.addEventListener('fwClick', function log(e){
    console.log('Button is Clicked');
  })
</script>
<p></p>
<!-- End -->

<!-- Methods -->
<script>
focusMethod = function setFocus() {
document.getElementById("myTextField").setFocus();
}
  </script>
<fw-input type="text" id="myTextField" value="Text field."></fw-input>

<fw-button color="secondary" onclick="focusMethod()">Click me to focus on the text field!</fw-button>
<!-- End -->
</body>

Change the values associated with each to get idea about how it impacts a component's behaviour.

CSS Custom Properties — They help in customizing each crayons components in it's own individual ways. The button's padding has increased to 5 rem.

Properties — Attributes are the characteristics of an component at the Author time. While the properties can be modified by Javascript at runtime. In this case, Button's color, size, is disabled, etc.

Events — The components will emit them as they occur to Javascript. Author can write code that executes when the events occur. In this case, we simply log to the console whenever user clicks the button.

Methods — These are mini actions provided along the components. You can use javascript to simply invoke them. In this case, we set the focus to text field when user clicks the button.

If you took some time to play around with the components in the previous step, you know opening up the right documentation and simply use the documentation.

In this section, we will layout all set of components as envisioned in the "The Picture" and use CSS Utils effectively with having to write as less CSS as possible.

Let's rewrite the body of HTML with following:

<body>
  <!-- Top Notification Horizantal -->
  <fw-inline-message open type="info" class="fw-p-4">Registration is open for anyone aged less than 18
  </fw-inline-message>

  <!-- A Horizantal Strip -->
  <section class="strip-one fw-flex fw-flex-row fw-justify-between">
    <fw-toast id="type_toast"></fw-toast>

    <h1 class="fw-p-16 fw-type-h1">Join Marvel Universe
      <fw-label value="Registration Form"> </fw-label>
    </h1>

    <fw-menu class="fw-flex-grow-0" style="--fw-menu-max-width:300px; width: 20rem;">
      <fw-menu-item>
        <fw-icon name="at-the-rate"></fw-icon>
        Login
      </fw-menu-item>
      <fw-menu-item>
        <fw-icon name="close"></fw-icon>
        Signup
      </fw-menu-item>
    </fw-menu>
  </section>

  <!-- Three vertical columns to place components -->
  <div class="fw-flex fw-flex-row fw-justify-between">
    <section class="fw-flex fw-flex-column fw-p-16 fw-m-28 " style="width:30rem;">
      <fw-input label="Super Hero Name" value="Ironman"></fw-input>
      <fw-file-uploader id="file-uploader-1" muliple="false" class="fw-p-8" text="Upload SuperHero Profile">
      </fw-file-uploader>
      <fw-button file-uploader-id="file-uploader-1" color="link">Upload file</fw-button>
      <fw-pill color="blue" class="fw-m-8">
        <fw-icon name="info" slot="icon"></fw-icon>
        Personal Information
      </fw-pill>
      <fw-textarea cols=40 rows=5 maxlength=75 minlength=5 label="Address"
        warning-text="Do not enter your temporary address" state="warning" placeholder="Enter your permanent address"
        required>
      </fw-textarea>

    </section>

    <section class="fw-flex fw-flex-column fw-p-16 fw-m-28" style="width:30rem;">
      <h3 class="fw-type-h3">Order the following with highest super power</h3>
      <fw-pill color="green">
        <fw-icon name="add-contact" slot="icon"></fw-icon>
        New
      </fw-pill>
      <fw-drag-container class="drag-container" id="defaultSort">
        <fw-drag-item>Ironman</fw-drag-item>
        <fw-drag-item>Captain America</fw-drag-item>
        <fw-drag-item>Black Widow</fw-drag-item>
        <fw-drag-item>Thor</fw-drag-item>
        <fw-drag-item>Hulk</fw-drag-item>
        <fw-drag-item>Spiderman</fw-drag-item>
        <fw-drag-item>Thanos<fw-icon slot="suffix" name="bulb"></fw-icon>
        </fw-drag-item>
      </fw-drag-container>
      <fw-tooltip content="This will submit your application to Marvel Authors!">
        <fw-button
          onclick="document.querySelector('#type_toast').trigger({type:'success', content: 'Application to become Avenger is successfully submitted!'})">
          Apply Now!
        </fw-button>
      </fw-tooltip>
    </section>

    <section class="fw-flex fw-flex-column" style="width:30rem;">
      <fw-accordion expanded class="fw-mr-16 fw-type-base">
        <fw-accordion-title>MCU's Avengers</fw-accordion-title>
        <fw-accordion-body>
          The Avengers are a fictional team of superheroes and the protagonists of the Marvel Cinematic Universe (MCU)
          media franchise, based on the Marvel Comics team of the same name created by Stan Lee and Jack Kirby in 1963.
          Founded by S.H.I.E.L.D. Director Nick Fury, the team is a United States-based organization composed primarily
          of superpowered and gifted individuals, described as "Earth's Mightiest Heroes", who are committed to the
          world's
          protection from
          a variety of threats. The Avengers are depicted as operating in the state of New York; originally operating
          from the
          Avengers Tower in Midtown Manhattan and subsequently from the Avengers Compound in Upstate New York.

          The concept of the Avengers was teased in the post-credits scene of Iron Man (2008), the first MCU film, by
          Nick Fury as an initiative planned by him. The concept was further explored in Iron Man 2 (2010), with the
          introduction of
          Natasha Romanoff. The team was eventually established in the crossover-style film The Avengers (2012), which,
          followed
          by Avengers: Age of Ultron (2015), Avengers: Infinity War (2018) and Avengers: Endgame (2019), established a
          series of four films that headlined the MCU and became the sixth highest-grossing film series of all time,
          with the MCU
          franchise overall ranking first. Arranged as an ensemble of core MCU characters such as Iron Man, Captain
          America and
          Thor, they are central to the MCU's Infinity Saga and have been acclaimed as an important part of the
          franchise.
        </fw-accordion-body>
      </fw-accordion>
    </section>
  </div>
</body>

Components aside, pay closer attention to the classes used at each section, div and component.
We managed to control the font style and typography using fw-type-xx classes. For example, the accordion inherits it's font characteristics from Crayons library but not from the web browser. See Typography
The classes fw-flex fw-flex-row and so forth work synonymous with CSS Flexbox. For instance, both "Login, Register" Menu and "Registration form" title actually stay on the same row to give users an appearance as a header. See Layout document in Crayons Docs.
Similarly, fw-pt-XX or fw-mX-XX can be used to adjust padding and spacing. For example, "Join Marvel Universe" heading actually uses these classes. See Spacing.

Kudos for completing this tutorial

We have covered a comprehensive map of the crayons library. JS library-like crayons is a bundle of web components so that you can use them complementary with your favorite frameworks in any of your projects.

See the final source code of the app

Always have the documentation handy!