diff --git a/docs/frontend/05-angular.md b/docs/frontend/05-angular.md new file mode 100644 index 00000000..82cfcacc --- /dev/null +++ b/docs/frontend/05-angular.md @@ -0,0 +1,591 @@ +--- +title: Angular +description: انگولار، جایی که بایندینگ‌ها بیشتر از ستاره‌های آسمون می‌درخشن +tags: [ Angular,NodeJs ] +--- + +# Angular + +## Web Frameworks + +یک فریمورک وب مجموعه‌ای از ابزارها، کتابخانه‌ها و الگوهای آماده است که برای توسعه سریع‌تر و کارآمدتر برنامه‌های وب +استفاده می‌شود. این فریمورک‌ها ساختار و چارچوبی مشخص فراهم می‌کنند که به توسعه‌دهندگان کمک می‌کند تا کدهای خود را به‌طور +سازمان‌یافته بنویسند، وظایف رایج مانند مسیریابی، مدیریت وضعیت، و تعامل با سرور را ساده کنند و همچنین از ابزارهای +بهینه‌سازی و تست برای بهبود کیفیت و عملکرد برنامه‌ها بهره‌مند شوند. +استفاده از فریمورک‌های وب مانند +React +و +Angular +به دلیل فراهم کردن ساختار و الگوی مشخص، افزایش بهره‌وری و سرعت توسعه، وجود جامعه‌ی کاربری بزرگ و پشتیبانی، و بهینه‌سازی +عملکرد کد توصیه می‌شود. این فریمورک‌ها مدیریت پروژه‌های بزرگ‌تر و پیچیده‌تر را آسان‌تر کرده و ابزارهای مناسبی برای تست و +نگهداری کد فراهم می‌کنند. در مقابل، جاوااسکریپت خام برای پروژه‌های کوچک مناسب‌تر است و در پروژه‌های بزرگ به سرعت پیچیده +می‌شود. + +## چرا Angular + +از این فریمورک استفاده می‌کنیم چون ساختار ماژولار و قابلیت‌های داخلی جامعی دارد که توسعه برنامه‌های پیچیده را ساده و +سریع می‌کند. همچنین، این فریمورک +قابلیت تست‌پذیری بالا و عملکرد بهینه‌ای ارائه می‌دهد که کیفیت و پایداری برنامه‌ها را تضمین می‌کند. + +## مقدمه‌ای بر Angular + +[Angular](https://angular.io/) یک فریمورک و پلتفرم برای ساخت برنامه‌های تک‌صفحه‌ای +(SPA +یا +Single Page Application) +با +استفاده از +HTML +و +TypeScript +است. این فریمورک توسط گوگل توسعه داده شده و نگهداری می‌شود و ابزارها و معماری محکمی را برای +ساخت برنامه‌های قابل گسترش ارائه می‌دهد. + +### ویژگی‌ها و مزایای کلیدی Angular + +- **TypeScript** + Angular + با + TypeScript + نوشته شده است که یک + SuperSet + بر + JavaScript + است و ویژگی‌های زیادی از جمله تایپ استاتیک را به زبان اضافه می‌کند. + +- **Templating** + Angular + از یک سیستم طراحی + template + پیشرفته استفاده می‌کند که به شما این امکان را می‌دهد تا بتوانید به راحتی داده‌های پویا را به + template + متصل کنید. + +- **Component / Directive** + با استفاده از دایرکتیوها و کامپوننت‌ها می‌توانید رفتارها و نماهایی با قابلیت استفاده مجدد ایجاد کنید. + +**** + +# مرور کلی بر Angular + +Angular +از مفاهیم و ابزارهای متعددی تشکیل شده که به توسعه‌دهندگان کمک می‌کند تا برنامه‌های وب پیچیده را به روشی ماژولار و +ساختاریافته توسعه دهند. در اینجا برخی از مفاهیم کلیدی و اجزای اصلی +Angular +آورده شده است: + +- **ماژول‌ها (Modules)** + هر برنامه + Angular + از یک یا چند ماژول تشکیل شده است. ماژول‌ها به سازماندهی کد و مدیریت وابستگی‌ها کمک می‌کنند. + +- **کامپوننت‌ها (Components)** + کامپوننت‌ها بلوک‌های ساختمانی اصلی یک برنامه + Angular + هستند. هر کامپوننت شامل یک کلاس + TypeScript، + یک قالب + HTML + و یک فایل + CSS + است. + +- **دایرکتیوها (Directives)** + دایرکتیوها به شما امکان می‌دهند تا رفتارهای خاصی را به المان‌های انگولار اضافه کنید. + +- **سرویس‌ها (Services)** + سرویس‌ها برای مدیریت منطق و تبادل داده‌ها بین کامپوننت‌ها استفاده می‌شوند. + +- **تزریغ وابستگی (Dependency Injection)** + تزریغ وابستگی یک + Design Pattern + است که در + Angular + برای مدیریت وابستگی‌ها استفاده می‌شود. + +- **روتر (Router)** + روتر به شما امکان می‌دهد تا بین نماهای مختلف در برنامه جابه‌جا شوید. + +### پیش‌نیازها + +پیش از هر چیزی برای یادگیری انگولار شما باید با ابزار +npm +(Node Package Manager) +آشنا شوید. +این ابزار، برای مدیریت بسته‌های پروژه شماست، +شما می‌توانید از ابزار‌های دیگری همچون +yarn،pnpm +برای مدیریت بسته‌ها استفاده کنید. + +- [نصب node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) +- [همه چیز درباره node.js](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/) +- [پکیچ منیجر های دیگر](https://romanglushach.medium.com/comparing-npm-yarn-and-pnpm-package-managers-which-one-is-right-for-your-distributed-project-to-4d7de2f0db8e) + +بعد از آشنایی با پکیج منیجرها نیاز است شما با نحوه ساخت و راه‌اندازی یک پروژه انگولار و سپس ساختار آن آشنا شوید. + +- [نصب و راه‌اندازی Angular](https://v17.angular.io/guide/setup-local) +- [ساختار پروژه](https://dev.to/tomwebwalker/angular-starting-files-explanation-for-beginners-15cp) +- [فایل angular.json](https://dev.to/tomwebwalker/angularjson-structure-for-beginners-what-we-can-set-27f3) + +# مفاهیم اساسی Angular + +## Components + +کامپوننت‌ها بلوک‌های ساختمانی اصلی برنامه‌های +Angular +هستند. هر کامپوننت شامل یک کلاس +TypeScript، +یک قالب +HTML +و یک فایل +سبک +CSS +است. کامپوننت‌ها به شما امکان می‌دهند تا بخش‌های مختلف برنامه را به صورت مجزا توسعه داده و مدیریت کنید. + +برای ساخت کامپوننت از +`@Component` +استفاده می‌کنیم. در این +decorator +مشخصه +`selector` +مشخص می‌کند که این کامپوننت با چه +تگی در HTML استفاده خواهد شد، +`template` +قالب HTML کامپوننت را تعریف می‌کند، و +`styles` +استایل‌های CSS مربوط به کامپوننت +را مشخص می‌کند. + +### مثال از یک کامپوننت ساده + +در این مثال، یک کامپوننت ساده به نام +`HelloWorldComponent` +ایجاد می‌کنیم که یک پیام +“Hello, World!” +را نمایش می‌دهد. +برای ایجاد یک کامپوننت جدید با استفاده از +Angular CLI، +دستور زیر را در ترمینال اجرا کنید: + +```sh +ng generate component hello-world +``` + +یا به صورت مختصر: + +```sh +ng g c hello-world +``` + +این دستور در هر دایرکتوری اجرا شود به صورت خودکار دایرکتوری جدید شامل فایل +HTML، CSS، TypeScript +و فایل تست تشکیل +می‌دهد. (برای نام گذاری +componentها +از قرارداد +`name.component.ts` +و برای تست از +`name.component.spec.ts` +استفاده +می‌شود) + +فایل +`hello-world.component.ts` +به این صورت خواهد بود: + +```typescript +import {Component} from '@angular/core'; + +@Component({ + selector: 'app-hello-world', + template: '

Hello, World!

