معرفی فریم ورک Stimulus برای علاقه‌مندان به HTML

DOM: موقعیتی برای وضعیت (State)

مفاهیم اصلی بسیاری از فریم‌ورک‌های مدرن در جداسازی " state" از " DOM" قرار دارد. به این ترتیب DOM فقط مانند کلاینتی رفتار می‌کند که داده‌های آن در حال نمایش هستند.

Stimulus این رفتار را تغییر داد و در عوض از DOM برای نگه داشتن state استفاده کرد.

در نهایت این بدان معناست که Stimulus برای برنامه‌هایی که HTML را به کار می‌گیرند مناسب‌تر است (مثلا یکپارچگی با JSON API).

با Stimulus، شما قالب HTML را نمی‌بینید. در عوض ویژگی *-data را می بینید که HTML را به برنامه جاوااسکریپت متصل می‌کند.

همچنین بدان معناست که مواردی مثل each یا حلقه‌های map را که ممکن است در Handlebars یا React ببینید را دیگر مشاهده نمی‌کنید.

Stimulus کار رندرینگ HTML را انجام نمی‌دهد مگر اینکه خودتان به صراحت این قابلیت را ا ایجاد کنید.

پس... چه کاری انجام می‌دهد؟

Stimulus قالب‌ها را رندر نمی‌کند. در عوض، برای اتصال اقدامات و رویدادهای front end برنامه برای کنترل روی back end ساخته شده است.

Stimulus از این سه مفهوم برای انجام این کار استفاده می‌کند: targetها، controllerها و actionها.

اما قبل از اینکه از این مفاهیم دور شویم، بیایید Stimulus را در کامپیوتر خود اجرا کنیم.

راه‌اندازی

فرض می‌کنیم که آخرین نسخه NodeJS را روی کامپیوتر خود نصب دارید. اگر از قبل این کار را انجام نداده‌اید، به nodejs.org مراجعه کنید.

ما از یک فایل index.html استاتیک پایه استفاده می‌کنیم که در ابتدا به صورت دستور زیر خواهد بود:

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./dist/bundle.css">
  </head>
  <body>
    <!-- application code will go here -->
    <script src="./dist/bundle.js"></script>
  </body>
</html>

نکته: ما در واقع هیچ یک از استایل‌ها یا فرآیند ساخت CSS را در این آموزش پوشش نمی‌دهیم.

سپس یک فولدر به نام src ایجاد کنید. داخل src فولدر دیگری به نام controllers ایجاد کرده و یک فایل index.js بسازید.

ما برای ساخت برنامه جاوااسکریپت از Webpack استفاده می‌کنیم، زیرا Stimulus از برخی ویژگی‌های پیشرفته جاوا اسکریپت استفاده می‌کند که به طور مستقیم در مرورگرها کار نمی‌کند.

فایلی را در روت (ریشه) پروژه خود به نام package.json ایجاد کنید که شامل محتوای زیر است:

{
    "name": "wdstimulus",
    "version": "1.0.0",
    "description": "Stimulus Introduction",
    "scripts": {},
    "author": "Your Name",
    "license": "ISC",
    "devDependencies": {
        "@babel/core": "^7.0.0-beta.39",
        "@babel/preset-env": "^7.0.0-beta.39",
        "babel-loader": "^8.0.0-beta.0",
        "babel-preset-stage-0": "^6.24.1",
        "stimulus": "^1.0.0",
        "webpack": "^3.10.0"
    }
}

نکته: این نسخه‌ها در آینده تغییر خواهند کرد و توصیه می‌کنیم تا جایی که ممکن است با آخرین نسخه ابزار کار کنید.

همچنین می‌توانید این فایل را با استفاده از npm init تولید کنید و وابستگی‌ها را یکی پس از دیگری با استفاده از npm install [package-name]نصب کنید.

