Click to show TOC

TryITJs Tutorials

©Nurul Choudhury - 2020

Introduction

This is an introduction to TryITJs, a tool to create tutorials to Javascript libraries. It used a simple markup language to create these tutorials with runable code examples that the user can edit and experiment. The editing is non-destructive and you can go back to the original state by refreshing the browser. To make life easier for someone who wants to keep the edits and experiments and come back to it later, you can save your changes by clicking on the the save button . When you save some changes, these are ctored locally in your browser local storage.

To learn more tou can go to Why TryITjs

Directory Structure

Click on the image above to see a more detailed view

What is a .try file

Top level files

Top level files are simply text file with the extension .try. The first line on a top level file must start the !head. The fillowing section is an example of a very simple try file.

Basic Example

The code below is the basic.try file for the example

!head
  ~~lt%%title~~gt%%First Tryit~~lt%%/title~~gt%%
  @@include tools/head.try

!md 
    # Introduction
    This a very simple **TryITjs** file. It has only one page.

    ## Code example

    This is a simple code example to create a javascript array and display it.

    Press the RUN button to execute the code (you can eddit the code and run again if you like)

!tryit
    var array = [ 'a String', 1 , { name: 'tryit'} ]; // array with a `string`, `number`, and an `object`
    array


!md
    **What just happened**, if you execute the code above it will display the array just created. 

    __Note: the last expression `array` is displayed.__

Two Page Example

In this example we show you how to create a multi page try file. The way to create a new page is to use '#' heading h1 to create a new page.

The following is the .try file used for this example

!head
  ~~lt%%title~~gt%%Sligltly More elaborate example~~lt%%/title~~gt%%
!md 
    # Introduction
    This is a slightly more elaborate example

    ## Code example

    This is a simple code example to create a javascript array and display it.

!tryit
    var array = [ 'a String', 1 , { name: 'tryit'} ]; // array with a `string`, `number`, and an `object`
    array


!md
    **What just happened**, if you execute the code above it will display the array just created. 

    _Note: the last expression `array` is displayed._

    ## Some simple notes

    * You can edit the example above and runit as may time as you want
    * The code changes its theme once you edit it to show you
    A variable created within a **!tryit** snippet  usin a ``let`` only exists in the snipped

!md
    # Another Page

    This is one more example in a new page. The is it my test.
!end




Page - 1




Modularizing a try file

Once you start creating a significant tutorial file it can start to become large and unwieldy. The tool that supports modularization is @@include file_name.try.

Try Fragments

This the file we are using to implement the page

!head
    ~~lt%%title~~gt%%Modular Tryit~~lt%%/title~~gt%%
    @@include tools/head.try

!md
    # Example of Modularizaion

    I am going to see how to modularize a try example into multiple files.

    While we are here we can demonstrate how to display data, amd show how to incorporate into a new file (in a sub directory __modular__)

    @@include modular/disp_data_simple.try

Internal file 1

The internal file is the following:

!md
    ## Displying data

    The simplest way of displaying data is to end the script with a expression that
    returns a value that is not __undefined__.

!tryit
    let arr = [0, 1, 2, 3, 4, 'hello'];
    arr.slice(2, 5);

!md
    ## Displaying and may values

    If we need to display display and other points of the script at ponts other than at the end, we need a display function, for example __console.log__

    * $$.D(exp1,exp2...) __Display Javascript expression results __
    * $$.HTML(str)  __Display string as HTML__
    * $$.json(expr) __Display data as JSON string__

    ### Displaying Javascript Data $$.D

    First we will use the __$$.D__ to display Javascript expressions. This function is
    very similar to __console.log(expr1, expr2)__

!tryit
    let name = "TryITjs"
    $$.D('Name: ', name); // display the naame and give it a description

    let jobTitle = "Developer";
    $$.D('Job Title', jobTitle);

    let arr = [0, 1, 2, 3, 4, 'hello'];
    $$.D(arr);

