آموزش Elixir در Laravel در لاراول

Elixir در Laravel

1. مقدمه
2. نصب و راه اندازی
3. اجرا و راه اندازی Elixir
4. کار با صفحات سبک دهی (stylesheets)
   • فایل های Less
   • فایل های Sass
   • CSS خالص
   • Source Map ها
5. کار با اسکریپت ها
   • CoffeeScript
   • تابع browserify
   • تابع babel
   • اسکریپت ها
6. کپی فایل ها و پوشه ها
7. متد version و نسخه سازی / cache busting
8. متد browsersync
9. فراخوانی Gulp task های جاری
10. نوشتن افزونه های Elixir در لاراول

مقدمه

سرویس Elixir در چارچوب نرم افزاری لاراول با ارائه ی API های کارامد و بهینه به شما این امکان را می دهد تا Gulp task های پایه و آسان برای برنامه های کاربردی خود بنویسید.
Elixir از پیش پردازنده های (pre-processor) رایج جاوا اسکریپت و CSS و نیز ابزار تست واحد پشتیبانی می کند که انجام بسیاری از فرایند های تکراری و زمان بر را به مراتب آسان می سازد.
با بهره گیری از قابلیت فراخوانی زنجیره ای متدها، Elixir به شما اجازه می دهد asset pipeline خود را به صورت روان و بهینه تعریف نمایید (pipeline: خط لوله متشکل از زنجیره‌ای از پردازش عناصر (فرایندها، thread ها و غیره..)، مرتب شده است به طوری که خروجی هر عنصر ورودی عنصر بعدی می‌باشد). مثال:

elixir(function(mix) {
   mix.sass('app.scss')
      .coffee('app.coffee');
});

اگر قبلا در نحوه ی شروع به کامپایل Gulp و asset با مشکلات و سردرگمی مواجه می شدید، باید بگیم که Elixir تمامی این دست مشکلات را بر طرف می سازد. لازم به ذکر است برای توسعه و نوشتن برنامه ی خود ملزوم به استفاده از این سرویس نبوده و آزادید از هر asset pipeline ای که مایل به استفاده از آن هستید، بهره بگیرید.

نصب و راه اندازی

پیش از راه اندازی Elixir بایستی Node.js را بر روی دستگاه خود نصب نمایید.

نصب Node

                    node -v

به صورت پیش فرض، ماشین مجازی Homestead تمام آنچه برای نوشتن اپلیکیشن تحت وب به آن نیاز دارید را در اختیارتان قرار می دهد. اما اگر از Vagrant استفاده نمی کنید، در آن صورت می توانید با مراجعه به صفحه ی دانولد آن Node را به آسانی دریافت نموده و نصب کنید.

نصب Gulp

در گام بعدی بایستی با اجرای دستور زیر، Gulp را به صورت global و به عنوان یک پکیج NPM سراسری نصب نمایید:

                    npm install --global gulp

اگر از یک سیستم کنترل ورژن نیز استفاده می کنید، در آن صورت بد نیست دستور npm shrinkwrap را برای اعمال قفل بر روی requirement(dependency های واکشی شده توسط متد require) NPM خود اجرا نمایید:

                    npm shrinkwrap

پس از اجرای این دستور می توانید npm-shrinkwrap.json را در source control تایید ثبت نمایید.

Elixir در لاراول

تنها گام باقی مانده نصب Elixir می باشد. پس از نصب فریم وروک لاراول، در پوشه ی root آن یک فایل به نام package.json مشاهده می کنید. این فایل به مثابه ی فایل composer.json ایفای نقش می کند با این تفاوت که بجای PHP، dependency های Node (مخزن آنلاین ماژول ها) را ایجاد می کند. با اجرای دستور npm install، تمامی dependency هایی مورد اشاره ی این پکیج (که به طور پیش فرض به آن اضافه شده اند) را نصب نمایید.
اگر برای توسعه ی برنامه ی خود از سیستم عامل ویندوز استفاده کرده و یا ماشین مجازی خود را بر روی سیستم میزبانی ویندوز (Windows host system) اجرا می کنید، در آن صورت می بایست گزینه ی--no-bin-links را همراه با دستور npm install را فراخوانی نمایید:

npm install --no-bin-links

اجرا و راه اندازی Elixir