', + styles: ['h1 { color: blue; }'] +}) +export class HelloWorldComponent { +} +``` + +در این مثال: + +- `selector` + مشخص می‌کند که این کامپوننت با استفاده از تگ + `` + در HTML استفاده خواهد شد. +- `template` + قالب HTML کامپوننت را تعریف می‌کند. +- `styles` + استایل‌های CSS مربوط به کامپوننت را تعریف می‌کند. + +برای استفاده از این کامپوننت در برنامه، می‌توانید تگ +`` +را به قالب +`app.component.html` +اضافه کنید: + +```html + + +``` + +حال با اجرای مجدد پروژه، کامپوننت ساخته شده نمایش داده می‌شود. + +برای مطالعه بیشتر به [مستندات رسمی](https://angular.dev/api/core/Component#viewProviders) انگولار مراجعه کنید. + +## Dependency injection + +Dependency Injection +یا تزریق وابستگی‌ها یک تکنیک است که یک شئ وابستگی‌های شئ دیگر را تامین (تزریق) می‌کند. که این +فرآیند توسط انگولار انجام می‌شود + +- [آشنایی با تزریق وابستگی در انگولار](https://www.youtube.com/watch?v=G8zXugcYd7o&list=PLX7eV3JL9sfmJ6AaZj9eDlAKrJrEul4Vz) + +## Services + +سرویس‌ها +(Services) +در انگولار یکی از اصول اصلی و مهم این فریم‌ورک هستند که برای مدیریت منطق و داده‌های اپلیکیشن استفاده +می‌شوند. سرویس‌ها به طور معمول برای انجام کارهایی مثل درخواست‌های +HTTP، +ذخیره و بازیابی داده‌ها، و به اشتراک‌گذاری +داده‌ها بین کامپوننت‌ها به کار می‌روند. این مفهوم به منظور تفکیک منطق کسب و کار از رابط کاربری +(UI) +به کار گرفته می‌شود. + +### تعریف سرویس + +برای ایجاد یک سرویس در انگولار، ابتدا باید یک کلاس ایجاد کرده و سپس این کلاس را با استفاده از دکوراتور +`@Injectable` +تزریق‌پذیر +(injectable) +کنید. به عنوان مثال، یک سرویس ساده برای مدیریت کاربران را در نظر بگیرید: + +```typescript +import {Injectable} from '@angular/core'; + +@Injectable({ + providedIn: 'root', +}) +export class UserService { + private users = ['Alice', 'Bob', 'Charlie']; + + constructor() { + } + + getUsers() { + return this.users; + } + + addUser(user: string) { + this.users.push(user); + } +} +``` + +### استفاده از سرویس در کامپوننت + +برای استفاده از این سرویس در یک کامپوننت، باید آن را در +constructor +کامپوننت تزریق +(inject) +کنید: + +```typescript +import {Component, OnInit} from '@angular/core'; +import {UserService} from './user.service'; + +@Component({ + selector: 'app-user', + template: ` +
+
    +
  • {{ user }}
    • +
+ + +
+ `, +}) +export class UserComponent implements OnInit { + users: string[] = []; + newUser: string = ''; + + constructor(private userService: UserService) { + } + + ngOnInit() { + this.users = this.userService.getUsers(); + } + + addUser() { + this.userService.addUser(this.newUser); + this.newUser = ''; + } +} +``` + +### توضیح: + +1. **ایجاد سرویس**: یک کلاس با نام + `UserService` + ایجاد می‌شود و از دکوراتور + `@Injectable` + استفاده می‌کند تا انگولار + بفهمد این کلاس قابل تزریق است. +2. **متدهای سرویس**: این سرویس دو متد + `getUsers` + و + `addUser` + دارد که به ترتیب کاربران را بازیابی و اضافه می‌کنند. +3. **تزریق سرویس در کامپوننت**: در کلاس + `UserComponent` + سرویس + `UserService` + در + constructor + تزریق می‌شود. +4. **استفاده از سرویس**: در متد + `ngOnInit`، + متد + `getUsers` + سرویس فراخوانی می‌شود تا لیست کاربران دریافت شود. همچنین، + متد + `addUser` + برای افزودن کاربر جدید به لیست استفاده می‌شود. + +## pipe + +پایپ +(Pipe) +در +Angular +یک ویژگی است که برای تبدیل داده‌ها قبل از نمایش در قالب نهایی استفاده می‌شود. این کاربرد اصلی آن +است که اطلاعات را به یک فرمت مشخص یا به صورتی خاصی نمایش دهد، مثلا تبدیل یک تاریخ به فرمت خاص، نمایش مقادیر اعشاری به +تعداد معین اعشار، تبدیل متن به حروف بزرگ یا کوچک و غیره. + +برای استفاده از پایپ در +Angular، +ابتدا باید پایپ مورد نظر را ایجاد کنید یا از پایپ‌های تعریف شده پیش فرض استفاده کنید. +سپس آن را در قالب مورد نظرتان به صورت خاصی اعمال می‌کنید. + +**مثال:** + +اگر بخواهیم یک زمان را به فرمت داده شده تبدیل کنیم، از پایپ +`DatePipe` +استفاده می‌کنیم: + +```html +

تاریخ امروز: {{ today | date:'hh:mm:ss' }}

+``` + +در این مثال، +`today` +یک متغیر در کامپوننت +Angular +است که تاریخ فعلی را نگهداری می‌کند. +`date` +یک پایپ است که تاریخ را به +فرمت +"hh:mm:ss" +تبدیل می‌کند و نمایش می‌دهد. + +پایپ‌ها در +Angular +به طور گسترده‌ای برای فراهم کردن قابلیت‌های فرمت‌بندی و تغییر شکل داده‌ها استفاده می‌شوند و می‌توانند +به آسانی سفارشی‌سازی شوند یا از پایپ‌های پیش‌فرض +Angular +استفاده شود. + +برای مثال پایپ زیر با توجه به ژانر ورودی لیست کتاب هارا فیلتر می‌کند. +```ts +import {Pipe, PipeTransform} from '@angular/core'; +import {Book} from './book.model'; + +@Pipe({ + name: 'genreFilter', +}) +export class GenreFilterPipe implements PipeTransform { + transform(books: Book[], genre: string): Book[] { + if (!genre) { + return books; + } + return books.filter(book => book.genre === genre); + } +} +``` + +در این پایپ،‌ متد +transform +لیست کتاب ها و ژانر را به عنوان ورودی دریافت کرده و لیست فیلتر شده شامل کتاب هایی که تنها در ژانر ورودی هستند برمی‌گرداند. + +## Decorators + +پیش از آنکه به توضیح بخش‌های اصلی +Angular +بپردازیم، بهتر است با مفهوم اساسی +Decorator +که به طور گسترده از آن در تعاریف +مختلف +Angular +استفاده می‌شود، آشنا شویم. + +decorator +ها در +Angular +یک نوع خاص از توابع هستند که به شما امکان می‌دهند تا به کلاس‌ها، متدها، ویژگی‌ها یا پارامترها +متادیتا اضافه کنید و رفتار آنها را +Override +کنید. +Decorator +ها در +TypeScript +به طور گسترده‌ای برای تعریف ویژگی‌ها و +رفتارهای اجزای مختلف +Angular +استفاده می‌شوند. این توابع توسط +`@` +فراخوانی می‌شوند و ورودی‌های خود را دریافت می‌کنند و +تغییرات لازم را بر روی هدف خود اعمال می‌کنند. + +### Angular Decorators + +دیکوریتورهای اصلی Angular عبارتند از: + +- **@NgModule**: + برای تعریف ماژول‌های + Angular + استفاده می‌شود. +- **@Component**: + برای تعریف کامپوننت‌ها استفاده می‌شود. +- **@Directive**: + برای تعریف دستورالعمل‌ها استفاده می‌شود. +- **@Pipe**: + برای تعریف لوله‌ها (فیلترها) استفاده می‌شود. +- **@Injectable**: + برای تعریف سرویس‌ها استفاده می‌شود. + +هر کدام از این دیکوریتورها وظایف خاصی دارند و به شما کمک می‌کنند تا ویژگی‌های خاصی را به اجزای برنامه اضافه کنید. + +- [decorator های پر استفاده در انگولار](https://medium.com/@madhavmahesh/list-of-all-decorators-available-in-angular-71bdf4ad6976) + +## Angular Modules + +انگولار یک فریم‌ورک ماژولار است. ماژولاریتی خاصیتی است که میزان جداپذیری اجزا درون یک سیستم را اندازه‌گیری می‌کند، به +طوری که این اجزا می‌توانند به عنوان یک واحد مستقل عمل کنند و بدون وابستگی به یکدیگر کار کنند. در انگولار، ماژول یک واحد +است که کامپوننت‌ها، پایپ‌ها، دایرکتیوها و سرویس‌ها را گروه‌بندی می‌کند. یک برنامه انگولار می‌تواند شامل چندین ماژول +باشد. در هر برنامه انگولار حداقل یک ماژول وجود دارد. +NgModule +پیش‌فرض +AppModule +است و در فایل +app.module.ts +قرار دارد. +وقتی برنامه را اجرا می‌کنید، این ماژول اجرا می‌شود. شما همچنین می‌توانید عملکردها را از یک ماژول به ماژول دیگر +import +و +export +کنید. + +- [مطالعه درباره ماژول‌ها در انگولار](https://medium.com/ngconf/an-introduction-to-ngmodules-6061241e75e1) +- [نحوه استفاده از NgModule](https://youtube.com/watch?v=oqZ4-ULwfbc) + +## Templates and Data Binding + +### Interpolation + +در +Angular، +Interpolation +به معنی نشان دادن داده‌های کامپوننت در قالب کامپوننت است. این کار با استفاده از +`{{ }}` +انجام +می‌شود. + +```html +

