@abolis/plate-maker 中文文档教程

Question

Introduction

制版机是由 Abolis Biotechnologies 开发的开源前端工具，用于 模拟和可视化微孔板，这是一种带有多个孔的测定板，用作生物学中的小试管。 制版机是 灵活且易于使用的库，可以在 Angular* 项目中快速实施。

此工具是使用 Angular CLI v10.1.1 生成的，并使用 Node v10.16.0 和 NPM v6.13.6。 Plate Maker 依赖于 ngx-drag-to-select 包： 适用于 Angular 6 及更高版本的轻量级、快速、可配置和反应式拖动选择 (DTS) 组件。

*如果您是 Angular 新手，请访问 Angular 入门教程。

Table of Contents

• Main Features and Demonstration
• Project Structure
• Getting Started
  • Pre-requisites (Install)
• Running End-to-End Tests
• Configurations and Dependencies
• Adding Plate Maker to Your Application
  • Usage Example
    • Simulating an Assay Plate
    • Visualising an Assay Plate
• API
  • Customizing Styles
  • Main Features
• Development Github Release
• NPM Release
• Versioning
• Licence

Main Features and Demonstration

• Create and visualise assay plates with up to 96 wells
• Select wells on the assay plate simply by dragging (Drag to select)*
• Fill selected wells with objects from the Configuration menu
• Wells with the same content are grouped by color for easy visualisation
• Read-only assay plates in the visualization mode

*Drag To Select 是单击屏幕的一部分，按住鼠标按钮，然后将光标拖动到另一个位置的过程。 此操作将选择从拖动开始到结束的所有内容。

Project Structure

项目工作区包含三个主要部分：

• A library with Plate Maker components and modules (/projects/@abolis/plate-maker)
• An example of Plate Maker usage (/projects/app)
• An automatic end-to-end tests (/cypress)

plate-maker
    ├── cypress                           ─────── End-To-End tests  
    ├── project 
    |   ├── @abolis                       ───┐
    |   |   └── plate-maker                  |
    |   |       ├── src                      | 
    |   |       |   ├── lib                  |
    |   |       |   |   ├── *.html           ├─── Library
    |   |       |   |   ├── *.scss           |
    |   |       |   |   └── *.ts             |
    |   |       |   └── public_api.ts        |
    |   |       └── *.json                ───┘
    |   └── app                           ───┐
    |       └── src                          |  
    |           ├── app                      |
    |           |   ├── create-plate-app     |
    |           |   ├── display-plate-app    ├─── Application
    |           |   └── ...                  |
    |           ├── assets                   |
    |           ├── index.html               |
    |           └── ...                   ───┘
    ├── package.json
    /
    └── ...

Getting Started

Pre-requisites (Install)

安装和运行该库的标准方法是使用 NPM*。

  npm install           # if this is your first time here
  npm run build.lib     # Build the main library
  npm run serve.dev     # Run the app in development mode

更多构建任务，请查看package.json。

*如果您是 NPM 新手，请访问NPM 入门教程。

Running End-to-End Tests

运行 cypress.live 以通过 Cypress 在实时模式下执行端到端测试。 要在控制台模式下运行端到端测试，请使用 cypress.ci。 更多详细信息，请参阅 package.json。

Configurations and Dependencies

所有配置和依赖项都可以在 angular.json 和 package.json 中找到。

Adding Plate Maker to Your Application

• Declare Plate Maker library dependency in your package.json

  "@abolis/plate-maker": "^1.2.0"

• Add Plate Maker component in your html template, respecting its inputs and outputs.

<lib-plate-maker ...></lib-plate-maker>

Usage Example

为项目提供服务后，您可以访问 localhost 查看正在运行的应用程序，默认配置为 angular CLI项目。 主导航栏包含两个链接，一个用于模拟化验板，另一个对应于板可视化工具。

Simulating an Assay Plate

1. Drag your mouse over wells you want to select ('Drag to Select').
2. In the Configuration menu choose objects in Main Object or Other Object fields to fill selected wells with it. All wells containing an object will be colored by a random color and then grouped by this random color*.
3. Repeat steps 1 and 2 to fill in all neccessary wells of the plate with objects.
4. Use Save button of the Configuration menu to print an assay plate into the console. You can also send an assay plate to a backend server instead of printing it.