Elixir بر اساس Gulp پایریزی شده، از اینرو جهت اجرای Elixir task های خود (اجرای تمامی وظایف و کارها) ابتدا لازم است دستور gulp را در پنجره ی فرمان (terminal) صدا بزنید. افزودن فلگ (پارامتر) --production به دستور مورد نظر در واقع به Elixir اعلان می کند که بایستی فایل های CSS و جاوا اسکریپت اپلیکیشن را کم حجم و بهینه (Minify) نماید:

// Run all tasks...
gulp
// Run all tasks and minify all CSS and JavaScript...
gulp --production

تحت نظر داشتن و رصد تغییرات Asset ها

اجرای دستور gulp پس از هر بار تغییر در asset داخل پنجره ی فرمان کمی دشوار است. برای رفع این مشکل می توانید بجای دستور مزبور، gulp watch را فرخوانی نمایید زیرا که این دستور تمامی asset ها و تغییرات ایجاد شده در آن ها را رصد می کند. در واقع فرمان gulp watch همچنان به اجرا در پنجره ی فرمان ادامه داده و در این میان تمامی تغییراتی که در asset ها وارد می شود را دنبال می کند. با ایجاد هر گونه تغییر جدید درasset (مثلا ویرایش کدها، این تغییرات شناسایی شده و) فایل های جدید به صورت خودکار کامپایل می شوند:

                    gulp watch

کار با صفحات سبک دهی (stylesheet)

فایل gulpfile.js مقیم در پوشه ی root پروژه، دربردارنده ی تمامی task های Elixir اپلیکیشن شما می باشد. با متصل کردن این task ها به صورت زنجیره ای به یکدیگر می توانید نحوه ی کامپایل asset های برنامه را مشخص نمایید.

فایل های Less

با فراخوانی تابع less می توانید فایل های Less را به CSS کامپایل نمایید. متد ذکر شده فرض می گیرد کلیه ی فایل های Less اپلیکیشن شما در مسیر resources/assets/less نگهداری می شوند. به طور پیش فرض task مربوطه، CSS کامپایل شده ی این مثال را در فایلpublic/css/app.css جایگذاری می کند:

elixir(function(mix) {
   mix.less('app.less');
});

همچنین می توانید چندین فایل Less را ترکیب نموده و در قالب یک فایل CSS واحد بگنجانید. این فایل CSS خروجی نیز در مسیرpublic/css/app.css جایگذاری می شود:

elixir(function(mix) {
   mix.less([
       'app.less',
       'controllers.less'
   ]);
});

در صورت تمایل می توانید مکان قرار گیری خروجی فایل کامپایل شده ی CSS خود را سفارشی تنظیم نمایید. برای این منظور می بایست یک پارامتر دوم به تابع less پاس دهید:

elixir(function(mix) {
   mix.less('app.less', 'public/stylesheets');
});
// Specifying a specific output filename...
elixir(function(mix) {
   mix.less('app.less', 'public/stylesheets/style.css');
});

فایل های Sass

متد sass به شما این امکان را می دهد تا فایل های Sass خود را به CSS کامپایل کنید. با فرض اینکه فایل های Sass شما در مسیرresources/assets/sass ذخیره شده اند، می توانید متد مذکور را به صورت زیر بکار ببرید:

elixir(function(mix) {
   mix.sass('app.scss');
});

متد sass نیز درست مانند متد less به شما این اجازه را می دهد تا چندین فایل Sass را با یکدیگر ادغام و در قالب یک فایل واحد CSS بگنجانید و حتی در صورت نیاز مسیر قرارگیری خروجی (فایل CSS حاصل شده) را مطابق میل تنظیم نمایید:

elixir(function(mix) {
   mix.sass([
       'app.scss',
       'controllers.scss'
   ], 'public/assets/css');
});

CSS خالص

می توانید تعدادی Stylesheet (صفحه ی سبک دهی CSS) را با هم ترکیب کرده و در قالب یک فایل واحد CSS بگنجانید. این امکان با فراخوانی متد styles برای شما فراهم می شود. Path هایی که به عنوان آرگومان ورودی به این متد پاس داده شده اند، در واقع نسبت (relative) به دایرکتوری resources/assets/css سنجیده شده و CSS خروجی در واقع در مسیر public/css/all.css قرار داده می شود:

