Skip to content

1.4. Languages and Tutorials JSON web services

Jump to bottom
Francisco Bernardo edited this page Dec 4, 2020 · 1 revision

Sema has a couple of JSON web services implemented for content extensibility. The following sections explain how the services are structured, where are they published, how they can be extended and finally, where they are consumed in Sema.

The Languages service

The first service to consider is the Languages service, which indicates which languages are published and available to populate Sema with their assets. You can find it in Sema's solution in sema/assets/languages/languages.json or published in https://YOUR-SEMA-INSTANCE/languages/languages.json.

[{
    "name": "default"
  },
  {
    "name": "rubberduckling"
  },
  {
    "name": "nibble"
  },

  ...

Each language exists as a set of assets in a folder titled with the name of the language (e.g. rubberduckling). If you check the folder for the rubberduckling language assets/languages/rubberduckling which includes the language grammar file (i.e. grammar.ne) and the language default example (i.e. code.sem).

The Tutorial service

The Tutorial service provides all the structure and content necessary for adding to Sema interactive Tutorial area. You can find it in Sema's solution in sema/assets/tutorial/tutorial.json or published in https://YOUR-SEMA-INSTANCE/tutorial/tutorial.json.

[{
  "title": "Basics",
  "sections": [{
    "slug": "introduction",
    "title": "Introduction",
    "chapter_dir": "01-basics",
    "section_dir": "01-introduction"
  }, {
    "slug": "interface",
    "title": "Interface",
    "chapter_dir": "01-basics",
    "section_dir": "02-interface"
  }, {

The Tutorial service structures a table of contents and the respective hierarchy of chapters, sections and content. At the bottom of the hierarchy, for instance, chapter Basics, section Introduction, sema/assets/tutorial/01-basics/01-introduction you will find the content that populates that tutorial entry upon combobox selection:

  • index.md – a markdown file with text content and code snippets to copy and past, which load into the Tutorial's side bar
  • layout.json – a JSON file with the layout items and code that the Dashboard and svelte-grid components need to render widgets and code editor content.

Where JSON services are consumed in Sema

Other fundamental knowledge about the Languages and Tutorial JSON web services is where they are consumed in Sema. That is precisely in the main container route sema/client/routes/_layout.svelte, which is created when Sema loads.

The content is fetched from the Languages service to populate the Playground's sidebar, a UI element that presents options to create code editor widgets in the dashboard. The $: is Svelte's reactive expression operator, which is used here trigger loadSidebarLiveCodeOptions, which in turn makes an asynchronous request and populates the sidebar's store $sidebarLiveCodeOptions.

  $: loadSidebarLiveCodeOptions();

  ...

  /**
   * Loads language options from language service and set grammar and default code sources in the $sidebarLiveCodeOptions store
  */
  let loadSidebarLiveCodeOptions = () => {
		fetch(`/languages/languages.json`)
      .then(r => r.json())
      .then(json => {
        console.log("DEBUG:_layout:loadPlayground");
        console.log(json)
        $sidebarLiveCodeOptions = $sidebarLiveCodeOptions.concat(json.map( language => ({
            id: 1,
            disabled: false,
            text: language.name,
            content : {
              grammar:  `/languages/${language.name}/grammar.ne`,
              livecode: `/languages/${language.name}/code.sem`
            }
          })
        ));
        $ready();
      });
  }

For the Tutorials there is an orchestration of two services; one that fetches the tutorials' table of contents, and one that fetches the selected tutorial specifically

  $: fetchAndLoadDefaultTutorial();
  $: fetchAndLoadDefaultTutorialItems();

  ...

  /**
   * Fetches Tutorial table of contents and sets default tutorial (Basics/Introduction)
  */
  let fetchAndLoadDefaultTutorial = () => {

		fetch(`/tutorial/tutorial.json`)
      .then(r => r.json())
      .then(json => {
        $tutorials = json;
        $selected = $tutorials[0].sections[0];
        $ready();
      });
  }

  /**
   * Fetches and sets the contents of the default tutorial (Basics/Introduction)
  */
  let fetchAndLoadDefaultTutorialItems = () => {

    fetch(`/tutorial/${$params.chapter_dir}/${$params.section_dir}/layout.json`)
      .then( r => r.json())
      .then(json => {
        $items = json.map( item => hydrateJSONcomponent(item) );
        $ready();
      });
  }

  let persistentParams = { chapter: '01-basics', section: '01-introduction' };
  // update url parameters only when navigating tutorials
  $: if($params.chapter && $params.section) persistentParams = $param

Note the last line, where there is a reactive expression for setting up the default selection of the Tutorial Table of Contents combobox which depends on the route's selection parameters given by Routify. That means that for every selection there is a request that downloads a tutorial, sets its content not the stores and hydrates the layout widgets components.

Clone this wiki locally