Hướng dẫn tại đây bao gồm mọi thứ cần thiết để bắt đầu phát triển Module của bạn vận hành trên nền tảng AppTeng, bao gồm cấu trúc để cập nhật thường xuyên và đóng gói Module.
Khái niệm Module trên nền tảng AppTeng là gì?
Module là một trong các thành phần cốt lõi của nền tảng AppTeng, dùng để hoạt động trên giao diện người dùng, Bảng điều khiển ứng dụng, các tuỳ biến tính năng và thậm chí là nhiều hơn nữa.
Một Module là duy nhất với các tính năng và cài đặt hoàn chỉnh trên nền tảng AppTeng để được sử dụng trong các ứng dụng di động và được quản lý trong Bảng điều khiển ứng dụng.
Vui lòng liên hệ với chúng tôi để nhận Lõi Module mẫu, từ đó bạn có thể bắt đầu với việc tạo Module chạy trên nền tảng AppTeng.
Kết cấu Module
Cấu trúc thư mục
ModuleName
├─ Controller
│ └─ Default.php /** Nếu bạn cần ghi đè các lớp điều khiển mặc định */
├─ controllers
│ ├─ Backoffice
│ │ └─ ModuleName.php
│ └─ Mobile
│ └─ ModuleName.php
├─ Form
├─ Model
├─ View
├─ resources
│ ├─ db
│ │ ├─ data
│ │ └─ schema
│ ├─ media
│ │ └─ library
│ ├─ translations
│ │ ├─ default
│ │ │ └─ mymodule.csv
│ │ ├─ en
│ │ └─ [...]
│ ├─ design
│ └─ var /** Mọi thứ liên quan đến ứng dụng gốc. */
└─ package.json
Các khái niệm cơ bản
1.Các package.json là gì ?
Các package.json được sử dụng bởi trình cài đặt để nhận biết các tham vấn, nó được lập trình để chạy cài đặt, cập nhật và nâng cấp:
{
"name": "ModuleName",
"description": "Module description",
"type": "module",
"version": "1.0",
"dependencies": {
"system": {
"type": "TEA",
"version": "4.6.2"
},
"modules": {
"OtherModule": "4.6.2"
}
}
}
2. resources/db/schema
AppTeng sử dụng resources/db/schema/table_name.php để mô tả các bảng schema;
Dưới đây là một ví dụ về một bảng cơ bản.
Tập tin này phản ánh cơ sở dữ liệu của bạn hiện tại trong phiên bản mới nhất, mỗi khi bạn tiến hành cập nhật phiên bản mới của Module, nó sẽ so sánh với tập tin này và cập nhật những gì còn thiếu.
Lưu ý quan trọng: Bảng schema sẽ thêm các trường mới nếu nó chưa có, các trường dữ liệu đã có không bao giờ được gỡ bỏ.
<?php
/**
* Định nghĩa lược đồ cho 'table_name'
*/
$schemas = (!isset($schemas)) ? array() : $schemas;
$schemas['table_name'] = array(
'mytable_id' => array(
'type' => 'int(11) unsigned',
'auto_increment' => true,
'primary' => true,
),
'admin_id' => array(
'type' => 'int(11) unsigned',
'is_null' => true,
'foreign_key' => array(
'table' => 'admin',
'column' => 'admin_id',
'name' => 'FK_MY_MODULE_ADMIN_ID_ADMIN_AMIN_ID',
'on_update' => 'CASCADE',
'on_delete' => 'CASCADE',
),
),
'name' => array(
'type' => 'varchar(50)',
'default' => 'default_value',
'index' => true,
),
'created_at' => array(
'type' => 'datetime',
),
'updated_at' => array(
'type' => 'datetime',
),
);
Danh sách các tùy chọn có sẵn:
KEY | KIỂU | CÁCH SỬ DỤNG, GIÁ TRỊ, HƯỚNG DẪN |
type | String | int(11) unsigned, varchar(50), datetime, vân vân…. |
auto_increment | Boolean | |
primary | Boolean | |
is_null | Boolean | |
default | mixed | |
foreign_key | Array() | Xem tuỳ chọn ForeForeign Key ở Bảng bên dưới |
index | Array() | Xem tuỳ chọn Index ở Bảng bên dưới |
Tuỳ chọn Foreign Key
KEY | KIỂU | CÁCH SỬ DỤNG, GIÁ TRỊ, HƯỚNG DẪN |
table | String | Bảng tham chiếu |
column | String | Cột được tham chiếu trong bảng |
name | String | Tên Foreign Key (Ví dụ: FK_TABLENAME_KEYNAME_REFTABLENAME_REFKEYNAME) |
on_update | String | NO ACTION, SET NULL, CASCADE, RESTRICT |
on_delete | String | NO ACTION, SET NULL, CASCADE, RESTRICT |
Tuỳ chọn Index
KEY | KIỂU | CÁCH SỬ DỤNG, GIÁ TRỊ, HƯỚNG DẪN |
key_name | String | Tên Index, sử dụng giống nhau trên nhiều cộtcột cho chỉ số tổng hợp |
index_type | String | BTREE, HASH |
is_null | Boolean | |
is_unique | Boolean |
3. resources/db/data
Thư mục này được sử dụng để chèn các giá trị mặc định khi cài đặt, hoặc cập nhật một Module.
Mỗi tập tin php trong thư mục này sẽ được thực hiện khi cài đặt và/hoặc cập nhật module, nó cần được thể hiện dữ liệu cần thiết là phiên bản mới nhất.
Các tên cấm xoá bao gồm install.php và %VERSION%.php là một chuỗi semver, bạn không bao giờ phải sử dụng chúng.
Hướng lập trình tốt nhất:
Nếu Module của bạn có nhiều tính năng, hãy chia chúng thành nhiều file, ví dụ feature1.php, feature2.php, vân vân …
Dưới đây là một ví dụ cho File tập tin có tên job.php
<?php
# Job module, data.
$name = "Job";
$category = "social";
# Icon, icon trước hết được đặt làm mặc định cho Module,
# sau đó tất cả icon được chèn vào trong thư viện.
$icons = array(
"/app/local/modules/Job/resources/media/library/job1.png",
"/app/local/modules/Job/resources/media/library/job2.png",
);
$result = AppTeng_Feature::installIcons($name, $icons);
# Cài đặt Module
$data = array(
"library_id" => $result["library_id"],
"icon_id" => $result["icon_id"],
"code" => "job",
"name" => $name,
"model" => "Job_Model_Company",
"desktop_uri" => "job/application_job/",
"mobile_uri" => "job/mobile_list/",
"mobile_view_uri" => "job/mobile_view/",
"mobile_view_uri_parameter" => "company_id",
"only_once" => 0,
"is_ajax" => 1,
"position" => 1000,
"social_sharing_is_available" => 1
);
$option = AppTeng_Feature::install($category, $data, array("code"));
# Nhiều sắp xếp bố trí
#
# Nếu module của bạn có nhiều sắp xếp bố trí, hãy sử dụng phần sau đây, nếu không hãy bỏ qua nó
# Bố trí Layouts
$layout_data = array(1, 2);
$slug = "job";
AppTeng_Feature::installLayouts($option->getId(), $slug, $layout_data);
# !Nhiều bố trí layouts
# Phần này trùng lặp các icons cho thiết kế Flat, bạn có thể có nhiều icons khác nhau
# hoặc cùng sử dụng một icons, bạn phải viết phần này
# Icons
$icons = array(
"/app/local/modules/Job/resources/media/library/job1.png",
"/app/local/modules/Job/resources/media/library/job2.png",
);
$result = AppTeng_Feature::installIcons("{$name}-flat", $icons);
Danh sách các tuỳ chọn:
KEY | KIỂU | CÁCH SỬ DỤNG, GIÁ TRỊ, HƯỚNG DẪN |
$name | String | Tên Module của bạn |
$category | String | social, media, contact, monetization, customization, integration, events, misc |
Danh sách các tuỳ chọn cho $data
KEY | KIỂU | CÁCH SỬ DỤNG, GIÁ TRỊ, HƯỚNG DẪN |
code | String | Đây là code duy nhất cho Module của bạn |
name | String | Tên Module của bạn |
model | String | Mô hình lớp mặc định được sử dụng trong trình biên tập Module. |
desktop_uri | String | Mặc định lớp điều khiển uri sử dụng trong trình biên tập Module. |
mobile_uri | String | |
mobile_view_uri | String | |
mobile_view_uri_parameter | String | |
only_one | Boolean | Điều chỉnh Module có một lần tính năng này, hoặc nhiều hơn. |
is_ajax | Boolean | |
position | Integer | Vị trí tính năng trong danh sách các tính năng của module, để trống cho tự động. |
social_sharing_is_available | Boolean | Cho phép chia sẻ mạng xã hội module của bạn (thử nghiệm) |
Dịch các ngôn ngữ cho Module
Đầu tiên tạo một file mới có tên mymodule.csv sau đó đặt file này trong thư mục translations/default
Nếu bạn muốn module của bạn được phép xuất hiện trong nhiều bản dịch ngôn ngữ khác nhau, hãy tách các file trong các thư mục có tên với mã ngôn ngữ cụ thể:
Ví dụ:
– Tiếng Việt cần ở trong thư mục translations/vi/mymodule.csv
– Tiếng Anh cần ở trong thư mục translations/en/mymodule.csv
Dưới đây là các ví dụ file ngôn ngữ Tiếng Anh và Tiếng Việt có tên contact.csv
Lưu ý quan trọng: Vui lòng liên hệ với chúng tôi trước khi đặt tên, để tránh đặt tên file trùng với các file ngôn ngữ hiện đã có trên nền tảng AppTeng, vì khi đó các bản dịch ngôn ngữ của bạn sẽ không hoạt động.
Tiếng Việt:
"Đã xảy ra lỗi khi lưu thông tin liên hệ của bạn."
"Đã xảy ra lỗi khi thực hiện yêu cầu của bạn. Vui lòng thử lại sau ít phút"
"Và đây là số điện thoại của anh ấy:"
"Bạn chắc chắn muốn xoá hình ảnh này?"
"Thành phố"
"Thông tin liên hệ"
"Địa chỉ Email:"
"Nội dung tin nhắn:"
"Vui lòng nhập dữ liệu trong các trường sau: <br/>"
"Twitter"
"Website"
"Bạn đã nhận được tin nhắn từ:"
"Email của bạn"
"Tin nhắn của bạn đã được gửi đi"
"Tìm kiếm của bạn"
"Quận/Huyện"
Tiếng Anh
"An error occurred while saving your contact informations."
"An error occurred while sending your request. Please try again later."
"And his phone number:"
"Are you sure you want to remove the picture?"
"City"
"Contact information"
"Here is his email:"
"Here is his message:"
"Please enter properly the following fields: <br/>"
"Twitter"
"Website"
"You have received a message from a contact:"
"Your email"
"Your message has been sent"
"Your request"
"Zip code"
Dưới đây là ví dụ về một File ngôn ngữ mà bạn nên thực hiện:
[...]
"City";"Thành phố"
"Contact information";"Thông tin liên hệ"
"Here is his email:";"Địa chỉ Email"
"Here is his message:";"Nội dung tin nhắn"
[...]
Thiết kế
Tất cả mọi thứ bạn cần để tổ chức, sắp xếp, tương tác…. module của bạn nằm trong thư mục design
ModuleName
├─ [...]
├─ resources
│ └─ design
│ ├─ desktop
│ │ ├─ appteng
│ │ │ ├─ css
│ │ │ │ └─ job.css
│ │ │ ├─ js
│ │ │ │ └─ job.js
│ │ │ ├─ images
│ │ │ │ └─ customization
│ │ │ │ └─ layout
│ │ │ │ └─ job
│ │ │ │ ├─ layout-1.png
│ │ │ │ └─ layout-2.png
│ │ │ ├─ layout
│ │ │ │ ├─ job.xml
│ │ │ │ └─ company.xml
│ │ │ └─ template
│ │ │ ├─ company
│ │ │ │ └─ [...]
│ │ │ └─ job
│ │ │ ├─ index.phtml
│ │ │ └─ application
│ │ │ ├─ edit.css
│ │ │ ├─ edit.js
│ │ │ └─ edit.phtml
│ │ └─ flat
│ │ └─ [...] # Tiêu chuẩn thiết kế Flat của AppTeng
│ └─ email
│ ├─ layout
│ └─ template
└─ [...]
Ví dụ job.xml
Đây là thông tin được yêu cầu tối thiểu trong layout.xml mặc định, các File tập tin cần phải đặt tên riêng theo tên module của bạn, trong ví dụ này nó nên là job.xml :
<?xml version="1.0" encoding="UTF-8"?>
<layout>
<job_application_job_edit>
<views>
<content class="application_view_customization_features_edit_tabbareditor" template="application/customization/features/edit/tabbar_editor.phtml" />
<content_editor class="core_view_default" template="job/application/edit.phtml" />
</views>
</job_application_job_edit>
</layout>
Phần content là mặc định cho các tab biên tập soạn thảo Module, bạn không cần phải thay đổi nó.
Phần content_editor phải đặt trong khu vực tính năng biên tập soạn thảo template
Ví dụ: job/application/edit.phtml phải được đặt trong ModuleName/resources/design/template/job/application/edit.phtml
Lưu ý quan trọng: Sử dụng đường dẫn thư mục càng ngắn càng tốt
Bộ nhớ cache
Module cũ sẽ được lưu trữ, vì vậy mỗi khi chúng tôi thêm hoặc xóa một tập tin trong mô-đun, chúng tôi sẽ xóa các tập tin trong var/cache/design.cache
Lưu ý quan trọng: Khi chúng tôi cài đặt và/hoặc cập nhật một module thường xuyên với định dạng zip, bộ nhớ cache sẽ được tự động xóa cho người sử dụng.
Đóng gói Module
Sau khi hoàn tất Module của bạn, hãy đóng gói nó !
Nén .zip tất cả mọi thứ tại thư mục gốc của Module và bạn đã hoàn tất!
ModuleName.zip
├─ Controller
├─ controllers
│ └─[...]
├─ Model
├─ View
├─ resources
│ └─[...]
└─ package.json
Quy trình AppTeng gỡ bỏ cài đặt Module trên hệ thống:
Mỗi module cần phải đi kèm với un-installer riêng của nó, nó cần phải là tập tin duy nhất có tên uninstall.php nằm trong thư mục gốc của gói.
Tất cả được cài đặt bởi các tập tin nằm trong resources/db/data và mỗi bảng được tạo trong resources/db/schema
<?php
# Job module un-installer.
$name = "Job";
# Làm sạch thư viện icons
AppTeng_Feature::removeIcons($name);
ApTeng_Feature::removeIcons("{$name}-flat");
# Làm sạch bố trí Layouts
$layout_data = array(1, 2);
$slug = "job";
AppTeng_Feature::removeLayouts($option->getId(), $slug, $layout_data);
# Làm sạch Các Tuỳ chọn/Các module
$code = "job";
AppTeng_Feature::uninstallFeature($code);
# Làm sạch DB (Thận trọng với bước này).
$tables = array(
"job_company",
"job_place",
);
AppTeng_Feature::dropTables($tables);
# Làm sạch module
AppTeng_Feature::uninstallModule($name);
Đóng gói Module.
Nén .zip tất cả các File từ thư mục gốc của bạn. Gửi File nén .zip cho chúng tôi tới app@appteng.app
Ban kỹ thuật AppTeng sẽ kiểm tra sự phù hợp của nó trên nền tảng thử nghiệm, nếu đạt tiêu chuẩn, chúng tôi sẽ kích hoạt nó cho bạn.
Bạn đã hoàn tất.