elixir(function(mix) {
   mix.styles([
       'normalize.css',
       'main.css'
   ]);
});

می توانید فایل حاصل شده را در مکان قرارگیری مد نظر خود جای گذاری کنید. کافی است یک مقدار به عنوان آرگومان دوم به متد styles ارسال نمایید:

elixir(function(mix) {
   mix.styles([
       'normalize.css',
       'main.css'
   ], 'public/assets/css');
});

Source map ها

Source map ها به صورت آماده و از پیش تنظیم شده در اختیار شما قرار داده می شوند. از اینرو به ازای هر فایلی که کامپایل می شود، یک فایل*.css.map همراه نیز در همان پوشه ایجاد می شود. این mapping، در زمان عیب یابی داخل مرورگر به شما امکان می دهد تا selector های فایل های CSS کامپایل شده را ردیابی و در فایل های اصلی Sass و Less اپلیکیشن خود پیدا نمایید.
(source map به شما در عیب یابی فایل های css و javascript کمک می کند).
اگر نمی خواهید از source map های ایجاد شده برای CSS استفاده نمایید، در آن صورت می بایست گزینه ی elixir.config.sourcemaps را با پارامتر false مقدار دهی کنید:

elixir.config.sourcemaps = false;
elixir(function(mix) {
   mix.sass('app.scss');
});

کار با اسکریپت ها

Elixir توابع متعددی برای کار با فایل های JavaScript ارائه می کند که از جمله ی آن ها می توان به تابع مخصوص کامپایل ECMAScript 6،CoffeeScript، Browserify، کم حجم و بهینه سازی (minification) و الحاق (concat) فایل های خالص و ساده ی جاوا اسکریپت اشاره کرد.

متد coffee

متد coffee را می توان برای کامپایل CoffeeScript به فایل های ساده ی JavaScript مورد استفاده قرار داد. تابع coffee رشته یا آریه ای از فایل های CoffeeScript را نسبت به پوشه یا آدرس resources/assets/coffee به عنوان پارامتر ورودی پذیرفته و یک فایلapp.js را در پوشه ی public/js ایجاد می کند:

elixir(function(mix) {
   mix.coffee(['app.coffee', 'controllers.coffee']);
});

متد browserify

Elixir همچنین یک متد به نام browserify عرضه می کند که تمامی مزایای فراخوانی ماژول ها در مرورگر و استفاده از ECMAScript 6 و JSX را برای توسعه دهنده فراهم می نماید (این متد به شما اجازه می دهد تا با bundle کردن dependency ها، ماژول ها را با متد require() در مرورگر فراخوانی نمایید).
task موجود در مثال زیر فرض می گیرد که اسکریپت های پروژه ی شما در آدرس resources/assets/js ذخیره شده و فایل خروجی را در مسیرpublic/js/main.js جایگذاری می کند. می توانید با ارسال مقداری دیگر به عنوان پارامتر دوم، مکان قرارگیری این فایل خروجی را خود تعیین نمایید:

elixir(function(mix) {
   mix.browserify('main.js');
});
// Specifying a specific output filename...
elixir(function(mix) {
   mix.browserify('main.js', 'public/javascripts/main.js');
});

متد Browserify به صورت پیش فرض با دو تبدیلگر (transformer) Partialify و Babelify عرضه می شود. با این حال می توان تبدیلگر های اختصاصی خود را به صورت زیر نصب و اضافه نمایید:

npm install aliasify --save-dev
elixir.config.js.browserify.transformers.push({
   name: 'aliasify',
   options: {}
});
elixir(function(mix) {
   mix.browserify('main.js');
});

متد Babel

متد babel() را می توان به منظور کامپایل ویرایش 6 و 7 ECMAScript و JSX به جاوا اسکریپت ساده مورد استفاده قرار داد. این تابع آرایه ای از فایل ها را نسبت به دایرکتوری resources/assets/js (آدرس دهی شده) به عنوان پارامتر پذیرفته و سپس یک فایل all.js در پوشه یpublic/js ایجاد می کند:

elixir(function(mix) {
   mix.babel([
       'order.js',
       'product.js',
       'react-component.jsx'
   ]);
});

