Skip to main content

Quick Start

Quick Start

In this chapter, we will introduce how to use Glyphix.js to create a simple application. We will start by installing the build tools, then create a project, and run the emulator to view the results. Finally, we will briefly introduce the project structure and main files. This tutorial does not cover how to run applications on real devices or how to publish applications.

Preparation

Before you begin, please refer to this document to install the Glyphix build tool. Simply put, you can use npm to install the glyphix-cli package:

npm install -g glyphix-cli

Since Glyphix development tools are primarily CLI-based, we recommend installing a modern shell such as Zsh or PowerShell 7+, along with useful plugins to improve operational efficiency.

Terminal Tools

For Linux or macOS users, it is recommended to install Oh My Zsh. For Windows users, it is recommended to install Windows Terminal and use Oh My Posh. Please also refer to the gx completion documentation to install the autocomplete script for the gx command.

You can use any editor to develop Glyphix apps, such as VS Code or Quick App IDE.

Tips

The Quick App IDE does not have a built-in glyphix.js bundling tool; you still need to install glyphix-cli and use the gx command in the terminal to build and run your project. When using editors such as VS Code, it is recommended to associate *.ux files with the html format to obtain basic syntax highlighting.

Using Node.js

If you decide to use npm packages or any resources from the Web development ecosystem in your project, please refer to the Node.js configuration documentation. Using Node.js is not mandatory, but it supports modern development tools like TypeScript.

Using Build Tools

Once everything is set up, run the gx list device command in the terminal. If you get output similar to the following, the installation was successful:

$ gx list device
  default
  ...

Next, create an app project and run it in the emulator! Simply use the following commands:

gx new myapp # Create a project named myapp; this will create a directory named myapp
cd myapp     # Change to the myapp directory
gx emu       # Run the emulator

If all goes well, you will see a window displaying "Hello World!". Subsequent tutorials will explain the command usage of the glyphix.js tool in more detail.

Tips

Refer to the gx build and gx emu documentation for more information about building and running the emulator.

Project Structure

You can use the file explorer to view the structure of the myapp directory. In the current version, its structure is as follows:

<app-name>
├─ README.md         # Project README file
└─ src               # Project source code directory
    ├─ app.js        # App entry script file
    ├─ manifest.json # Configures basic application information
    ├─ assets        # Stores public resources (fonts, images, etc.)
    │  ├─ fonts      # Stores font resources
    │  └─ images     # Stores image resources
    └─ main          # Directory for the main page
        └─ index.ux  # UI description file for the main page

In the default project template, source code is located in the <app-name>/src directory. Resources that do not need to be bundled or released, such as project documentation, can be placed in other directories.

We recommend creating a dedicated directory for each page (using the page name as the directory name) and placing it in the source code root. Component source files (*.ux files) used exclusively within a page should be placed in that page's directory, while common files can be organized according to the following rules:

  • Common UX files and scripts can be placed in the common directory
  • Script files referenced only within a page should be stored directly in that page's directory
  • Font files are stored in the assets/fonts directory
  • Image files are stored in the assets/images directory
  • Other resources can be stored in appropriate locations within the assets directory

Project Files

Now that you have seen some files inside myapp, please note the files with the *.ux extension and the manifest.json file; these are the files you will interact with most frequently during development. The following tutorial will briefly introduce them.

manifest.json File

The manifest.json file is the app's configuration file, which is used for the app build. This file contains basic information about the app, including the app name, version information, etc. It also includes descriptions and routing information for all pages within the app. In other words, page descriptions must be added to manifest.json before you can navigate to those pages in the code.

This is the content of the manifest.json file generated by the gx command:

{
  "package": "com.example.app",
  "name": "Example App",
  "versionName": "1.0.0",
  "versionCode": 1,
  "features": [],
  "router": { // Page routing information
    "entry": "main", // Initial page of the application
    "pages": { // Page description information
      "main": {
        "component": "index"
      }
    }
  }
}

Warning

For instructional purposes, this manifest.json code snippet contains comments. However, JSON does not support comments; please do not add any comments to the manifest.json file in your project.

