Repository files navigation

Tutorial and sample application for the Embedded Wizard GUI builder

Embedded Wizard is a graphical user interface tool developed and distributed byTARA Systems GmbH for creating graphical user interface (GUI) applications mainly for embedded systems.

This project aims at providing a tutorial for novice users to get them started quickly.

While building a sample application step by step, the tutorial covers the following topics:

• Basic steps when building a GUI application
• Developing and prototyping reusable graphical components
• Device integration
• Localization of your application
• Persistent data storage on the target device

In order to preview a live demo of the sample application, navigate to the applicationdemo site.

The tutorial is hosted onGitHub pages, enjoy the tutorial!

If you have any suggestion for improvement or comment concerning this tutorial, feel free to open anissue.

For general question unrelated to this tutorial, you may make use of thequestion and answer site for Embedded Wizard users and UI developers.

The graphic below illustrates the structure of the repository:

docs/                    -> html sources of web site, linked to github pages  index.html                -> start page, redirection only  EmWiTutorial/latest/      -> html pages, images and attachments  _/                        -> GUI resourcessrc/                     -> Sources of Embedded Wizard tutorial application  EmWiTutorial.ewp          -> Embedded Wizard project file  xxx.ewu/                  -> Project unit xxx  yyy.ewu                   -> Project unit yyy  ...www/                     -> tutorial website  antora/                   -> antora publishing toolchain    playbook.yml               -> settings file, tells antora how to operate  asciidoc/                 -> sources, in asciidoc format    antora.yml                -> component descriptor file    modules/      ROOT/                      -> root module        nav.adoc                    -> navigation source file        assets/                     -> images and attachments        pages/                      -> page source files  pdf/                      -> pdf publishing toolchain    metadata.yml            -> metadata file, customization of pdf output    template.latex          -> pandoc LaTeX template (author: Pascal Wagler)    Tutorial.adoc           -> book file, includes all chapters of the tutorial  resources/images/         -> images used (photoshop format)  ui/                       -> website page templates, footer, header, ...    build/                     -> generated ui bundle 'ui-bundle.zip'

The html sources of the tutorial website can be found inside the directorydocs. This directory is linked to the github pages website. Any changes inside the directorydocs will be picked up immediately on the tutorial website.

The site is published usingAntora, a static site generator leveraging theAsciiDoctor text processing and publishing toolchain. Instructions on how to publish and possibly extend the site are given below:

First of all, install all needed prerequisites:

Make sure you havegit installed on your system.

C:\> git --version

If you don't havegit installed yet, download and run theGit installer.

For various installation tasks, we neednpm, the Node.js package manager.If you don't havenpm installed yet, download and run theNode.Js® installer. This installer will install bothNode.Js and the package managernpm on your system.

Withgit andnode installed, you’re ready to set up the project.

First, clone the project into a local directory of your choice and enter this directory:

C:\Users\Me\Projects> git clone https://github.com/deining/EmWiTutorial.gitC:\Users\Me\Projects> cd EmWiTutorialC:\Users\Me\Projects\EmWiTutorial> REM ready for the next steps

The project uses a customized version of theAntora Default UI as GUI template for the tutorial website. In order to successfully publish the tutorial site, we have to build and bundle this user interface first. Enter the directorywww\ui of the cloned repository and install the dependencies usingnpm first. Afterwards, issue twogulp commands to generate the bundled user interface:

C:\Users\Me\Projects\EmWiTutorial> cd www\uiC:\Users\Me\Projects\EmWiTutorial\www\ui> npm installC:\Users\Me\Projects\EmWiTutorial\www\ui> npx gulp preview:buildC:\Users\Me\Projects\EmWiTutorial\www\ui> npx gulp bundle

If all went fine, you should now see the UI bundleui-bundle.zip available inside the subdirectorybuild.

C:\Users\Me\Projects\EmWiTutorial\www\ui> dir /B buildui-bundle.zip

• The directorywww\asciidoc\modules\ROOT\pages contains the pages sources in asciidoc format. Extend and or alter these pages according to your needs.
• The directorywww\asciidoc\modules\ROOT\assets contains the images of the pages and the attachments the pages link to. Extend and or alter these resource files as needed.

Using theantora publisher, we can now build the tutorial site. Enter the directorywww\antora of the cloned repository and install the dependencies usingnpm first. Afterwards, issue the followingantora command to generate the tutorial site:

C:\Users\Me\Projects\EmWiTutorial\www\ui> cd ..\antoraC:\Users\Me\Projects\EmWiTutorial\www\ui> npm installC:\Users\Me\Projects\EmWiTutorial\www\antora> npx antora --fetch playbook.yml

If all went fine, you should now see your changes reflected in the web site stored inside the the subdirectorydocs of the cloned repository.

Besides the html sources, you may want to generate a pdf version of the tutorial website. While there are several ways to produce a pdf document from asciidoc sources, we found out that leveraging theLaTeX toolchain gave the best results. All needed files for pdf generation are found inside the directorywww\pdf. Be aware that generating high quality pdf documents is not an easy task, so don't expect a perfect result here.

PDF generation is done using a two step approach: first we producedocbook output from the asciidoc sources using theasciidoctor text processor. Afterwards, we use thepandoc document converter to convert the docbook source to a pdf document usingxelatex as pdf engine. Instructions on how to a generate a pdf version of the tutorial site are given below:

First of all, install the needed prerequisites:

Make sure you haveruby installed on your system.

C:\> ruby --version

If you don't haveruby installed yet, download and run theRuby installer.

Next, you have to installasciidoctor using the following command:

C:\> gem install asciidoctor

Download and run thePandoc installer if you don't havepandoc installed on your system yet.

Make sure you havexetex installed on your system.

C:\> xetex --version

If you don't havexetex installed yet, install a working LaTeX installation on your system. For that purpose, you may make use of theMiKTeX orproTeXt orTeX Live distributions.

Now that you haveasciidoctor,pandoc andxetex installed, you’re ready to generate the pdf of the tutorial site.

Enter the directorywww\pdf of the cloned repository and invokeasciidoctor text processor to produce docbook output from the asciidoc sources:

C:\Users\Me\Projects\EmWiTutorial> cd www\pdfC:\Users\Me\Projects\EmWiTutorial\www\pdf> asciidoctor --doctype book --backend docbook5 Tutorial.adoc

This will produce a fileTutorial.xml inside the same directory, containing docbook output.

Finally, invokepandoc converter to generate a pdf file from the docbook output you just generated:

C:\Users\Me\Projects\EmWiTutorial\www\pdf> pandoc Tutorial.xml --output Tutorial.pdf --from docbook --template template --metadata-file metadata.yml --pdf-engine xelatex --toc

This eventually will produce the pdf fileTutorial.pdf inside the same directory.

For pdf styling, we use thepandoc LaTeX template authored byPascal Wagler. Furthercustomization of the generated pdf can be achieved by extending the metadata filemetadata.yml.