!md
    \
    ### Displaying HTML from string

    Here we will show how to render some HTML. In order to support remdering, TryITjs uses 
    ~~lt%%a href="https://semantic-ui.com/introduction/getting-started.html" target="_blank"~~gt%%Semantic-UI~~lt%%/a~~gt%%




Page - 2




Creating UI

Now we will create an example to a tutorial that shows you how to create UI. The expmplaw is kept intentionally simple so that we do not introduce too many complications all at once.

!head
  ~~lt%%title~~gt%%Modular Tryit~~lt%%/title~~gt%%
  @@include tools/head.try
  ~~lt%%script src="https://unpkg.com/react@16.12.0/umd/react.production.min.js" crossorigin="anonymous"~~gt%%~~lt%%/script~~gt%%
  ~~lt%%script src="https://unpkg.com/react-dom@16.12.0/umd/react-dom.production.min.js" ~~gt%%~~lt%%/script~~gt%%
  ~~lt%%script src="https://unpkg.com/semantic-ui-react/dist/umd/semantic-ui-react.min.js"~~gt%%~~lt%%/script~~gt%%
!md
   # Create UI

   There are several ways to create a UI using TryITjs. The simplest method is to create a string in Javascript with some HTML markup.
   The string is rendered in the output screen using the builtin TryITJs function ```$$.HTML(someHtmlString)```.


!md
  ## How to render some HTML

!tryit
  // Javascript - $$.HTML = builtin HTML
  $$.HTML(
     `~~lt%%h1~~gt%%Edit some HTML here~~lt%%/h1~~gt%%~~lt%%br~~gt%%~~lt%%br~~gt%%`
  );

!md
  ## More elaborate example

  In this example we will create a header with today's date and an image below it. The code for it is very simple as shown next.

!tryit
  // add some style
  $$.HTML(`
        ~~lt%%style~~gt%%
         .center {
          display: block;
          margin-left: auto;
          margin-right: auto;
        }
      ~~lt%%/style~~gt%%
  `)

  // Now render some html

  $$.HTML(`
    ~~lt%%div style="height: 30rem"~~gt%%
      ~~lt%%h1~~gt%%Hello World ${(new Date()).toLocaleDateString()}~~lt%%/h1~~gt%%
      ~~lt%%img class="center" src="https://www.w3schools.com/html/pic_trulli.jpg" /~~gt%%
    ~~lt%%/div~~gt%%
  `)


!md
    ## Semantic-UI example

    In this example we will create 3 button group, the first button is red, the second green, and the lat one the default color. After the
    button group we will plce an SVG image of a camera.


!tryit
  // The button group as a string
  var strHtml =   `
    ~~lt%%div style="width: 70%; margin-left: 10rem"~~gt%%
      ~~lt%%div class="ui three buttons"~~gt%%
        ~~lt%%button class="ui active button red"~~gt%%One~~lt%%/button~~gt%%
        ~~lt%%button class="ui button green"~~gt%%Two~~lt%%/button~~gt%%
        ~~lt%%button class="ui button"~~gt%%Three~~lt%%/button~~gt%%
      ~~lt%%/div~~gt%%
    ~~lt%%/div~~gt%%
  `;

  // Render the HTML in the output
  $$.HTML(
    `~~lt%%div id="ui-target"~~gt%%${strHtml}~~lt%%!-- html string to render --~~gt%%~~lt%%/div~~gt%%
    ~~lt%%div style="margin-left: 30rem; margin-top: 5rem"~~gt%%
     ~~lt%%img src="https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/AJ_Digital_Camera.svg" /~~gt%%
    ~~lt%%/div~~gt%%`
  )   

!md
  _Notes: the way the execution of the script works is, first the entire sceipt block is executed, all output is collected in a staging buffer. Once the execution of the script block has completed all the staged output is rendered in the output window.
  _


!md
  ### Using React JSX

It's easier to use inline JSX to render some UI. The code below will render some buttons 
in the output area.