Fill in Application Information

You can provide your app information in manifest.json.

Add page description

In the root fields of the manifest.json file, the router and pages fields are related to page descriptions. The router field is the application's page routing table, which must have at least the entry field to specify the application's entry page; typically, the main page is used as the entry point.

If you want to add a new page, you need to add content to the pages field. For example, if we want to create a new page named NewPage, and the entry component for this page is NewPage/index.ux, then the content of the pages field is as follows:

"pages": {
  "main": {
    "component": "index"
  },
  "NewPage": { // This is the newly added page
    "component": "index"
  }
}

The pages field is a JSON object where each key is a page name, which by default also represents the path to the page directory. The value corresponding to a page name is also an object; its component property is the name of the page's entry component, which must be stored in the page directory. The component field is the filename of the page entry component (excluding the extension). All names are case-sensitive.

When you add or remove pages, remember to update the relevant fields in manifest.json.

See the relevant documentation for the structural description of the manifest.json file.

UX File Introduction

UX (UI XML) is the interface description file for Glyphix. Taking the initial template project as an example, the content of the main/index.ux file is as follows:

<template>
  <p>{{text}}</p>
</template>

<style>
  * {
    text-align: center;
  }
</style>

<script>
  export default {
    data: {
      text: "Hello, World!"
    }
  }
</script>

A UX file is essentially an XML file. This UX file contains root nodes: <template>, <style>, and <script>. The content within the <template> node is the structural description of the interface, the <style> node defines the style sheets, and the content within the <script> node is the JavaScript script that implements the interaction logic of the component.

Tips

VS Code does not provide syntax highlighting for UX files. You can switch the language to "HTML" in the bottom right corner for better highlighting.

Component Introduction

The object corresponding to a UX file at runtime is called a component. Components are an important concept in the Glyphix JavaScript application framework. Every component is a UI element that has these characteristics:

  • Components have their own display effects
  • Some components can respond to user input
  • Some components can display corresponding effects based on data and state
  • Components can be embedded into other components for use

Common UI elements are all components in the Glyphix JavaScript application framework, for example:

  • Text: Used to display text information
  • Button: Buttons can also display text information; most importantly, they can respond to click events (and of course, display effects when clicked)
  • List: Lists contain other components and arrange them vertically; additionally, element components in the list can be moved via swipe gestures

Components like lists that can contain other components are also called container components.

As you can imagine, a component consists of two elements: visual appearance and behavioral logic. The <template> tag in a UX file declares the component's appearance. Taking main/index.ux as an example:

<template>
  <p>{{text}}</p>
</template>

The main/index.ux component uses a <p> component to display content. This component is used for displaying text, and the value of the {{text}} expression is the text to be displayed.

The JavaScript script in the <script> tag implements the behavioral logic of the component. This tag always uses export default to export a component object. First, focus on the data property of the component object, which is usually an object:

export default {
  data: {
    text: 'Hello, World!'
  }
}

Here, the data object has a text property, and the value of this property will be used as the display content for the preceding <text> component.

Component model and state updates

Suppose we need to design a component that displays different text when clicked. In this case, we need to listen for input events on the component and update the displayed content. The following code listens for the click event on the <p> component:

<template>
  <p on:click="text += '!'">{{text}}</p>
</template>

The expression in the on:click property is executed when the text is clicked. Therefore, an '!' character will be appended to the end of the text displayed in the <p> component upon clicking:

Click event360×120px 
<p on:click="text += '!'">{{text}}</p>

export default {
  data: {
    text: "Hello, World!"
  }
}

p {
  font-size: 32px;
  text-align: center;
}

We will introduce the component update mechanism in detail in later tutorials.

Start Developing the Application

Now, you can start developing your own Glyphix applications! Start writing code from the default project template and use the gx emu command to run the emulator. Other chapters of this documentation will introduce how to build interfaces using Glyphix's built-in mechanisms, APIs, and components, as well as how to implement the application's interaction logic.

Glyphix framework