[ English | 中文 (简体, 中国) | русский | português (Brasil) | नेपाली | 한국어 (대한민국) | Indonesia | français | español | esperanto | English (United Kingdom) | Deutsch ]

Panduan Topik AngularJS

Catatan

Panduan ini sedang dalam proses. Itu telah diunggah untuk mendorong peninjauan yang lebih cepat dan pengembangan kode di Angular, dan untuk membantu masyarakat melakukan standarisasi pada serangkaian pedoman. Ada catatan sebaris pada bagian yang kemungkinan akan segera berubah, dan dokumen akan segera diperbarui setelah perubahan apa pun.

Mulai

Perkakas untuk pengujian AngularJS dan linting kode bergantung pada npm, manajer paket simpul, dan dengan demikian bergantung pada Node.js. Meskipun bukan merupakan prasyarat untuk mengembangkan dengan Horizon, disarankan untuk menginstal Node.js, baik melalui downloading atau via a package manager.

Setelah npm tersedia di sistem Anda, jalankan npm install dari direktori root horizon.

Gaya Kode

Kami saat ini menggunakan Angular Style Guide oleh John Papa sebagai bahan referensi. Saat mengulas kode AngularJS, sebaiknya tautan langsung ke panduan gaya untuk memperkuat suatu poin, misal https://github.com/johnpapa/angular-styleguide#style-y024

ESLint

ESLint adalah alat untuk mengidentifikasi dan melaporkan pola dalam kode JS Anda, dan merupakan bagian dari tes otomatis yang dijalankan oleh Jenkins. Anda dapat menjalankan ESLint dari direktori root horizon dengan tox -e npm - lint, atau sebagai alternatif pada direktori atau file tertentu dengan eslint file.js.

Horizon menyertakan .eslintrc dalam direktori rootnya, yang digunakan oleh tes lokal. Penjelasan opsi, dan detail orang lain yang mungkin ingin Anda gunakan, dapat ditemukan di ESLint user guide.

Struktur Aplikasi

OpenStack Dashboard adalah contoh aplikasi Angular berbasis Horizon. Aplikasi lain yang dibangun pada kerangka Horizon dapat mengikuti struktur yang sama. Ini terdiri dari dua modul sudut utama:

app.module.js - Root aplikasi. Menentukan modul yang dibutuhkan oleh

aplikasi, dan termasuk modul dari dashboard yang bisa dicolokkan (pluggable).

framework.module.js - Komponen Horizon yang dapat digunakan kembali (reusable). Itu adalah salah satu

ketergantungan aplikasi.

Struktur File

Horizon memiliki tiga jenis kode angular:

  1. Khusus untuk satu dasbor di aplikasi OpenStack Dashboard

  2. Khusus untuk aplikasi OpenStack Dashboard, tetapi dapat digunakan kembali oleh beberapa dasbor

  3. Dapat digunakan kembali oleh aplikasi apa pun berdasarkan kerangka kerja Horizon

Saat menambahkan kode ke horizon, pertimbangkan apakah itu khusus dasbor atau harus dibagi sebagai utilitas atau widget yang dapat digunakan kembali.

Kode khusus untuk satu dasbor

Kode yang tidak dibagi di luar satu dashboard ditempatkan di openstack_dashboard/dashboards/mydashboard/static. Seluruh dasbor dapat diaktifkan atau dinonaktifkan menggunakan mekanisme plugin Horizon. Karenanya tidak ada dasbor selain mydashboard yang dapat menggunakan kode ini dengan aman.

Struktur direktori openstack_dashboard/dashboards/mydashboard/static menentukan bagaimana kode tersebut digunakan dan cocok dengan struktur modul. Sebagai contoh:

openstack_dashboard/dashboards/identity/static/dashboard/identity/
├── identity.module.js
├── identity.module.spec.js
└── identity.scss

Karena kode ini berada di openstack_dashboard/dashboards/identity kita tahu itu khusus untuk hanya ``identity `` dasbor dan tidak digunakan oleh orang lain.

Kode dibagikan oleh banyak dasbor

Tampilan atau utilitas yang diperlukan oleh banyak dasbor ditempatkan di openstack_dashboard/static/app. Sebagai contoh:

openstack_dashboard/static/app/core/cloud-services/
├── cloud-services.module.js
├── cloud-services.spec.js
├── hz-if-settings.directive.js
└── hz-if-settings.directive.spec.js

Modul cloud-services digunakan oleh panel di beberapa dasbor. Itu tidak dapat ditempatkan di dalam openstack_dashboard/dashboards/mydashboard karena menonaktifkan bahwa satu dasbor akan menghancurkan yang lain. Oleh karena itu, ini dimasukkan sebagai bagian dari modul core aplikasi. Kode di app/ dijamin akan selalu ada, meskipun semua dasbor lainnya dinonaktifkan.

