Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add English User Guide. #4

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions src/ng/demo/src/webdoc/faq-en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
title: FAQ | TinyNG
---

# FAQ
## 1. How to fix the error "Can't bind to 'ngModel' since it isn't a known property of 'ti-xxxxx'"?

To use `ngModel`, you need to import `FormsModule`.

```typescript
import { FormsModule } from '@angular/forms';
@NgModule({
imports: [
...
FormsModule,
...
],
})
```

## 2. How to fix the error "Can't bind to 'yyyyy' since it isn't a known property of 'ti-xxxxx'"?

Import the corresponding module of the component.

```
If 'ti-xxxxx' is an Angular component and it has 'options' input, then verify that it is part of this module.
If 'ti-xxxxx' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@NgModule.schemas' of this component to suppress this message.
To allow any property add 'NO_ERRORS_SCHEMA' to the '@NgModule.schemas' of this component.
```

## 3. How to find the module name of the `TinyNG` component?

When looking at examples of specific components, the module on which the component depends will be displayed at the top of the page.

## 4. How to fix the error "ExpressionChangedAfterItHasBeenCheckedError: Expression has changed after it was checked"?

This is a prompt from the Angular debugging environment, indicating that Angular has finished rendering the templates, but the business code changes the template variables after `ngAfterViewInit()` or later.

Two solutions: 1. Optimize code organization and change template variables in advance. 2. After changing the template variables, force the template to refresh (refer to this article).

## 5. When using the `TinyNG` library for business development, how to debug it step by step?

The TinyNG library has built-in source maps, which is very convenient for debugging step by step. The method of debugging step by step:

At present, Angular CLI 7.0 version, `ng serve --vendor-source-map` (this parameter has been officially deprecated)

Angular CLI 7.2 version, `ng serve --source-map=true`

## 6. Why did I encounter an error when the code I wrote was exactly the same as that on the official website?

Please use `Angular CLI` to create a new project, copy the code from the official website, and check if the component behaves the same as that on the official website.

## 7. There is a scrollbar in part of the page, and the dropdown list inside it is misplaced when scrolling?

The dropdown box component registers the `tiScroll` event on the document. When this event is detected, the component will make the dropdown box disappear.

Developers need to trigger the `tiScroll` event on the document in the callback function of the corresponding scroll bar's scroll event to make the dropdown box disappear when dragging the local scrollbar.

```typescript
const event: Event = document.createEvent('HTMLEvents');
event.initEvent('tiScroll', false, true);
element.dispatchEvent(event);
```

## 8. How to fix the error "can't bind 'fromGroup'"?