• To delete objects from selected wells use Backspace or Delete keys.
• To name an assay plate use the Barcode field.

*请注意，在 Main Object 字段中选择对象的孔可以按颜色分组，而在 Other Object 中选择对象的孔可以按颜色分组 字段不提供此选项。

Visualising an Assay Plate

• Select a barcode from the Barcode(s) menu to display an assay plate. Note, that the visualised assay plate is read-only.
• Barcode(s) menu provides an option of filtering assay plate by barcodes.
• The barcode(s) and their plate arrays can be fetched from a backend server.

有关更多实现细节，请参阅源代码 (/projects/app)。

API

在本节中，您将找到有关将 Plate maker 库集成到 Angular 项目的更多具体信息。

Customizing Styles

• If you use scss in your project then you need to add the following instruction on the top of your styles.scss:

// Overriding ngx-drag-to-select sass variables - Should be before importing ngx-drag-to-select scss file
$selected-item-border-size: 2px;
$selected-item-border-color: #000000;

// import ngx-drag-to-select scss file
@import "~ngx-drag-to-select/scss/ngx-drag-to-select";

• If you use css in your project then you have to import ngx-drag-to-select.css and add the following lines to styles.css:

.dts-select-container:not(.dts-custom) .dts-select-item.selected {
  border: 2px solid #000000;
}

Main Features

在 HTML 模板 (plate-maker.component.html) 中，您会注意到 dts-select-container 组件包裹了您想要的所有孔 在此组件中可选择。 此组件由 ngx-drag-to-select 库提供，并与以下功能一起使用：

Input/Output	Description
[(selectedWells)]	binds the selected wells
[disabled]	changes an editable plate to read-only
(selectionEnded)	triggered when wells are selected

另一方面，我们的 Plate Maker 组件旨在具有三个属性，一个 hostListener，三个输入和两个输出：

I/O/Prop./Listener	Type	Description
selectedWells	property	2D array, represents the selected wells when the [(selectedWells)] of the DTS component is fired
contentsDetails	property	array of strings, represents the well contents that will be displayed when clicking a well
truncateLimit	property	number, defines the limit of a well content
keyup	hostListener	listens to the keyup event (using keyboard Backspace and Delete keys to clear selected wells)
[wells]	input	2D array, gets plate wells sent by the app (e.g., an assay plate with empty wells at initialization)
[disableSelection]	input	boolean, signals if an assay plate is read-only (in visualization mode)
[tick]	input	an optional EventEmitter that plate-maker will subscribe to, to re-compute the wells rendering on-demand only. When this input is not provided, the computation is performed in ngDoCheck(), which is to say an (awful) lot of times. Use this input to increase performance if needed.
(selected)	output	emitted when well(s) is(are) selected for updating (filled)
(deleted)	output	emitted when well(s) is(are) selected for deleting objects from it

Well 由具有以下 4 个属性的 WellInterface

Property	Type	Description
row	number	row index of a well in a plate array
column	number	column index of a well in a plate array
bgColor	string	indicates the background color of a well
content	array	array of ContentInterface (see table below), represents well content

表示：Well 内容由具有 3 个以下属性的 ContentInterface 表示：

Property	Type	Description
type	string	represents content type
value	string	indicates the content value
mdb_classes	string	contains MDBootstrap classes to customize the displayed content

Development Github Release (for maintainers)

每个 Travis CI 管道推送一个 tar 包（显然只有当所有测试都通过时），可以在开发阶段的其他项目中使用。 因此，为了在另一个项目的 package.json 中声明这个库，只需在 github 发布。

NPM Official Release (for maintainers)

• Integrate your changes on master branch
• Git commit/push and wait for the job to succeed
• git checkout release branch
• Merge with master branch
• Bump up the version minor, and possibly major (https://semver.org/), in [package.json] of the app and the library
• If needed, update readme
• npm install
• Git commit with a message exactly matching Release YYYY.X.Z
• Git push and wait for the job to succeed \o/

Versioning

Plate Maker 将根据语义版本控制指南进行维护。 版本按以下格式编号：

..

MAJOR 版本表示不兼容的 API 更改，

MINOR 版本以向后兼容的方式添加功能，

PATCH 版本引入向后兼容的错误修复。

有关 SemVer 的更多信息，请访问 http://semver.org。

Licence

麻省理工学院 © Abolis Biotechnologies