Komponen yang dapat digunakan kembali

Akhirnya, komponen yang mudah digunakan kembali oleh aplikasi apa pun ditempatkan di horizon/static/framework/. Ini tidak mengandung URL atau logika bisnis yang khusus untuk aplikasi apa pun (bahkan aplikasi OpenStack Dashboard).

Arahan modal horizon/static/framework/widgets/modal/ adalah contoh yang baik dari komponen yang dapat digunakan kembali.

Satu folder per komponen

Setiap komponen harus memiliki folder sendiri, dengan kode dipecah menjadi satu komponen JS per file. (Lihat Single Responsibility <https://github.com/johnpapa/angular-styleguide#single-responsibility> _ dalam panduan gaya). Setiap folder dapat menyertakan gaya (*.scss), serta template (*.html) dan pengujian (*.spec.js). Anda juga dapat menyertakan contoh, dengan menambahkan .example.

Untuk komponen yang lebih besar, seperti alur kerja dengan beberapa langkah, pertimbangkan memecah kode lebih lanjut. Misalnya, alur kerja Launch Instance, memiliki satu direktori per langkah. Lihat openstack_dashboard/dashboards/project/static/dashboard/project/workflow/launch-instance/

File SCSS

File SCSS tingkat atas di openstack_dashboard/static/app/_app.scss. Ini mencakup gaya apa pun yang merupakan bagian dari aplikasi core dan dapat digunakan kembali oleh beberapa dasbor. File SCSS yang khusus untuk dasbor tertentu ditautkan ke aplikasi dengan menambahkannya dalam file yang diaktifkan dasbor itu. Sebagai contoh, _1920_project_containers_panel.py adalah file yang diaktifkan untuk panel Container Project dasbor dan termasuk:

ADD_SCSS_FILES = [
    'dashboard/project/containers/_containers.scss',
]

File styling bersifat hierarkis, dan termasuk file SCSS anak langsung. Sebagai contoh, project.scss akan menyertakan file SCSS workflow, yang pada gilirannya menyertakan setiap styling instance peluncuran:

@import "workflow/workflow";

Ini memungkinkan aplikasi untuk dengan mudah memasukkan semua styling yang diperlukan, cukup dengan memasukkan file SCSS top-level dasbor.

Struktur Modul

Modul Horizon Angular menggunakan nama yang memetakan ke struktur direktori kode sumber. Ini memberikan isolasi namespace untuk modul dan layanan, yang membuat injeksi ketergantungan lebih jelas. Ini juga mengurangi konflik kode di mana dua modul berbeda menentukan modul, layanan atau konstanta dengan nama yang sama. Sebagai contoh:

openstack_dashboard/dashboards/identity/static/dashboard/identity/
└── identity.module.js

Nama modul Angular yang disukai dalam contoh ini adalah horizon.dashboard.identity. Bagian horizon dari nama modul memetakan ke direktori static dan menunjukkan ini adalah aplikasi berbasis horizon. dashboard.identity memetakan ke folder yang dibuat dalam static. Ini memungkinkan pemetaan langsung antara nama modul angular horizon.dashboard.identity dan direktori kode sumber static\dashboard\identity.

Layanan dan konstanta dalam modul-modul ini semua harus dimulai dengan nama modul mereka untuk menghindari tabrakan injeksi ketergantungan. Sebagai contoh:

$provide.constant('horizon.dashboard.identity.basePath', path);

Arahan tidak memerlukan nama modul tetapi didorong untuk memulai dengan awalan hz. Sebagai contoh:

.directive('hzMagicSearchBar', hzMagicSearchBar);

Akhirnya, setiap modul mencantumkan modul anaknya sebagai ketergantungan. Ini memungkinkan modul root untuk dimasukkan oleh aplikasi, yang secara otomatis akan menentukan semua modul anak (child module). Sebagai contoh:

.module('horizon.framework', [
  'horizon.framework.conf',
  'horizon.framework.util',
  'horizon.framework.widgets'
])

`` horizon.framework`` menyatakan dependensi pada horizon.framework.widgets, yang mendeklarasikan dependensi pada masing-masing widget. Ini memungkinkan aplikasi untuk mengakses widget apa pun, hanya dengan bergantung pada modul horizon.framework tingkat atas.

Pengujian

  1. Buka <dev_server_ip:port>/jasmine di browser. Server pengembangan dapat dijalankan dengan tox -e runserver dari direktori root horizon; secara default, ini akan menjalankan server pengembangan di http://localhost:8000.

  2. tox -e npm dari direktori root horizon.

Pekerjaan kode linting dapat dijalankan dengan tox -e npm - lint. Jika ada banyak peringatan, Anda juga dapat menggunakan tox -e npm - lintq untuk melihat hanya kesalahan dan mengabaikan peringatan.

Untuk informasi lebih rinci, lihat Pengujian JavaScript.

Terjemahan (Internasionalisasi dan Pelokalan)

Lihat Membuat string dapat diterjemahkan untuk informasi tentang arsitektur terjemahan dan cara memastikan kode Anda dapat diterjemahkan.

Membuat panel Anda sendiri

Catatan

Bagian ini akan diperpanjang saat praktik standar diadopsi di hulu. Saat ini, mungkin berguna untuk melihat Project Images Panel sebagai referensi lengkap. Sejak Newton, ini adalah Angular secara default (disetel ke True dalam perintah ANGULAR_FEATURES di settings.py). Anda dapat melacak semua perubahan yang dilakukan pada Image Panel here

Catatan

Saat ini, nama modul Angular masih harus dideklarasi secara manual dengan ADD_ANGULAR_MODULES, bahkan ketika menggunakan penemuan file otomatis.

Bagian ini berfungsi sebagai pengantar dasar untuk menulis panel Anda sendiri untuk horizon, menggunakan AngularJS. Panel dapat disertakan dengan sistem plugin, atau mungkin merupakan bagian dari proyek hulu horizon.

Upstream (ke hulu)

File JavaScript dapat ditemukan secara otomatis, ditangani secara manual, atau campuran keduanya. Jika memungkinkan, gunakan mekanisme otomatis. Untuk menggunakan fungsi otomatis, tambahkan:

AUTO_DISCOVER_STATIC_FILES = True

ke file Anda yang diaktifkan (enabled/<plugin_name>.py). Untuk memungkinkan ini, Anda perlu mengikuti beberapa konvensi struktural:

  • File statis harus diletakkan di folder static/, yang harus ditemukan langsung di bawah folder untuk dashboard/panel/panel grup paket Python.

  • Kode JS yang mendefinisikan modul Angular harus dalam file dengan ekstensi .module.js.

  • Kode JS untuk pengujian harus dinamai dengan ekstensi .mock.js dan dari .spec.js.

  • Templat sudut harus memiliki ekstensi .html.

Anda dapat membaca lebih lanjut tentang fungsi di :ref: auto_discover_static_files dari dokumentasi pengaturan.

Untuk menambahkan file secara manual, tambahkan array dan path file berikut ke file yang diaktifkan:

ADD_JS_FILES = [
  ...
  'path-to/my-angular-code.js',
  ...
]

ADD_JS_SPEC_FILES = [
  ...
  'path-to/my-angular-code.spec.js',
  ...
]

ADD_ANGULAR_MODULES = [
  ...
  'my.angular.code',
  ...
]

Plugins

Tambahkan panel/ panel group/ dasbor baru (Lihat :ref: tutorials-dashboard). Penyertaan file JavaScript sama dengan proses Upstream.

Untuk memasukkan stylesheet eksternal, Anda harus memastikan bahwa ADD_SCSS_FILES didefinisikan dalam file yang diaktifkan, dan tambahkan filepath yang relevan, seperti di bawah ini:

ADD_SCSS_FILES = [
  ...
  'path-to/my-styles.scss',
  ...
]

Catatan

Kami sangat merekomendasikan menggunakan file SCSS tunggal untuk plugin Anda. SCSS mendukung nesting dengan @import, jadi jika Anda memiliki banyak file (misal per panel styling) yang terbaik adalah mengimpor semuanya menjadi satu, dan memasukkan satu file itu. Anda dapat membaca lebih lanjut di SCSS documentation.

Schema Forms

JSON schemas digunakan untuk mendefinisikan tata letak model dan kemudian angular-schema-form digunakan untuk membuat formulir dari skema itu. Horizon menambahkan beberapa fungsionalitas di atasnya untuk menjadikan segalanya lebih mudah melalui ModalFormService yang akan membuka modal dengan formulir di dalamnya.

Contoh yang sangat sederhana:

var schema = {
  type: "object",
  properties: {
    name: { type: "string", minLength: 2, title: "Name", description: "Name or alias" },
    title: {
      type: "string",
      enum: ['dr','jr','sir','mrs','mr','NaN','dj']
    }
  }
};
var model = {name: '', title: ''};
var config = {
  title: gettext('Create Container'),
  schema: schema,
  form: ['*'],
  model: model
};
ModalFormService.open(config).then(submit);   // returns a promise

function submit() {
  // do something with model.name and model.title
}