!tryit
  // JSX - the system knows how to render JSX markup
  // Since the JSX obj is the last expression, it will be displayed in the output window
  (
  ~~lt%%div style={{width: "70%", marginLeft: '10rem'}}~~gt%%
    ~~lt%%div class="ui three buttons"~~gt%%
      ~~lt%%button class="ui active button red"~~gt%%One~~lt%%/button~~gt%%
      ~~lt%%button class="ui button green"~~gt%%Two~~lt%%/button~~gt%%
      ~~lt%%button class="ui button"~~gt%%Three~~lt%%/button~~gt%%
    ~~lt%%/div~~gt%%
    ~~lt%%div style={{marginLeft: "15rem", marginTop: "5rem"}}~~gt%%
      ~~lt%%img src="https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/AJ_Digital_Camera.svg" /~~gt%%
    ~~lt%%/div~~gt%%
  ~~lt%%/div~~gt%%
  )
!md      
  # UI using React

  This section will demonstrate we can use React and JSX to create some UI.

  * Ceate a function to create a div in JSX
       1. Display the current time
       2. Show an image


  _Notes: In a code block (the code block below) if you declare a variables ```let aVar``` the variable is local to the block, it is not visible 
  to any other block. On the other hand if the variable is declared as ```var aVar1``` then this variable and its content is available to 
  subsequent code block. In other words ```var``` declares a global variable, while ```let``` or ```const``` declares a local variable._

!tryit
// JSX example
var Clock= ({time}) =~~gt%% (
  ~~lt%%div style={{height: "30rem"}}~~gt%%
    ~~lt%%h1 class="center"~~gt%%~~lt%%b~~gt%%Hello World~~lt%%/b~~gt%% {(time||new Date()).toLocaleTimeString()}~~lt%%/h1~~gt%%
    ~~lt%%img class="center" src="https://www.w3schools.com/html/pic_trulli.jpg" /~~gt%%
  ~~lt%%/div~~gt%%
);

// Render the JSX by 
~~lt%%Clock time={new Date()}/~~gt%%

!md
    ## A simple running clock

    Using React to render a simple clock that updates the time. As explained earlier the rendering of the HTML is performed after the
  script has completely executed. This presents a challange since the script the HTML dom before the output has been rendered. To get
  around the problem we have another builtin function ```$$.lastly(aFunction)```. This delays the execution of the function until the output has been rendered.

!tryit
    // React JSX
    function JSXClock() {
      const clock = () =~~gt%% ReactDOM.render(~~lt%%Clock time={new Date()} /~~gt%%, document.getElementById('clock-id')); // function to render the React 'aClock'


      $$.HTML('~~lt%%div id="clock-id"~~gt%%~~lt%%/div~~gt%% ~~lt%%br /~~gt%%~~lt%%br /~~gt%%~~lt%%br /~~gt%%~~lt%%br /~~gt%%---------------'); // render HTML to create a div for the clock

      $$.lastly( () =~~gt%% setInterval(clock, 1000)); // execute after all rendering of output unsing the '$$.lastly( aFuncToExecute )'
    }    

    JSXClock();
!md
  ## Improved React Clock

  This is an example of an improved React implementation, using the new hooks API

!tryit
  let {useState, useEffect} = React;
  function BetterClock() {
      let [time, setTime] = useState(undefined);
      useEffect(() =~~gt%%{
        let timer = setInterval( () =~~gt%% setTime(new Date()), 1000);
        return ( () =~~gt%% clearInterval(timer));
      }, [])
      return ~~lt%%Clock time={time} /~~gt%%
  } 

  // Render the clock
  ~~lt%%BetterClock /~~gt%%


!end




Page - 3




Howto

This section explains how to apply all the facilities available to TryITJs.

Define a top level page

Add HTML

Add some markdown

Editable code example

Include the body of another try file

Include the content of URL

Display the content of a .try file

Display some TryITJs text




Page - 4