این فایل شامل تمام چیزهایی است که برای ایجاد ساختاری سازگار با مرورگر برنامه Stimulus خود نیاز داریم. از روت برنامه npm install را اجرا کنید. این عمل وابستگی‌ها را در پوشه node_modules موجود در برنامه شما نصب خواهد کرد.

سپس، یک فایل پیکربندی را ایجاد می‌کنیم، بنابراین Webpack می‌داند که ما وقتی فایل‌ها را ذخیره می‌کنیم چه کاری می‌خواهیم با آن‌ها انجام دهیم. در همان پوشه روت جایی که package.json آنجا قرار دارد، فایلی به نام webpack.config.js ایجاد کنید، و این محتوا را اضافه کنید:

module.exports = {
    module: {
        rules: [
            {
                test: /\.js$/,
                exclude: /(node_modules)/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: ["@babel/env"],
                        plugins: ["transform-class-properties"]
                    }
                }
            }
        ]
    }
};

این فایل اساسا به Webpack می‌گوید جاوااسکریپت ما را با استفاده از env preset کامپایل کند. همچنین پلاگین ضروری transform-class-properties را اضافه می‌کنیم.

آخرین مرحله برای آماده شدن برنامه Stimulus این است که فایل index.js خود را با محتوای زیر پر کنیم:

import { Application } from "stimulus"
import { definitionsFromContext } from "stimulus/webpack-helpers"
  
const application = Application.start()
const context = require.context("./controllers", true, /\.js$/)
application.load(definitionsFromContext(context))

این کد مستقیما از مستندات Stimulus می‌آید و به ما اجازه می‌دهد وقتی کد برنامه را ایجاد می‌کنیم، از ساختار قراردادی نامگذاری استفاده کنیم.

اگر از کد index.js استفاده می‌کنید، در حقیقت نامگذاری فایل شما برای Stimulus اهمیت دارد (این نکات مواردی هستند که توسعه‌دهنده Rails با آن آشنا خواهد بود).

حالا که تمام مراحل راه‌اندازی شده است، اجازه دهید ببینیم Webpack کار می‌کند. از پوشه روت دستور زیر را اجرا کنید:

1	`npx webpack src/index.js dist/bundle.js --watch`

قسمت npx این دستور، راهی مناسب برای اجرای باینری است که در پوشه node_modules قرار دارد. این دستور بر تغییرات فایل‌های جاوااسکریپت نظارت دارد و همانطور که این تغییرات را انجام می‌دهد برنامه شما را مجددا بازسازی (rebuild) می‌کند.

تا زمانی که خطاها را در کنسول مشاهده نمی‌کنید، خوب پیش می‌روید.

Controllerها

اگر شما با Rails یا Laravel آشنا هستید، ممکن است مفهوم کنترلرها برای شما آسان باشد.

در مورد کنترلر در Stimulus به عنوان کلاس جاوا اسکریپتی که شامل برخی متدها و داده‌هایی است که با هم کار می‌کنند، فکر کنید.

یک کنترلر در Stimulus ممکن است اینگونه باشد:

<div data-controller="refreshable">
<!-- more soon... -->
</div>

// src/controllers/refreshable_controller.js
import { Controller } from "stimulus"
  
export default class extends Controller {
}

چند نکته مهم در رابطه با این کنترلر وجود دارد. اول اینکه کنترلر هم HTML و هم JavaScript است. ویژگی data-controller چیزی است که به جاوااسکریپت برای ایجاد نمونه ای از کلاس می‌گوید.

یکی دیگر از ویژگی‌های جالب توجه این است که نام کلاس در هیچ جایی از خود کلاس کنترلر یافت نمی‌شود. این اتفاق به دلیل وجود خط application.load(definitionsFromContext(context)) در فایل index.js رخ می‌دهد. این خط کد برنامه را بارگیری کرده و از نام فایل‌ها برای نام کلاس‌های استخراج شده استفاده می‌کند. این مسأله ممکن است در ابتدا گیج‌کننده باشد،‌ اما هنگامی که به طور منظم شروع به استفاده از این قرارداد می‌کنید، راحت‌تر می‌شود.