به منظور انتخاب یک مکان دیگر برای ذخیره ی خروجی، کافی است path دلخواه را به عنوان آرگومان دوم به تابع ارسال کنید. به استثنای قابلیت کامپایل Babel، این متد از نظر signature )تعداد پارامتر ورودی و نوع آن ها( و کاری که انجام می دهد با mix.scripts() تفاوتی ندارد.

اسکریپت ها

چنانچه چندین فایل جاوا اسکریپت در پروژه ی خود دارید و اکنون می خواهید همه ی آن ها را در قالب یک فایل واحد ترکیب نمایید، در آن صورت می توانید متد scripts را فراخوانی نمایید.
متد ذکر شده در بالا فرض می گیرد تمامی path ها وابسته به دایرکتوری resources/assets/js هستند (نسبت به آن آدرس دهی و تنظیم شده) و به این خاطر فایل جاوا اسکریپت خروجی را به صورت پیش فرض در آدرسpublic/js/all.js جایگذاری می کند:

elixir(function(mix) {
   mix.scripts([
       'jquery.js',
       'app.js'
   ]);
});

حال اگر می خواهید چندین مجموعه اسکریپت را در فایل های مجزا ادغام کنید، در آن صورت لازم است متد scripts را چند بار فراخوانی نمایید. دومین آرگومان ارسالی به متد تعیین کننده ی اسم فایل خروجی به ازای هر concat جداگانه می باشد:

elixir(function(mix) {
   mix.scripts(['app.js', 'controllers.js'], 'public/js/app.js')
      .scripts(['forum.js', 'threads.js'], 'public/js/forum.js');
});

اگر می خواهید تمامی اسکریپت ها را در یک پوشه ی واحد ادغام کنید، در آن صورت می بایست تابع scriptsIn را فراخوانی نمایید. فایل جاوا اسکریپت خروجی داخل پوشه ی public/js/all.js جای می گیرد:

elixir(function(mix) {
   mix.scriptsIn('public/js/some/directory');
});

کپی فایل ها و پوشه ها

متدcopy() فایل ها و پوشه هایی را که به عنوان آرگومان به آن ارسال شده را در مسیر دلخواه کپی می کند. لازم به ذکر است که آدرس دهی به فایل های کپی شده نسبت به پوشه ی root پروژه تنظیم می شود (تمامی عملیات از دایرکتوری ریشه ی پروژه شروع می شوند):

elixir(function(mix) {
   mix.copy('vendor/foo/bar.css', 'public/css/bar.css');
});
elixir(function(mix) {
   mix.copy('vendor/package/views', 'resources/views');
});

متد version و نسخه سازی / cache busting

بسیاری از توسعه دهندگان یک timestamp یا توکن منحصربفرد به عنوان پیشوند به asset های کامپایل شده ی خود الحاق می کنند. با این کار مرورگر مجبور می شود بجای ارائه ی کپی های قدیمی از کد، asset های جدید را بارگذاری کند. Elixir با فراهم نمودن متد version این قابلیت را برای شما فراهم می کند.
متد version یک اسم فایل که نسبت به پوشه ی public آدرس دهی شده به عنوان پارامتر پذیرفته و سپس یک hash (رمز) یگانه به آن اسم فایل پیوست می کند و بدین وسیله امکان cache-busting را فراهم می آورد. اسم فایلی که خروجی این متد می باشد مشابه ی نمونه ی روبرو خواهد بود: all-16d570a7.css:

elixir(function(mix) {
   mix.version('css/all.css');
});

پس از اینکه فایل با نسخه ی جدید ایجاد شد، می توانید تابع کمکی سراسری (global helper) elixir را داخل view های اپلیکشن خود جهت بارگذاری asset رمزنگاری شده ی مربوطه، فراخوانی نمایید. تابع elixir خودش به صورت خودکار اسم فایل هش شده را تشخیص می دهد:

                <link rel="stylesheet" href="{{ elixir('css/all.css') }}">

نسخه سازی از چندین فایل

می توانید با ارسال یک آرایه به عنوان آرگومان به متد version از چندین فایل نسخه سازی نمایید:

elixir(function(mix) {
   mix.version(['css/all.css', 'js/app.js']);
});

پس از اینکه از فایل های مورد نظر نسخه های جدید ایجاد شد، می توانید تابع کمکی elixir را به منظور ایجاد لینک به فایل های رمزنگاری شده ی مربوطه صدا بزنید. یادآور می شویم که تنها بایستی اسم فایل رمزگشایی شده (unhashed) را به تابع کمکی elixir ارسال نمایید. تابع کمکی مزبور با استفاده از این پارامتر ارسالی نسخه ی هش شده ی فایل جاری را شناسایی کرده و تشخیص می دهد:

<link rel="stylesheet" href="{{ elixir('css/all.css') }}">
<script src="{{ elixir('js/app.js') }}"></script>

متد BrowserSync()

BrowserSync پس از ایجاد هر گونه تغییری در منابع سمت کاربر سایت (front-end resource)، به صورت خودکار مرورگر را refresh می کند. با بهره گیری از متد browserSync می توانید به Elixir اعلان کنید که هر زمان دستور gulp watch اجرا شد بایستی یک سرور BrowserSyncنیز راه اندازی کند:

elixir(function(mix) {
   mix.browserSync();
});

به منظور فعال سازی قابلیت همگام سازی مرورگر (browser syncing)، بایستی پس از اجرای دستور gulp watch، از طریق درگاه (port) 3000به برنامه ی خود دسترسی پیدا کنید: http://homestead.app:3000. اگر به منظور توسعه ی برنامه به صورت محلی از دامنه ای به غیر ازhomestead.app استفاده می کنید، در آن صورت می توانید آرایه ای از option ها را به عنوان آرگومان اول به متد browsersync پاس دهید:

elixir(function(mix) {
   mix.browserSync({
       proxy: 'project.app'
   });
});

فراخوانی Gulp Task های جاری

در صورت نیاز به فراخوانی gulp task جاری از Elixir، کافی است تابع task را بکار ببرید. فرض کنید یک gulp task ایجاد کرده اید که به هنگام صدا خوردن یک پیغام متنی را به صورت صوتی بخش می کند:

gulp.task('speak', function() {
   var message = 'Tea...Earl Grey...Hot';
   gulp.src('').pipe(shell('say ' + message));
});

این متد را می توانید از Elixir نیز فراخوانی کنید. برای این منظور متد mix.task را صدا زده و به عنوان تنها آرگومان اسم task را به آن ارسال کنید:

elixir(function(mix) {
   mix.task('speak');
});

ثبت watcher های سفارشی

می توانید یک watcher ثبت کرده تا با هر بار ویرایش فایل های پروژه، task سفارشی شما را اجرا کند. برای این منظور لازم است یک regular expression به عنوان آرگومان دوم به متد task ارسال کنید:

elixir(function(mix) {
   mix.task('speak', 'app*.php');
});

نوشتن افزونه های Elixir (Elixir Extension)

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

// File: elixir-extensions.js
var gulp = require('gulp');
var shell = require('gulp-shell');
var Elixir = require('laravel-elixir');
var Task = Elixir.Task;
Elixir.extend('speak', function(message) {
   new Task('speak', function() {
       return gulp.src('').pipe(shell('say ' + message));
   });
});
// mix.speak('Hello World');

کد فوق یک افزونه محسوب می شود. همان طور که می بینید منطق مربوط به Gulp باید داخل تابعی که خود به عنوان آرگومان دوم به تابع سازنده (constructor) Task ارسال شده، قرار داده شود. این افزونه را می توانید یا در بالای فایل Gulpfile قرار دهید و یا آن را در فایل اختصاصیtask ها (که خود آن را ایجاد کرده اید) جایگذاری نمایید. برای مثال اگر افزونه های خود را در elixir-extensions.js قرار داده باشید، در آن صورت می توانید فایل مورد نظر را به وسیله ی تابع require از Gulpfile اصلی خود به صورت زیر به برنامه اضافه کنید:

// File: Gulpfile.js
var elixir = require('laravel-elixir');
require('./elixir-extensions')
elixir(function(mix) {
   mix.speak('Tea, Earl Grey, Hot');
});

Watcher های سفارشی

اگر می خواهید task های سفارشیتان با اجرای دستور gulp watch مجددا راه اندازی شود، در آن صورت بایستی یک watcher به صورت زیر ثبت کنید:

                    new Task('speak', function() {
   return gulp.src('').pipe(shell('say ' + message));
})
.watch('./app/**');