To use the reactive form directive, you need to import `ReactiveFormsModule`, see [Reactive Forms](https://angular.io/guide/reactive-forms) for details.

```typescript
import { ReactiveFormsModule } from '@angular/forms';
@NgModule({
imports: [
...
ReactiveFormsModule,
...
],
```

## 9. Why aren't the style settings on the tags in HTML string fragments passed to some component interfaces effective?

In order to prevent XSS attacks, the component uses Angular's `DomSanitizer.sanitize` method for anti-XSS attack security processing, which will filter out the `style` setting, so it is recommended to use the `class` method to add styles. If you must use the `style` method and can ensure that the HTML string fragment passed in is safe, you can use the `bypassSecurityTrustHtml` method on the Angular-provided `DomSanitizer` to remove Angular's security filtering processing, which can be referenced from `message/message-security`.
89 changes: 89 additions & 0 deletions src/ng/demo/src/webdoc/getstart-en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
title: Getting Started | TinyNG
---

# Getting Started

`TinyNG` is a web UI component library based on Angular + TypeScript. This article will introduce how to use `TinyNG` components in a project.

> Before using the `TinyNG` component library, we recommend that you learn [HTML](https://www.w3schools.com/html/default.asp), [CSS](https://www.w3schools.com/css/default.asp), [TypeScript](https://www.typescriptlang.org/), and [Angular](https://angular.io/docs).

## First Local Instance

If you already have an Angular application project, please go directly to the [Installation](#installation) step.

If not, we strongly recommend using the official `@angular/cli` tool to create a project. It has outstanding contributions in building, developing, debugging, packaging, and deploying projects, and provides great help for developers.

#### Installing scaffolding tools

> If you want to learn more about the functionality and commands of the CLI toolchain, it is recommended to visit [@angular/cli](https://angular.io/cli) to learn more.

```bash
$ npm install -g @angular/cli
```

#### Creating a project

> Before creating a project, please make sure that `@angular/cli` has been successfully installed.

Create an Angular project named MYAPP in the current directory using `@angular/cli`, and automatically install the corresponding dependencies.

```bash
ng new MYAPP
```

## Installation and Use

#### Enter the project root directory and use npm to install `TinyNG`.

```bash
cd MYAPP
npm install @opentiny/ng @angular/cdk
```

#### Import the module

Before using a specific component, you need to import the corresponding module. Here, we will use the `Button` component as an example.

```typescript
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; // some components depend on angular animations, so you may need to import the animations module
import { NgModule } from '@angular/core';
import { TiButtonModule } from '@opentiny/ng'; // import the module of a specific component
import { AppComponent } from './app.component';

@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
BrowserAnimationsModule,
TiButtonModule // import this module
],
bootstrap: [AppComponent],
})
export class AppModule {}
```

#### Importing the Style File

In the `angular.json` file, import the `TinyNG` component library style files.

```json
{
"build": {
"styles": [
"node_modules/@opentiny/ng/themes/styles.css", // basic style
"node_modules/@opentiny/ng/themes/theme-default.css", // theme style
"src/styles.css"
]
}
}
```

The `TinyNG` component library has built-in 5 sets of themes, which are theme-default.css, theme-blue.css, theme-green.css, theme-purple.css, and theme-red.css. You can choose according to your business scenario, or select more style configuration methods in [Theme Configuration](./themedoc).

## Starting Development Debugging

```bash
ng serve --open
```
32 changes: 32 additions & 0 deletions src/ng/demo/src/webdoc/introduce-en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: Introduction | TinyNG
---

# Introduction

`TinyNG` is a web UI component library based on Angular + TypeScript, which can be used for developing enterprise-level front-end pages.

### Features

- Interaction language and visual style suitable for enterprise-level PC products.

- Over 70 high-quality Angular component libraries with out-of-the-box capabilities that almost cover all business scenarios.

- Developed using TypeScript, providing complete type definitions.

- Supports OnPush mode, showing remarkable performance.

- Supports 5 international languages.

- Provides ultra-granular theme customization capabilities through CSS variables.

### Supported Environments

| <img src="/src/ng/demo/src/assets/browser/edge.png" alt="Edge" width="24px" height="24px" /><br>Edge | <img src="/src/ng/demo/src/assets/browser/firefox.png" alt="Firefox" width="24px" height="24px" /><br>Firefox | <img src="/src/ng/demo/src/assets/browser/chrome.png" alt="Chrome" width="24px" height="24px" /><br>Chrome | <img src="/src/ng/demo/src/assets/browser/safari.png" alt="Safari" width="24px" height="24px" /><br>Safari |
| --------- | --------- | --------- | --------- |
| last 3 versions | last 3 versions | last 3 versions | last 2 versions |

### Supported Angular Versions
Currently supports Angular `^14.0.0` version.

### [Latest Version](./changelog)
4 changes: 1 addition & 3 deletions src/ng/demo/src/webdoc/introduce.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ title: 介绍 | TinyNG

- 通过CSS variables 提供超细粒度的主题定制能力。



### 支持环境

| <img src="/src/ng/demo/src/assets/browser/edge.png" alt="Edge" width="24px" height="24px" /><br>Edge | <img src="/src/ng/demo/src/assets/browser/firefox.png" alt="Firefox" width="24px" height="24px" /><br>Firefox | <img src="/src/ng/demo/src/assets/browser/chrome.png" alt="Chrome" width="24px" height="24px" /><br>Chrome | <img src="/src/ng/demo/src/assets/browser/safari.png" alt="Safari" width="24px" height="24px" /><br>Safari |
Expand All @@ -31,4 +29,4 @@ title: 介绍 | TinyNG
### 支持 Angular 版本
目前支持 Angular `^14.0.0`版本。

### [最新版本](./changelog)
### [最新版本](./changelog)
154 changes: 154 additions & 0 deletions src/ng/demo/src/webdoc/joinus-en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
---
title: Join us | TinyNG
---
## Contribution Guide

### Issue Specification

- Issues are only used to submit Bugs or Features, as well as content related to user experience. Other content may be directly closed.

- Before submitting an issue, please search for related content first to see if it has already been raised.

- When providing the Bug, please specify clearly the version number of @opentiny/ng and related environment used.

### Pull Request Specification

- Please fork a copy to your own project and create a branch for changes.

```bash
git checkout -b my-branch master
```

- Follow [commit rules](https://github.com/opentiny/ng/blob/main/commit.template) when writing commit message.

- Prior to submitting a PR, please perform a rebase to ensure that the commit record is clean.
```bash
git rebase master -i
git push -f
```

- If you are fixing a `bug` or `issue`, please describe it clearly in the PR.


### Development

```bash

# fork && git clone
...
# my-branch
npm install
npm start

```

## Unit Testing

### Overall Testing
```bash
$ npm test ng-demo
```
or
```bash
$ npx ng test ng-demo
```

### Specific Component Testing
```bash
$ npm test ${component name for test}-demo
```
or
```bash
$ npx ng test ${component name for test}-demo
```

For example:
```bash
$ npm test text-demo
```

### Adding Test Cases

- Because each component in the library has a separate version, developers need to prepare a unit test environment for newly added components. (An automated script can also be used to generate the required files for the new component, such as: `npm build:test radio`)
- For existing components, simply create a `${your component name}.spec.json` file in the component `demo/` directory and write test scripts.
- If the `${your component name}.spec.json` file already exists in the component demo directory, simply modify the case in this file.

TinyNG uses the [Jasmine testing framework](https://jasmine.github.io/) to perform unit testing on the component library content.
The `npm test` command builds the application in **watch mode** and starts the [karma test runner](https://karma-runner.github.io/).
After the run is complete, the console outputs the test results in the following format:

```
✔ Browser application bundle generation complete.
28 11 2022 08:40:17.804:WARN [karma]: No captured browser, open http://localhost:9876/
28 11 2022 08:40:17.824:INFO [karma-server]: Karma v6.3.20 server started at http://localhost:9876/
28 11 2022 08:40:17.825:INFO [launcher]: Launching browsers Chrome with concurrency unlimited
28 11 2022 08:40:17.833:INFO [launcher]: Starting browser Chrome
28 11 2022 08:40:19.278:INFO [Chrome 107.0.0.0 (Windows 10)]: Connected on socket swhnqYi_RwdYbu8uAAAB with id 55443332
Chrome 107.0.0.0 (Windows 10): Executed 5 of 5 SUCCESS (0.562 secs / 0.815 secs)
TOTAL: 5 SUCCESS
```

It also opens the Chrome browser and displays the test output in the [Jasmine HTML Reporter](https://github.com/dfederm/karma-jasmine-html-reporter). You can click on a specific test case to rerun it, or click on a description row to rerun the tests selected in that test suite.

Unit testing cases and related configurations are located in the `/src/test/` directory.

For more detailed information, consult the [Angular testing introduction](https://angular.cn/guide/testing).

### Code Specification
Follow [ESLint](https://github.com/opentiny/ng/blob/main/.eslintrc.js)

## Recruiting Talents
### Web Front-end Development Engineer

#### Job Responsibilities

+ The team currently uses Angular and Vue as front-end frameworks and uses ES6/7 to do specific development work;

+ Front-end engineering, creating an end-to-end engineering system from project initialization, construction deployment, release to operation and maintenance, and creating front-end DevOps;

+ Visual building technology, based on less or no code building methods, improves the development efficiency of activity operations;

+ Targeting scenarios that focus on first-screen rendering and SEO, research and develop a Nodejs+Vue Isomorphic solution to achieve ultimate page performance for first screen rendering;

+ For Nodejs, independently research and develop front-end engineering system-related tools, use Nodejs more efficiently to implement web layer development, and use Nodejs for server-side development in high-concurrency business scenarios;

+ Based on Serverless solutions, solve Nodejs operation and maintenance issues and improve front-end development efficiency.


#### Skills required

+ Proficient in various front-end technologies, including HTML, CSS, JavaScript, etc.;

+ Have cross-terminal front-end development capabilities, proficient in at least one direction of Web (PC+Mobile), Nodejs, and Native App, and having multiple ones is better, and encourage exploration of the integration of Native and Web technologies;

+ Have a certain understanding of front-end engineering and modular development, and have practical experience (such as Webpack, Babel, AMD, CMD, etc.);

+ Possess excellent teamwork spirit, use own technical capabilities to improve the overall development efficiency of the team, and enhance team influence;

+ Have sustained enthusiasm for front-end technology, with a cheerful personality, strong logical thinking, and smooth communication skills;

+ Willing to share, good at summarizing and precipitating, and able to share good experiences within the team;

+ Optional: be familiar with at least one non-front-end language (such as Java, PHP, C, C++, Python, Ruby), and have practical experience.

### Java Backend Development Engineer

#### Job Responsibilities

+ Participate in the architecture design, detailed scheme design and development of core frameworks, and provide users with high-availability and high-performance console services;

+ Responsible for solution design and development in the field of cloud-native, realizing high traffic and high concurrency of cloud service business;

+ Responsible for the incubation, design, and development of public services and middleware, building industry-leading platform capabilities.

#### Skills required

+ Familiar with J2EE, Java Web programming technology, deeply apply and optimize various open-source frameworks such as Spring;

+ Familiar with Netty, familiar with multi-threaded model programming and network IO model;

+ Familiar with Spring Boot, Spring MVC, Redis, MySQL;

+ Have strong learning ability and technical sensitivity, a strong sense of responsibility and enterprising spirit, and enjoy learning and sharing technology.

If you are interested in joining, please add WeChat to consult: ly5353523.
Loading