Actionها

یک اکشن را می‌توان اینگونه تعریف کرد: عملی که می‌خواهید پس از یک رویداد خاص از طرف یک کاربر انجام شود. برای رفرش کنترلرمان،‌ می‌خواهیم وقتی روی دکمه‌ای کلیک شد، رفرش در یک ناحیه خاصی اجرا شود. در این مورد اکشن ما refresh نامگذاری می‌شود.

// src/controllers/refreshable_controller.js
import { Controller } from "stimulus"
  
export default class extends Controller {
  refresh(){
    console.log("refresh!")
  }
}

اما فقط داشتن این اکشن متد قابل دسترس در کنترلر ما نمی تواند هیچ کاری انجام دهد. ما باید آن را به HTML متصل کنیم.

<div data-controller="refreshable">
  <button data-action="refreshable#refresh">Refresh</button>
</div>

وقتی کاربر روی دکمه در این HTML کلیک می‌کند، اکشن refresh در کنترلر اجرا می‌شود.

حالا چگونه می‌توانیم از این اکشن برای انجام کاری در صفحه استفاده کنیم؟

Targetها

Stimulus همچنین از مفهومی به نام " Targets" برای اتصال به عناصر مهم صفحه استفاده می‌کند. ما از این مورد برای مدیریت نگهدارنده (container) عناصری که محتوایی که می‌خواهیم رفرش کنیم را نگه می‌دارد، استفاده می کنیم.

<div data-controller="refreshable">
  <button data-action="refreshable#refresh">Refresh</button>
  <article data-target="refreshable.content"></article>
</div>

// src/controllers/refreshable_controller.js
import { Controller } from "stimulus"
  
export default class extends Controller {
  
  static targets = [ "content" ]
  
  refresh(){
    this.contentTarget.innerHTML = "Refresh!"
  }
  
}

در این مثال ما سه مفهوم نمایش Stimulus را داریم. کنترلر refreshable، اکشن refresh و تارگت content.

اگر به طور دقیق نگاه کنید، متوجه می‌شوید که می‌توانید به صورت مستقیم DOM را بکار گیرید. این مسأله یکی از مواردی است که Stimulusرا از دیگر فریم‌ورک‌ها متمایز کرده است. بکارگیری و دستکاری مستقیم عناصر DOM نه تنها امکان‌پذیر است بلکه باعث تقویت آن نیز می‌شود.

این بدان معناست که اگر شما در jQuery یا vanilla JavaScript و APIهای مرورگر خوب باشید، می‌توانید از مزیت‌های این دانش استفاده کنید. مثلا یک نسخه جی‌کوئری از متد refresh ممکن است مانند دستور زیر باشد:

// src/controllers/refreshable_controller.js
import { Controller } from "stimulus"
import $ from 'jquery'; // requires adding jQuery to package.json
  
export default class extends Controller {
  
  static targets = [ "content" ]
  
  refresh(){
    let target = this.contentTarget;
    $.get("/content", function(content){
      $(target).html(content)
    })
  }
  
}

اگر می‌خواهید از ابزارهای دیگری که از قبل با آن‌ها آشنا هستید استفاده کنید، Stimulus هیچ محدودیتی در کار شما ایجاد نمی‌کند.

نتیجه‌گیری

شما اکنون اطلاعات کافی برای شروع ساخت برنامه‌های قابل نگهداری با Stimulus را کسب کرده‌اید. توسعه‌دهندگانی که Stimulus را ایجاد کرده‌اند به ما یادآوری می‌کنند که قوانین و روندها می‌توانند شکسته شوند و گاهی اوقات می‌توانیم از بهترین شیوه‌ها دور شویم و فقط از همان شیوه‌ای استفاه کنیم که برایمان کار می‌کند.

معرفی فریم ورک Stimulus برای علاقه‌مندان به HTML

نظرات کاربران در رابطه با این دوره