{{ title }}

+``` + +در این مثال، +`title` +یک +property +از کامپوننت است که مقدار آن در قالب نمایش داده می‌شود. لازم به ذکر است هر تغییر در +مقدار +`title` +به طور خودکار توسط +Angular +تشخیص داده شده و در نتیجه قالب به صورت خودکار بروز می‌شود. (البته این در صورتی +است که در +Change Detection +تغییری انجام نشده باشد که در بخش‌های آینده از آن صحبت خواهیم کرد) + +### Property Binding + +در Angular، +می‌توانید +Propertyهای +کامپوننت را به عناصر قالب متصل کنید. این کار با استفاده از +`[ ]` +انجام می‌شود. + +```html + +``` + +در این مثال، `imageUrl` یک property از کامپوننت است که به ویژگی `src` عنصر `` متصل می‌شود. + +### Event Binding + +#### مفهوم Event + +در جاوااسکریپت، مفهوم "رویداد" +(Event) +به هر اتفاق یا کنشی که در مرورگر رخ می‌دهد اطلاق می‌شود. این رویدادها می‌توانند توسط کاربر (مثل کلیک کردن، فشردن کلید، +حرکت ماوس) یا توسط مرورگر (مثل بارگذاری صفحه، تغییر اندازه صفحه) رخ دهند. + +در +Angular، +می‌توانید +eventها +را در template مدیریت کنید و به متدهارا به event ها متصل کنید. این کار با استفاده از +`( )` +انجام +می‌شود. + +```html + + +``` + +در این مثال، وقتی کاربر بر روی دکمه کلیک می‌کند، متد +`handleClick()` +کامپوننت فراخوانی می‌شود. + +### Two Way Binding + +[Two Way Binding](https://angular.dev/guide/templates/two-way-binding) +به منظور اشتراک داده بین کامپوننت‌های انگولاری استفاده می‌شود، به صورتی که تغییر مقدار داده‌ها به صورت همزمان هم در +کامپوننت پدر و هم فرزند انجام می‌شود. + +- [Demystifying Angular Two Way Binding](https://www.youtube.com/watch?v=vkmwbZV-ob8) + +### angular routing + +‌ابزار قدرتمند انگولار برای جابه‌جایی بین صفحات مختلف استفاده می‌شود. + +- [مستندات روتینگ انگولار](https://angular.dev/guide/routing/common-router-tasks) + +## تثبیت دانش + +برای تثبیت مطالبی که تا اینجا آموختید ، پیشنهاد می‌شود که پروژه ` Book Collection Manager ` را انجام دهد. + +این پروژه شامل مدیریت یک مجموعه کتاب شخصی است که کاربران می‌توانند کتاب‌های خود را اضافه، مشاهده، ویرایش و حذف کنند. هر +کتاب دارای عنوان، نویسنده، تاریخ انتشار و ژانر است. در این پروژه، از مفاهیم و تکنولوژی‌های Angular از جمله کامپوننت‌ها، +سرویس‌ها و پایپ‌ها استفاده خواهد شد. + +این پروژه به شما این امکان را می‌دهد تا تجربه عملی کسب کنید در: + +ایجاد و مدیریت کامپوننت‌ها و ارتباط آنها با یکدیگر. +استفاده از سرویس‌ها برای مدیریت داده‌ها و انجام عملیات CRUD (ایجاد، خواندن، به روزرسانی، حذف). +اعمال پایپ‌ها برای فرمت‌بندی و فیلتر کردن داده‌ها. +این پروژه می‌تواند فرصتی عالی باشد تا مهارت‌های یادگرفته شده را در یک محیط عملی تثبیت کنید و آمادگی خود را برای +پروژه‌های واقعی و بزرگ‌تر افزایش دهید. \ No newline at end of file diff --git a/docs/frontend/phase01-sandbox.md b/docs/frontend/phase01-sandbox.md deleted file mode 100644 index 91f55dc8..00000000 --- a/docs/frontend/phase01-sandbox.md +++ /dev/null @@ -1,446 +0,0 @@ ---- -title: Sandbox -description: When I was a kid, my mom used to just throw me into a pile of broken glass! -tags: [Sandbox] ---- - -:::info این فاز، یکی از فازهای `Sandbox` است. - -به فازهایی `Sandbox` می‌گوییم که به طور مستقیم به پروژه مربوط نمی‌شوند -و در کارگاهی که برای آن‌ها برگزار می‌شود، مدرس در یک محیط ایزوله به تدریس می‌پردازد. -البته این به آن معنا نیست که در این فازها نکات کم‌اهمیتی گفته می‌شود؛ -بلکه در آن‌ها نکات مهمی تعبیه شده که در فازهای دیگر قابل بیان نبودند. - -::: - -## مقدمه - -در این فاز قصد داریم قبل از شروع پروژه با برخی نکات ساده اما مهم آشنا شویم -که در ادامۀ کار به کمک ما خواهند آمد. - -- چرا برای تعریف متغیر می‌توان از سه عبارت `var` و `let` و `const` استفاده کرد؟ -- تفاوت Function با Arrow Function چیست؟ -- مفهوم و کاربرد `this` چیست؟ -- صفت `type` در تگ `script` چیست؟ -- چطور می‌توان از کدی که دیگران نوشته‌اند استفاده کرد؟ -- برای افزایش خوانایی کد چه کارهایی می‌توان انجام داد؟ - ---- - -## یادگیری - -### متغیرها - -قبل از سال 2015 میلادی، برای تعریف متغیر در JavaScript تنها می‌توانستیم از `var` استفاده کنیم. -اما با معرفی ES6 عبارت‌های `let` و `const` نیز به این زبان اضافه شدند که در اینجا توضیحات مختصری در مورد هر کدام ارائه می‌کنیم. - -#### var - -زمانی که یک متغیر را با عبارت `var` تعریف می‌کنید، -آن متغیر در Global Scope یا نزدیک‌ترین Function Scope تعریف می‌شود. - -به عنون مثال خروجی کد زیر: - -```javascript -function defineAndPrintName() { - if (true) { - var name = 'Bijan'; - console.log(`inner scope -> name: ${name}`); - } - - console.log(`outer scope -> name: ${name}`); -} - -defineAndPrintName(); -``` - -به شکل زیر خواهد بود: - -```text -inner scope -> name: Bijan -outer scope -> name: Bijan -``` - -چرا که متغیر `name` داخل اسکوپِ تابعِ `defineAndPrintName` قرار می‌گیرد. - -لازم به ذکر است که Scopeها در JavaScript با آکلاد مشخص می‌شوند -بنابراین نیازی به `if (true)` نداریم. - -#### let - -برخلاف `var`، زمانی که از `let` برای تعریف یک متغیر استفاده کنیم، -آن متغیر در Scope فعلی محدود می‌شود. - -به‌عنوان مثال خروجی کد زیر: - -```javascript -function defineAndPrintName() { - { - let name = 'Bijan'; - console.log(`inner scope -> name: ${name}`); - } - - console.log(`outer scope -> name: ${name}`); -} - -defineAndPrintName(); -``` - -به شکل زیر خواهد بود: - -```text -inner scope -> name: Bijan -ReferenceError: name is not defined -``` - -#### const - -`const` -دقیقاً مانند `let` عمل می‌کند با این تفاوت که فقط یک بار می‌توان آن را مقداردهی کرد. -زمانی که احتیاج داشته باشیم مقداری را ذخیره کنیم که هیچ‌وقت نباید تغییر کند، -استفاده از `const` باعث جلوگیری از خطاهای احتمالی می‌شود؛ -همچنین زمانی که شخص دیگری کد را می‌خواند، -با دیدن `const` مطمئن می‌شود که مقدار آن تغییر نخواهد کرد. -ما پیشنهاد می‌کنیم همیشه به صورت پیش‌فرض برای تعریف متغیرها از `const` استفاده کنید -و تنها در صورت نیاز به `let` مراجعه کنید. - -برای آشنایی بیشتر با این مفاهیم می‌توانید از لینک‌های زیر استفاده کنید: - -- [var vs let vs const in JavaScript](https://ui.dev/var-let-const/) -- [Medium - Difference Between Var, Let and Const in ES6](https://medium.com/infancyit/difference-between-var-let-and-const-in-es6-16a08d74b8b2) -- [freeCodeCamp - Var, Let, and Const – What's the Difference?](https://www.freecodecamp.org/news/var-let-and-const-whats-the-difference/) - ---- - -### Regular Function vs Arrow Function - -در JavaScript به دو شکل می‌توان یک تابع را تعریف کرد: - -```javascript -function sayHello(name) { - console.log(`hello, ${name}!`); -} - -// or - -const sayHello = (name) => { - console.log(`hello, ${name}!`); -}; -``` - -که به نوع اول Regular Function و به نوع دوم Arrow Function گفته می‌شود. -در اینجا به تفاوت این دو روش می‌پردازدیم. - -#### this - -زمانی که از Regular Function استفاده می‌کنیم مقدار `this` با توجه به مکانی که تابع از آنجا صدا زده می‌شود، متفاوت است. -اما اگر از Arrow Function استفاده کنیم، این مقدار همواره برابر با شیئی است که تابع در آن تعریف شده. - -```javascript -const regularFunctionWrapper = { - whatIsThis: function () { - console.log(this); // regularFunctionWrapper - }, -}; - -const arrowFunctionWrapper = { - whatIsThis: () => { - console.log(this); // globalThis - }, -}; - -regularFunctionWrapper.whatIsThis(); -arrowFunctionWrapper.whatIsThis(); -``` - -#### Constructor - -قبل از اینکه کلاس‌ها به JavaScript بیایند، از Regular Function به‌عنوان Constructor استفاده می‌شد: - -```javascript -function Circle(radius) { - this.radius = radius; - - this.printArea = function () { - console.log('area', Math.PI * Math.pow(this.radius, 2)); - }; -} - -const small = new Circle(10); -const large = new Circle(100); - -small.printArea(); -large.printArea(); -``` - -#### arguments & args - -در Regular Function یک کلیدواژه به نام arguments وجود دارد که درواقع آرایه‌ای از پارامترهای ورودی می‌باشد؛ -در Arrow Function هم می‌توانیم به این پارامترها دسترسی داشته باشیم اما باید صراحتاً در ورودی‌های تابع به آن اشاره کنیم: - -```javascript -function regularFunctionSum() { - let result = 0; - - for (const n of arguments) { - if (!isNaN(n)) result += n; - } - - return result; -} - -const arrowFunctionSum = (...args) => { - let result = 0; - - for (const n of args) { - if (!isNaN(n)) result += n; - } - - return result; -}; - -console.log('Regular Function', regularFunctionSum(4, 8, 15, 16, 23, 42)); // 108 -console.log('Arrow Function', arrowFunctionSum(4, 8, 15, 16, 23, 42)); // 108 -``` - -#### return - -در Arrow Function اگر بدنۀ تابع فقط شامل یک Expression باشد، می‌توان آن را بدونِ استفاده از آکلاد و return نوشت: - -```javascript -const rand = (min, max) => Math.floor(Math.random() * (max - min) + min); - -console.log(rand(4, 42)); -``` - -برای آشنایی بیشتر با این مفاهیم می‌توانید از لینک‌های زیر استفاده کنید: - -- [5 Differences Between Arrow and Regular Functions](https://dmitripavlutin.com/differences-between-arrow-and-regular-functions/) -- [freeCodeCamp - When (and why) you should use ES6 arrow functions — and when you shouldn’t](https://www.freecodecamp.org/news/when-and-why-you-should-use-es6-arrow-functions-and-when-you-shouldnt-3d851d7f0b26/) - ---- - -### Modules - -#### type - -یکی از صفاتی که می‌توان به تگ `script` اضافه کرد، `type` است؛ -این صفت همان‌طور که از اسمش پیداست، مشخص می‌کند که مرورگر چگونه با کد شما برخورد کند. -مقادیر متنوعی را می‌توان برای `type` در نظر گرفت اما در اینجا فقط به `module` اشاره می‌کنیم. - -```html - -``` - -#### مزایا - -یکی از بزرگ‌ترین مزایای استفاده از `module` این است که می‌توانید کد خود را به چند فایل تقسیم کنید -و هر فایل را برای کار خاصی در نظر بگیرید. -به‌عنوان مثال فرض کنید بخواهیم دو کلاس با نام‌های `Circle` و `Square` داشته باشیم، -اشیائی با آن‌ها بسازیم و در نهایت محیط و مساحت هر کدام را محاسبه کنیم؛ -از سه راه می‌توانیم به هدف خود برسیم: - -1. قرار دادن تمام کدها در یک فایل -1. قرار دادن کد هر قسمت در یک فایل جدا و استفاده از سه تگ `script` در HTML -1. قرار دادن کد هر قسمت در یک فایل جدا و استفاده از `module` - -واضح است که روش اول خوانایی کد را به‌شدت پایین می‌آورد -و اگر در آینده بخواهیم توسعه‌ای انجام دهیم، باید در میان حجم انبوهی از کدها به دنبال قسمت مورد نظر بگردیم. - -روش دوم بهتر است اما مشکلی که وجود دارد این است که -همیشه باید به ترتیبِ کدها توجه کنیم. -به‌عنوان مثال اگر بخواهیم از کد `Square` داخل `main` استفاده کنیم، -باید حتماً تگ مربوط به `Square`، قبل از تگ مربوط به `main` باشد. - -اما روش سوم هیچ‌کدام از معایب دو روش دیگر را ندارد. -به راحتی می‌توان هر زمان که به یک کد احتیاج داشتیم، آن را `import` کنیم -و فقط یک تگ `script` در HTML قرار می‌دهیم. - -برای روشن‌تر شدن موضوع، در ادامه کد روش سوم را می‌بینیم: - -```html title="index.html" - -``` - -```javascript title="main.js" -import {Circle} from './circle.js'; -import {Square} from './square.js'; - -const main = () => { - const circle = new Circle(10); - const square = new Square(10); - - console.log(circle.toString()); - console.log(square.toString()); -}; - -main(); -``` - -```javascript title="circle.js" -class Circle { - #radius; - - constructor(radius) { - this.#radius = Number.parseInt(radius) || 0; - } - - calculatePerimeter() { - return 2 * Math.PI * this.#radius; - } - - calculateArea() { - return Math.PI * this.#radius * this.#radius; - } - - toString() { - return `(Circle) perimeter: ${this.calculatePerimeter()}; area: ${this.calculateArea()}`; - } -} - -export {Circle}; -``` - -```javascript title="square.js" -class Square { - #side; - - constructor(side) { - this.#side = Number.parseInt(side) || 0; - } - - calculatePerimeter() { - return 4 * this.#side; - } - - calculateArea() { - return this.#side * this.#side; - } - - toString() { - return `(Square) perimeter: ${this.calculatePerimeter()}; area: ${this.calculateArea()}`; - } -} - -export {Square}; -``` - -#### import & export - -همان‌طور که در کد قسمت قبل مشاهده کردید، -برای آنکه بتوانیم به یک موجودیت (متغیر، تابع، کلاس و ...) در قسمت‌های دیگر پروژه دسترسی داشته باشیم، -باید از کلیدواژه‌های `import` و `export` استفاده کنیم. - -در قسمت قبل، یک Object را `export` کردیم که تنها شامل یک عنصر با کلید `Circle` یا `Square` بود؛ -بنابراین زمانی که بخواهیم فایل را `import` کنیم، دقیقاً همان Object را به همان شکل در دسترس خواهیم داشت. -همچنین این امکان را داریم که یک موجودیت را به‌عنوان شیء پیش‌فرض `export` کنیم -یا اسامی اشیاء را هنگام `import` عوض کنیم. - -برای آشنایی بیشتر با این مفاهیم می‌توانید از لینک‌های زیر استفاده کنید: - -- [MDN - export](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export/) -- [MDN - import](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/import/) - ---- - -### Node.js & npm - -با استفاده از `import` می‌توانید کتابخانه‌هایی را که دیگران توسعه داده‌اند، به کد خود اضافه کنید. -برای این کار مرسوم‌ترین روش استفاده از یک Package Manager است که معروف‌ترینِ آن‌ها npm می‌باشد. - -#### Setup - -برای استفاده از npm باید ابتدا با مراجعه به -[این لینک](https://nodejs.org/)، -Node.js را نصب کنید. - -Node.js -یک Runtime Environment است که به ما این امکان را می‌دهد که بتوانیم کد JavaScript را بدونِ نیاز به مرورگر اجرا کنیم. -از Node.js معمولاً برای برنامه‌نویسی سمت سرور استفاده می‌شود که ما در این دوره به آن نمی‌پردازیم -و صرفاً از npm استفاده خواهیم کرد. - -#### Package Installation - -برای پیداکردن پکیج‌های مختلف می‌توانید به -[سایت npm](https://www.npmjs.com/) -مراجعه کنید. - -برای نصب پکیج‌ها، کافی است دستوری مشابه دستور زیر را در ترمینال بنویسید: - -```shell -npm i package-name -``` - -همچنین در صورتی که پکیج مورد نظر صرفاً توسط توسعه‌دهندگان مورد استفاده قرار می‌گیرد -و برای خروجی گرفتن از پروژه احتیاجی به آن نیست، -می‌توانید از پارامتر `D` هنگام نصب استفاده کنید: - -```shell -npm i -D package-name -``` - -با این کار، زمانی که بخواهید پروژه را بر روی Production ببرید، -پکیج‌های غیرضروری نصب نخواهند شد و فرآیند Deploy سریع‌تر انجام می‌شود. - -#### Prettier - -یکی از پکیج‌های بسیار محبوب Prettier است. -Prettier -به شما کمک می‌کند تا قواعدی را برای فرمت‌کردن کد تعریف کنید. -باید دقت داشته باشید که Prettier یک فرمترِ Opinionated است؛ -به این معنا که توسعه‌دهندگان آن، با توجه به Conventionهای موجود و سلیقۀ خود، قواعد را تنظیم کرده‌اند؛ -با این حال می‌توانید برخی از این قواعد را تغییر دهید. - -برای تغییر قواعد کافی است یک فایل با نام `prettierrc.` را به پروژه اضافه کنید. -ما پیشنهاد می‌کنیم از تنظیمات زیر برای پروژه‌های خود استفاده کنید: - -```json -{ - "printWidth": 120, - "tabWidth": 4, - "semi": true, - "singleQuote": true, - "trailingComma": "es5", - "bracketSpacing": false, - "arrowParens": "always", - "endOfLine": "auto", - "overrides": [ - { - "files": ["*.css", "*.scss"], - "options": { - "singleQuote": false - } - } - ] -} -``` - -همچنین اگر نمی‌خواهید Prettier در برخی از فایل‌ها تغییر ایجاد کند، -می‌توانید یک فایل با نام `prettierignore.` به پروژه اضافه کنید. -این فایل دقیقاً مشابه با `gitignore.` است و ما پیشنهاد می‌کنیم محتوای `gitignore.` را داخل این فایل نیز اضافه کنید. - -برای آشنایی بیشتر با Prettier می‌توانید از لینک زیر استفاده کنید: - -- [Prettier Docs](https://prettier.io/docs/en/index.html) - -#### ESLint - -Prettier -تنها ظاهر کدهای شما را زیبا می‌کند؛ -اما اکثر اوقات، مخصوصاً زمانی که به صورت تیمی بر روی یک پروژه کار می‌کنید، -احتیاج دارید قواعدی برای تمیزی کد وضع کنید؛ -ESLint -یک پکیج استاندارد است که به شما این امکان را می‌دهد. - -برای وضع قوانین کافی است یک فایل با نام `eslintrc.` را به پروژه اضافه کنید. -ما پیشنهاد می‌کنیم از قواعد پیش‌فرض ESLint استفاده کنید: - -```json -{ - "extends": "eslint:recommended" -} -``` - -برای آشنایی بیشتر با این قواعد می‌توانید از لینک زیر استفاده کنید: - -- [ESLint Rules](https://eslint.org/docs/latest/rules/) diff --git a/docs/frontend/phase02-pilot.md b/docs/frontend/phase02-pilot.md deleted file mode 100644 index a8800ca5..00000000 --- a/docs/frontend/phase02-pilot.md +++ /dev/null @@ -1,470 +0,0 @@ ---- -title: Pilot -description: The One Where it All Began ---- - -## مقدمه - -در این فاز برای شروع پروژه، Angular را معرفی می‌کنیم، -به برخی نکات مهم در HTML می‌پردازیم -و در نهایت چند منبع برای یادگیری flexbox و grid معرفی می‌کنیم. - -- تفاوت کتابخانه و فریمورک چیست؟ -- چرا به سراغ Angular می‌رویم؟ -- چگونه با Angular یک پروژه بسازیم؟ -- چرا از تگ‌های معنایی استفاده می‌کنیم؟ -- در استفاده از عکس‌ها چه نکاتی را باید رعایت کنیم؟ - ---- - -## یادگیری - -### Angular - -#### تفاوت کتابخانه و فریمورک - -کتابخانه مجموعه‌ای از ابزارها را در اختیار ما قرار می‌دهد -تا بتوانیم پروژه را راحت‌تر توسعه دهیم. -معروف‌ترین کتابخانه‌ای که در فرانت‌اند وجود دارد، React است. -React -شامل پکیج‌های زیادی است که تعدادی از آن‌ها توسط Facebook توسعه داده می‌شوند -و باقی آن‌ها توسط اشخاص حقیقی و حقوقی دیگر. - -اما در مقابل، Framework یا چارچوب، همان‌طور که از اسمش پیداست، -علاوه بر ابزارهای مورد نیاز، شامل قواعد و دستورالعمل‌هایی برای کدنویسی است. -این قواعد از بدیهی‌ترین مسائل مانند زبان مورد استفاده تا پیچیده‌ترین مسائل مانند Performance را شامل می‌شود. -بزرگ‌ترین فریمورکی که در فرانت‌اند وجود دارد، Angular است. -Angular -توسط شرکت Google توسعه داده می‌شود. -در ابتدا AngularJS نام داشت اما بعد از تغییرات اساسی و اضافه‌شدن Typescript، -از نسخه 2 به بعد، به Angular تغییر نام داد. -در زمان نوشتن این مطلب، جدیدترین نسخه آن، Angular 14 است -و به طور منظم هر 6 ماه یک بار، نسخۀ جدید آن منتشر می‌شود. - -خوشبختانه کدهای بنیادین React و Angular و همچنین اکثر کتابخانه‌ها و فریمورک‌های JavaScript، -به صورت Open-Source در اختیار عموم قرار دارند. - -#### چرا Angular؟ - -برای سایت‌های کوچک مانند فروشگاه‌های آنلاین، تماشای فیلم و سریال، اشتراک‌گذاری آهنگ و پروژه‌های دانشجویی، -قطعاً نیازی به Angular حس نمی‌شود. -این پروژه‌ها، همان‌طور که مرسوم است، اکثراً با کتابخانه‌هایی مانند React توسعه داده می‌شوند -و بدونِ آنکه توسعه‌دهنده کمبودی احساس کند، به نتیجۀ دلخواه خود می‌رسد. - -اما زمانی که در مورد یک پروژه صنعتی بسیار بزرگ صحبت می‌کنیم، -مخصوصاً اگر ده‌ها بلکه صدها توسعه‌دهنده مشغول کار بر روی آن باشند، -قطعاً به یک چارچوب، مجموعه‌ای از قواعد و دستورالعمل‌ها، احتیاج پیدا خواهیم کرد. - -این چارچوب می‌تواند توسط تیم فنی ایجاد شود و همراه با React یا به طور کلی هر کتابخانه‌ای مورد استفاده قرار گیرد؛ -ولی قطعاً Overhead زیادی خواهد داشت و ممکن است به اندازۀ یک فریمورک، محکم و قابل اطمینان نباشد. -استفاده از فریمورکی مانند Angular که بارها و بارها توسط هزاران توسعه‌دهنده مورد ارزیابی قرار گرفته، -باگ‌های احتمالی آن کشف و ثبت شده، -درخواست‌ها و فیچرهای جدید در آن پیاده‌سازی شده، -قطعاً بار سنگینی را از دوش توسعه‌دهنده برمی‌دارد و هزینه‌های غیرضروری تیم را کاهش می‌دهد. - -#### نصب و راه‌اندازی - -Angular -یک Command-line Interface یا CLI دارد که با استفاده از آن می‌توانید پروژۀ خود را مدیریت کنید؛ -بنابراین قبل از هر کاری، ابتدا باید با دستور زیر ان را نصب کنیم: - -```shell -npm i -g @angular/cli@12.2.17 -``` - -با استفاده از پارامتر `g` مشخص می‌کنیم که می‌خواهیم CLI در اسکوپِ Global نصب شود؛ -بنابراین در هرکجا از سیستم می‌توانیم از آن استفاده کنیم. - -همان‌طور که در کد بالا می‌بینید، -ما از نسخه 12.2.17 استفاده می‌کنیم و پیشنهاد می‌کنیم شما هم از همین نسخه استفاده کنید تا در روند آموزش مشکلی پیش نیاید. - -از این پس می‌توانید با استفاده از دستور `ng`، از CLI استفاده کنید. - -#### ساخت پروژه جدید - -با استفاده از دستور زیر می‌توانید یک پروژه جدید ایجاد کنید: - -```shell -ng new my-project-name -``` - -سعی کنید اسمی خلاقانه و همچنین مناسب برای پروژه انتخاب کنید که بیانگر کاربرد آن باشد. -همچنین دقت داشته باشید که اسم انتخابی شما باید حتماً kebab-case باشد. - -#### ESLint & Prettier - -در فاز قبل ESLint را معرفی کردیم؛ -حال می‌خواهیم آن را به پروژه‌ای که ساختیم اضافه کنیم. -برای این کار ابتدا باید پکیج مخصوص Angular را نصب کنیم: - -```shell -ng add @angular-eslint/schematics -``` - -همان‌طور که می‌بینید به جای استفاده از `npm i`، از `ng add` برای نصب پکیج استفاده کردیم. -این قابلیت در بعضی از پکیج‌ها وجود دارد و در صورتی که به این شکل آن‌ها را به پروژه اضافه کنیم، -خودِ Angular ورژن مناسب را پیدا و نصب می‌کند؛ -همچنین در صورتی که احتیاج باشد، علاوه بر نصب پکیج، فایل‌های مربوطه را نیز تغییر می‌دهد. - -حال به نصب Prettier می‌پردازیم: - -```shell -npm i -D prettier eslint-config-prettier eslint-plugin-prettier -``` - -با اجرای دستور بالا، علاوه بر Prettier، تنظیمات مربوط به ESLint هم دانلود می‌شوند و می‌توانیم از آن‌ها در پروژه استفاده کنیم. -علت این کار آن است که تنظیمات ESLint و Prettier باهم تداخل نداشته باشند. - -در ادامه محتوای پیشنهادی فایل‌های تنظیمات مربوط به ESLint و Prettier را می‌بینیم: - -```json title=".eslintrc" -{ - "root": true, - "ignorePatterns": ["projects/**/*"], - "overrides": [ - { - "files": ["*.ts"], - "parserOptions": { - "project": ["tsconfig.json"], - "createDefaultProgram": true - }, - "extends": [ - "plugin:@angular-eslint/recommended", - "plugin:@angular-eslint/template/process-inline-templates", - "prettier" - ], - "plugins": ["prettier"], - "rules": { - "@angular-eslint/directive-selector": [ - "error", - { - "type": "attribute", - "prefix": "app", - "style": "camelCase" - } - ], - "@angular-eslint/component-selector": [ - "error", - { - "type": "element", - "prefix": ["app", "icon", "illustration"], - "style": "kebab-case" - } - ], - "@typescript-eslint/explicit-member-accessibility": ["error"], - "@typescript-eslint/explicit-function-return-type": ["error"], - "prettier/prettier": ["error", {"endOfLine": "auto"}] - } - }, - { - "files": ["*.html"], - "extends": ["plugin:@angular-eslint/template/recommended", "prettier"], - "plugins": ["prettier"], - "rules": {"prettier/prettier": ["error", {"endOfLine": "auto"}]} - } - ] -} -``` - -```json title=".prettierrc" -{ - "printWidth": 120, - "tabWidth": 4, - "semi": true, - "singleQuote": true, - "trailingComma": "es5", - "bracketSpacing": false, - "arrowParens": "always", - "endOfLine": "auto", - "overrides": [ - { - "files": ["*.html"], - "options": { - "parser": "html" - } - }, - { - "files": ["*.component.html"], - "options": { - "parser": "angular" - } - }, - { - "files": ["*.css", "*.scss"], - "options": { - "singleQuote": false - } - } - ] -} -``` - -فراموش نکنید محتویات فایل -`gitignore.` -را به فایل -`prettierignore.` -هم اضافه کنید تا از تغییر فایل‌های ناخواسته جلوگیری شود. - -زمانی که یک پروژۀ جدید انگولاری می‌سازید، به صورت خودکار یک فایل با نام -`editorconfig.` -در پوشۀ اصلی پروژه قرار می‌گیرد؛ -کارکرد این فایل مانند ESLint یا Prettier است و می‌توانید قوانینی وضع کنید که تمام اعضای گروه از آن‌ها پیروی کنند. -از آنجایی که ما از ESLint و Prettier استفاده می‌کنیم، دیگر نیازی به این فایل نیست -و برای جلوگیری از تداخل احتمالی باید آن را پاک کنید. - -شما می‌توانید با استفاده از دستور زیر، ایراداتی که ESLint به کدهای شما وارد می‌کند را ببینید: - -```shell -ng lint -``` - -همچنین با استفاده از این دستور می‌توانید به ESLint بگویید که به طور خودکار و هوشمند سعی کند ایرادات را برطرف نماید: - -```shell -ng lint --fix -``` - -#### مطالعه بیشتر - -همان‌طور که احتمالاً حدس می‌زنید، Angular حاوی مباحث بسیار زیادی است که توضیح تک‌تک آن‌ها در قالب آموزش متنی بسیار دشوار است؛ -بنابراین این مباحث در قالب کارگاه ارائه خواهد شد؛ -اما در صورتی که تمایل دارید به منابع بیشتری دسترسی داشته باشید، می‌توانید از لینک‌های زیر استفاده کنید: - -- [Angular Docs](https://angular.io/docs/) -- [Traversy Media - Angular Crash Course](https://www.youtube.com/watch?v=3dHNOWTI7H8) - ---- - -### HTML - -#### تگ‌های معنایی - -در HTML تگ‌هایی وجود دارند که صرفاً برای یک کار خاص طراحی شده‌اند و با دیدن نام آن‌ها می‌توان کاربردشان را متوجه شد. به -این تگ‌ها، **تگ‌های معنایی** گفته می‌شود که لیستی از آن‌ها را به همراه توضیحات مختصری در اینجا مشاهده می‌کنید. - -توصیه می‌کنیم همزمان با خواندن این مطلب، -[صفحۀ دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html) -را نیز مشاهده کنید تا به صورت دیداری و کاربردی با مفاهیم آشنا شوید. - -##### header - -معمولاً در بالاترین بخش صفحه یا المان مورد نظر قرار می‌گیرد و در اکثر مواقع شامل لوگو، `nav` و دکمه‌های -Call-to-Action می‌باشد. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#header) - -##### nav - -شامل لینک‌هایی به قسمت‌های مختلف صفحۀ اصلی یا سایت می‌باشد. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#nav) - -##### main - -شامل محتوای اصلی سایت می‌باشد و در اکثر مواقع بیشترین حجم از صفحه را اشغال می‌کند. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#main) - -##### aside - -شامل محتوایی غیر از محتوای اصلی می‌باشد به طوری که نمی‌توان آن را در `main` قرار داد. به‌عنوان مثال تبلیغات یا لینک -به قسمت‌های مختلف مقاله. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#aside) - -##### footer - -معمولاً در پایین‌ترین بخش صفحه یا المان مورد نظر قرار می‌گیرد و در اکثر مواقع شامل Copyright، توضیحات مختصری در -مورد سایت و شخص یا گروه سازنده می‌باشد. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#footer) - -##### article - -بخشی از محتواست که کاملاً از بخش‌های دیگر مستقل می‌باشد به گونه‌ای که می‌توان آن را به طور جداگانه استفاده یا -منتشر کرد. به‌عنوان مثال می‌توان به مقاله‌ای از یک مجله یا پستی از یک وبلاگ اشاره کرد. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#article) - -##### section - -بخشی از محتوای اصلی سایت را مشخص می‌کند. معمولاً از این تگ برای ایجاد تمایز بینِ قسمت‌های مختلف استفاده می‌شود. -معمولاً در ابتدای هر بخش از `heading` یعنی تگ‌های `h1` تا `h6` استفاده می‌شود. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#results) - -##### details - -شامل بخشی از محتواست که کاربر می‌تواند در صورت نیاز آن را نمایان یا پنهان کند. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#details) - -##### summary - -همیشه داخل المان `details` استفاده می‌شود و باید شامل توضیحاتی دربارۀ آن باشد. - -[مشاهده در صفحه دمو](https://star-academy.github.io/frontend-demos/pages/semantic-tags/index.html#summary) - -البته موارد بالا تنها بخشی از تگ‌های معنایی HTML می‌باشند. برای آشنایی بیشتر با این مفهوم می‌توانید از لینک‌های زیر -استفاده کنید: - -- [MDN - HTML Elements Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) -- [W3Schools - HTML Semantic Elements](https://www.w3schools.com/html/html5_semantic_elements.asp) -- [HTML.com - What On Earth Is Semantic Markup?](https://html.com/semantic-markup/) -- [A Friendly Tutorial For Developing Meaningful Web Pages](https://internetingishard.netlify.app/html-and-css/semantic-html/index.html) -- [freeCodeCamp - Semantic HTML5 Elements Explained](https://www.freecodecamp.org/news/semantic-html5-elements/) - ---- - -#### Text Formatting Tags - -بعضی از تگ‌ها مانند `b` و `i` برای تغییر ظاهر بخشی از متن استفاده می‌شوند که لیست آن‌ها را در اینجا ذکر می‌کنیم: - -##### b & strong - -عبارت مورد نظر را به صورت Bold یا پُررنگ نمایش می‌دهند. - -##### i & em - -عبارت مورد نظر را به صورت Italic یا کج نمایش می‌دهند. - -##### mark - -برای Highlight کردن بخشی از نوشته، استفاده می‌شود. - -##### small - -عبارت مورد نظر را با اندازۀ کوچکتری نسبت به اندازۀ اصلی نمایش می‌دهد. - -##### del - -برای نوشته‌های حذف‌شده استفاده می‌شود به طوری که معمولاً آن‌ها را به صورت خط‌خورده نمایش می‌دهد. - -##### ins - -برای نوشته‌های اضافه‌شده استفاده می‌شود به طوری که معمولاً آن‌ها را با Underline نمایش می‌دهد. - -##### sub - -معمولاً برای نمایش اندیس‌ها در پایینِ عبارت، استفاده می‌شود. - -##### sup - -معمولاً برای نمایش شماره‌های پاورقی در بالای عبارت، استفاده می‌شود. - -اما تمامِ این styleها را با استفاده از CSS نیز می‌توانیم داشته باشیم؛ پس علت وجود این تگ‌ها چیست؟ چرا برای بعضی از -استایل‌ها مانند Bold، دو تگ متفاوت داریم؟ - -کاربرد اصلی این تگ‌ها برای استفادۀ سریع هنگام نوشتن محتوای سایت است. به‌عنوان مثال هر وقت خواستیم یک کلمه را Bold کنیم -به جای اینکه از `span` در HTML و یک کلاس در CSS، می‌توانیم از `b` یا `strong` استفاده کنیم، بدونِ آنکه نیاز باشد -تغییری در کد CSS دهیم. - -از طرفی در صورت نیاز می‌توانید ظاهر این تگ‌ها را مانند هر تگ دیگری تغییر دهید؛ -یعنی مثلاً به جای اینکه یک کلاس به اسم `bold` درست کنید -و هر بار مجبور باشید در HTML از آن استفاده کنید، می‌توانید صرفاً تگ `b` را استعمال کنید و در CSS فرمت دلخواه را -اعمال کنید. - -تگ‌های `b` و `strong` در ظاهر تفاوتی باهم ندارند. اما زمانی که شما از `strong` استفاده کنید، علاوه بر اینکه عبارت مورد نظر به -شکل Bold نمایش داده می‌شود، اگر کاربر از Screen Reader استفاده کند، نرم‌افزار به این موضوع اشاره خواهد کرد. به طور کلی -زمانی که صرفاً بخواهید ظاهر کلمه پُررنگ باشد از `b` و زمانی که بخواهید مفهوم کلمه پُررنگ باشد از `strong` استفاده کنید. -همچنین در مورد تگ‌های `i` و `em`، اگر از `em` استفاده کنید، نرم‌افزار آن عبارت را با استرس بیشتری می‌خواند. - -برای آشنایی بیشتر با این مفهوم می‌توانید از لینک زیر استفاده کنید: - -- [W3Schools - HTML Text Formatting](https://www.w3schools.com/html/html_formatting.asp) - ---- - -### عکس‌ها - -#### alt - -حتما با `alt` در تگ `img` آشنا هستید. حتی شاید زمانی که از آن استفاده نکردید، متوجه هشدار IDE شده باشید. -اما کاربرد این Attribute چیست؟ -زمانی که از عکس استفاده می‌کنیم چرا باید توضیحی برای آن بنویسیم؟ مقدار این Attribute به کاربر نشان داده -نمی‌شود، پس نوشتن آن چه فایده‌ای دارد؟ - -`alt` -در اینجا مخفف عبارت Alternate Text یا متن جایگزین می‌باشد که دو کاربرد مهم برای آن می‌توان در نظر گرفت: - -1. همانطور که از اسم آن مشخص است، جایگزینی برای عکس می‌باشد به طوری که اگر به هر دلیلی امکان نمایش عکس وجود نداشت، - این نوشته به کاربر نشان داده می‌شود تا موضوع عکس را بفهمد. - -2. Screen Readerها متن مورد نظر را می‌خوانند بنابراین کاربرانی که نمی‌توانند عکس را ببینند، متوجهِ موضوع عکس می‌شوند. - -بنابراین استفاده از alt برای عکس‌ها بسیار حائز اهمیت است. اما در موارد زیر بهتر است یک متن خالی را برای آن در نظر -بگیریم: - -- عکس مورد نظر صرفاً برای زیبایی ظاهری و دکوری باشد، به طوری که مفهوم خاصی به محتوا اضافه نکند. -- عکس مورد نظر Caption داشته باشد. - -دقت کنید که در موارد بالا حتماً باید تگ `alt` را استفاده کنید، اما متنی داخل آن ننویسید؛ به‌عنوان مثال: - -```html - -``` - -علت این موضوع این است که اگر `alt` وجود نداشته باشد، Screen Reader نام فایل عکس را به‌عنوان توضیحات آن می‌خواند؛ -اما اگر متن خالی داخل `alt` باشد، عکس به کلی در نظر گرفته نمی‌شود. - -برای آشنایی بیشتر با این مفهوم می‌توانید از لینک زیر استفاده کنید: - -- [Accessibility: Image Alt text best practices](https://support.siteimprove.com/hc/en-gb/articles/115000013031-Accessibility-Image-Alt-text-best-practices) - -#### Performance - -ما تقریباً در تمام سایت‌ها از عکس استفاده می‌کنیم؛ بنابراین همیشه باید به مبحث Performance توجه داشته باشیم، چرا که در -غیر این صورت تجربۀ بدی در انتظار کاربران ما خواهد بود. - -یکی از بهترین راه‌ها برای افزایش Performance، استفاده از عکس‌های باکیفیت و در عینِ حال کم‌حجم است. برای این موضوع ما -سایت -[Squoosh](https://squoosh.app/) -را که توسط توسعه‌دهندگان Google ساخته شده، به شما پیشنهاد می‌کنیم. استفاده از آن بسیار آسان است، صرفاً کافی است عکس خود -را آپلود و عکس کم‌حجم شده را دریافت کنید. همچنین این سایت قابلیت تبدیل به انواع فرمت‌ها و استفاده از الگوریتم‌های -گوناگون را دارد. - -در صورت امکان پیشنهاد می‌کنیم حتماً از فرمت svg استفاده کنید. -این فرمت برخلاف فرمت‌هایی مثل png و jpeg، به صورت Vector یا برداری می‌باشد، -به طوری که شما می‌توانید بدونِ افت کیفیت، به هر اندازه آن را کوچک یا بزرگ کنید. -فرمت svg همواره از باقی فرمت‌ها کم‌حجم‌تر است اما در عوض، جزئیات کمتری را می‌توانید در آن جای دهید. -بنابراین بهترین استفاده از svg در لوگوها، Illustrationها و آیکن‌هاست. - -برای دانلود فایل‌های svg حرفه‌ای می‌توانید از لینک‌های زیر استفاده کنید: - -- [freepik](https://www.freepik.com/home) -- [flaticon](https://www.flaticon.com/) -- [unDraw](https://undraw.co/) -- [Icons8](https://icons8.com/) - ---- - -### Flexbox & Grid - -می‌توان گفت Flexbox و Grid جزء بهترین قابلیت‌هایی هستند که در طی چند سال گذشته به CSS اضافه شده‌اند؛ -اما متاسفانه خیلی از افراد در استفاده از آن‌ها دچار مشکل می‌شوند و نحوۀ کارکرد آن‌ها را به خوبی درک نمی‌کنند. -بنابراین در این قسمت به معرفی چند منبع برای رفع ابهامات احتمالی می‌پردازیم. - -برای آشنایی بیشتر با Flexbox می‌توانید از لینک زیر استفاده کنید: - -- [CSS Tricks - A Complete Guide to Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) -- [Game - Flexbox Froggy](https://flexboxfroggy.com/) -- [Kevin Powell - Do you understand how Flexbox does what it does?](https://www.youtube.com/watch?v=9e-lWQdO-DA) -- [Kevin Powell - Flexbox is more complicated than you thought](https://www.youtube.com/watch?v=fm3dSg4cxRI) - -برای آشنایی بیشتر با Grid می‌توانید از لینک زیر استفاده کنید: - -- [CSS Tricks - A Complete Guide to Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) -- [Game - Grid Garden](https://codepip.com/games/grid-garden/) -- [Grid by Example](https://gridbyexample.com/) -- [Kevin Powell - The EASIEST way to get started with CSS GRID](https://www.youtube.com/watch?v=_lEkD8IGkwo) -- [Traversy Media - CSS Grid Layout Crash Course](https://www.youtube.com/watch?v=jV8B24rSN5o) -- [W3Schools - CSS Grid Layout Module](https://www.w3schools.com/css/css_grid.asp) - ---- - -## پروژه - -در این دوره قصد داریم یک فروشگاه آنلاین مانند Steam یا Epic برای خرید بازی بسازیم. -در این فاز شما باید با توجه به موارد آموزش داده شده، یک Landing Page برای سایت خود بسازید. -می‌توانید از نرم‌افزارهای مشابه ایده بگیرید اما اینکه چه قابلیت‌هایی در سایت شما وجود داشته باشد، کاملاً بستگی به خودتان دارد. -در صورتی که پیاده‌سازی قابلیتی ضروری باشد، در مستندات به آن اشاره خواهیم کرد. diff --git a/docs/frontend/phase07-ci-cd.md b/docs/frontend/phase07-ci-cd.md deleted file mode 100644 index 4e6ebc54..00000000 --- a/docs/frontend/phase07-ci-cd.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: CI/CD -description: Where is the pipe that was holding the door open? ---- - -## مقدمه - -زمانی که بر روی یک پروژۀ شخصی کار می‌کنیم، -معمولاً به ندرت احتیاج داریم آن را تست یا مستقر کنیم. -اما زمانی که پروژه به صورت تیمی توسعه داده شود، -نیاز است به طور مداوم تست‌های مختلف اجرا و فرآیند استقرار به‌طور خودکار انجام شود. -برای حل این مشکل می‌توانیم از روش‌های Continuous Integration و Continuous Deployment استفاده کنیم. - -- چگونه می‌توان تست‌ها را به‌طور خودکار اجرا کرد؟ -- چگونه می‌تواند فرآیندی جهت استقرار پروژه تنظیم کرد؟ -- چگونه می‌توان گزارشی از تمیزی کدهای جدید بدست آورد؟ - ---- - -## یادگیری - -### تعریف - -برای آشنایی بیشتر با این مفهوم می‌توانید از لینک‌های زیر استفاده کنید: - -- [Medium - What is CI/CD?](https://medium.com/tilicholabs/what-is-ci-cd-c7c047b80e6b) -- [Medium - The Journey to CI/CD](https://medium.com/driven-by-code/the-journey-to-ci-cd-b1872927c36b) -- [Medium - What's the Point of CI Anyway?](https://medium.com/swlh/whats-the-point-of-ci-anyway-ac3f9eaa244c) - ---- - -### GitHub Actions - -یکی از ابزارهای CI/CD معروف، GitHub Actions است -که به کمک آن، می‌توانیم یک Pipeline شامل عملیات Build، اجرای Testها، استقرار پروژه -و دیگر عملیاتی که در دستهٔ CI/CD قرار می‌گیرد را به Repository خود اضافه کنیم. - -#### Setup - -یک پوشه با نام `github.` در پوشۀ اصلی پروژه بسازید -و یک پوشه با نام `workflows` به آن اضافه کنید. -حال یک فایل که به پسوند `yml` ختم می‌شود را درون پوشۀ `workflows` قرار دهید؛ -به‌طور مثال ما از نام `deploy.yml` استفاده می‌کنیم. - -برای آنکه نام Workflow را مشخص کنید، کافی است محتوای زیر را به فایل خود اضافه نمایید: - -```yaml -name: Deployment Workflow -``` - -#### Conditions - -ممکن است بخواهید فقط زمانی Workflow اجرا شود که بر روی یک Branch خاص عملیات Push را انجام می‌دهید؛ -در این صورت محتوای زیر را به فایل خود اضافه نمایید: - -```yaml -on: - push: - branches: - - main -``` - -اما اگر می‌خواهید بر روی تمام Branchها این اتفاق بیفتد؛ -از محتوای زیر استفاده کنید: - -```yaml -on: - push: -``` - -همچنین می‌توانید شرایط دیگری را برای اجرا شدن Workflow در نظر بگیرید؛ -به‌عنوان مثال ایجاد یک Pull Request جدید یا عوض‌شدن وضعیت Issueها. - -#### Test - -هر Workflow می‌تواند شامل چند Job باشد که به‌صورت موازی یا متوالی انجام می‌شوند. - -برای تعریف کار Test می‌توانید از محتوای زیر استفاده کنید: - -```yml -jobs: - test: - name: Test - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v2 - - - name: Setup Node - uses: actions/setup-node@v1 - with: - node-version: '16.x' - - - name: Install Dependencies - run: npm ci - - - name: ESLint - run: npm run eslint:check - - - name: Stylelint - if: success() - run: npm run stylelint:check - - - name: Prettier - if: success() - run: npm run prettier:check - - - name: Angular - if: success() - run: npm run test:ci -``` - -در اینجا ابتدا نامی برای Job در نظر می‌گیریم تا بتوانیم آن را از سایر Jobها تشخیص دهیم؛ -در خط بعد سیستم‌عاملی که Job بر روی آن اجرا می‌شود را مشخص کنیم؛ -سپس مراحل کار را تعریف می‌کنیم که هر کدام را در ادامه به‌صورت مختصر توضیح می‌دهیم. - -##### Checkout - -همان‌طور که شما برای انجام هر کاری احتیاج دارید ابتدا بر روی Branch مورد نظر عملیات Checkout را انجام دهید، -زمانی که از GitHub Actions استفاده می‌کنیم هم باید این عملیات انجام شود. - -##### Setup Node - -در این مرحله Node.js بر روی سیستم عامل نصب می‌شود. -شما می‌توانید یک نسخۀ خاص از Node.js را که مطمئنید با پروژۀ شما سازگار است نصب کنید. - -##### Install Dependencies - -با اجرای دستور `npm ci` در ترمینال به نصب Dependencyها می‌پردازیم. - -##### ESLint - -با اجرای دستور `npm run eslint:check` از پاس‌شدن تست‌های ESLint اطمینان حاصل می‌کنیم. - -##### Stylelint - -با اجرای دستور `npm run stylelint:check` از پاس‌شدن تست‌های Stylelint اطمینان حاصل می‌کنیم. - -##### Prettier - -با اجرای دستور `npm run prettier:check` از پاس‌شدن تست‌های Prettier اطمینان حاصل می‌کنیم. - -##### Angular - -با اجرای دستور `npm run test:ci` از پاس‌شدن تست‌های Angular اطمینان حاصل می‌کنیم. - -##### Scripts - -این Scriptها را باید به فایل `package.json` اضافه نمایید: - -```json -{ - "name": "...", - "version": "...", - "scripts": { - "eslint:check": "ng lint", - "eslint:fix": "ng lint --fix", - "stylelint:check": "stylelint \"**/*.scss\"", - "stylelint:fix": "stylelint \"**/*.scss\" --fix", - "prettier:check": "prettier . --check", - "prettier:fix": "prettier . --write", - "test:ci": "ng test --browsers=ChromeHeadless --watch=false" - } -} -``` - -همچنین برای راحتی کار شما، نسخۀ `fix:` را برای هر Script قرار داده‌ایم -تا با استفاده از آن بتوانید خطاهای احتمالی را به‌صورت خودکار رفع کنید. - -#### Build - -برای تعریف کار Build می‌توانید از محتوای زیر استفاده کنید: - -```yml -jobs: - test: ... - build: - name: Build - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v2 - - - name: Setup Node - uses: actions/setup-node@v1 - with: - node-version: '16.x' - - - name: Install Dependencies - run: npm ci - - - name: Build - run: npm run build:prod - - - name: 404.html Hack - if: success() - run: cp dist/my-project-name/index.html dist/my-project-name/404.html - - - name: Upload Build - if: success() - uses: actions/upload-artifact@v1 - with: - name: deploy_dist - path: dist -``` - -با اجرای دستور `npm run build:prod` از پروژه Build تهیه می‌کنیم. - -این Script را باید به فایل `package.json` اضافه نمایید: - -```json -{ - "name": "...", - "version": "...", - "scripts": { - "build:prod": "ng build --base-href=/my-project-name/" - } -} -``` - -:::caution - -به جای `my-project-name` باید نام پروژۀ خود را قرار دهید. - -::: - -##### 404.html Hack - -زمانی که از GitHub Pages برای استقرار سایت استفاده می‌کنیم، -اگر به‌صورت دستی آدرس یکی از صفحات را در مرورگر وارد کنیم، -صفحۀ 404 نمایش داده می‌شود و از Routing خودِ Angular استفاده نمی‌کند. -برای حل این مشکل یک کپی از `index.html` می‌گیریم و نام آن را `404` می‌گذاریم. - -##### Upload Build - -تنها در صورتی که نتیجۀ Build موفقیت‌آمیز بود، -آن را به طور موقت با نام `deploy_dist` ذخیره می‌کنیم تا در ادامه بتوانیم از آن استفاده کنیم. - -#### Deploy - -برای تعریف کار Deploy می‌توانید از محتوای زیر استفاده کنید: - -```yaml -jobs: - test: ... - build: ... - deploy: - name: Deploy - runs-on: ubuntu-latest - needs: - - test - - build - steps: - - name: Checkout - uses: actions/checkout@v1 - - - name: Download Build - uses: actions/download-artifact@v1 - with: - name: deploy_dist - - - name: Deploy to GitHub Pages - uses: JamesIves/github-pages-deploy-action@releases/v3 - with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - BRANCH: gh-pages - FOLDER: deploy_dist/my-project-name -``` - -:::caution - -به جای `my-project-name` باید نام پروژۀ خود را قرار دهید. - -::: - -##### Download Build - -پوشه‌ای که در مرحلۀ قبل ذخیره کرده بودیم را در اینجا دانلود می‌کنیم. - -##### Deploy to GitHub Pages - -محتویات پوشه را داخل برنچ `gh-pages` قرار می‌دهیم که GitHub بتواند از آن استفاده کند. - -#### Monitor - -از این پس، بعد از آنکه بر روی Branch مورد نظر عملیات Push انجام دهید، -در صفحۀ Actions پروژۀ خود می‌توانید اجرا آن را مرحله به مرحله زیر نظر بگیرید -و در صورتی که خطایی رخ دهد از آن باخبر شوید. - ---- - -## پروژه - -با توجه به مطالبی که در این فاز یاد گرفتید، -فرآیند CI/CD را برای پروژۀ خود فراهم کنید.