این راهنما مقدمی ای بر کتابخانه JQuery است. برای ادامه به آشنایی مقدماتی با جاوااسکریپت و document object model (DOM) نیاز است. این راهنما از سطح پایین شروع و در صورت لزوم جزئیات را توضیح می دهد. یک مثال hello world هم آورده می شود، اصول selector و رخدادها، AJAX، FX و استفاده و مدیریت پلاگین ها آموزش داده می شود.
این راهنما شامل مثال های "click me" نمی باشد هدف از استفاده از کد "copy me" ترغیب شما به تست است. یک مثال را کپی نحوه کار ان را ببینید و انرا دستکاری کنید.
Setup
برای شروع کار، به یک کپی از کتابخانه JQuery نیاز داریم، که میتوانیم از سایت jquery.com دانلود کنیم. jQuery Starterkit چندین markup و CSS اماده دارد. بعد از دانلود و باز کردن محتویات ما فایل jquery.js را در همان پوشه برنامه مان قرار داده و فایل starterkit.html و custom.js را با برنامه ویرایشگرمان باز می کنیم. فایل startkit.html را با مرورگر نیز باز کنید.
الان تمام ابزار برای شروع با مثال "hello world" را داریم.
سلام JQuery
با یک صفحه خالی html شروع می کنیم:
1:
2:
3: <html>
4:
5: <head>
6:
7: <script type="text/javascript"
8: src="jquery.js"></script>
1:
2:
3: <script type="text/javascript">
4:
5: // we will add our javascript code here
6: </script>
9:
10: </head>
11:
12: <body>
13:
14: <!-- we will add our HTML content here
15: -->
16:
17: </body>
18:
19: </html>
این صفحه فقط کتابخانه jquery.js را لود می کند ( مطمئن شوید مقدار URL به آدرس فایل jquery شما اشاره می کند! برای این مثال فرض شده که فایل jquery.js در پوشه فایل html قرار دارد). دو کامنت مشخص شده را گسترش خواهیم داد.
از انجا که تقریبا تمام کارهای ما با jQuery شامل خواندن و دستکاری document object model (DOM) می شود، باید مطمئن شویم که به محض آماده شدن DOM رخدادها را اضافه کنیم.
به این منظور، یک رخداد ready را برای document رجیستر می کنیم:
1: $(document).ready(function() { // do stuff when DOM is ready });
قرار دادن یک کد هشدار دهنده درون این تابع معقول نیست، چون کد هشدار نیازی به اماده بودن DOM ندارد. اجازه دهید چیز پیچیده تری را آزمایش کنیم: نشان دادن یک هشدار هنگام کلیک شدن یک لینک.
کد زیر را به تگ <body> اضافه کنید:
حالا $(document).ready را آپدیت کنید:
1: $(document).ready(function() { $("a").click(function() { alert("Hello world!"); }); });
حالا به محض کلیک کردن روی لینک باید یک هشدار نمایان شود. حالا می توانید کد را درون فایل custom.js کپی کنید. سپس، فایل starterkit.html را با مرورگرتان باز کرده و بر روی یک لینک کلیک کنید. روی هر لینکی که کلیک کنید باید یک پنجره pop-up با پیغام "hello world!" ببینید.
اجاز دهید نگاهی به کارمان بیندازیم: $("a") یک jQuery selector است، که در مثال بالا تمام عناصر از نوع a را انتخاب می کند. $ نام مستعاری برای کلاس jQuery است.بنابراین $() یک شی jQuery جدید می سازد. تابع click() که در ادامه صدا می زنیم یکی از متدهای شی jQuery است. این کار یک رخداد کلیک را به تمام عناصر انتخاب شده ( در این مثال، یک عنصر anchor) پیوست کرده و هنگام رخداد آن تابع را اجرا می کند.
این مشابه کد زیر است:
1: <a href="" onclick="alert('Hello world')">Link</a>
تفاوت واضح است: لازم نیست ما برای هر عنصر یک onclick بنویسیم. ما به طور شفاف ساختار (HTML) را از رفتار (JS) جدا کرده ایم، درست همانطور که ساختار را از نحوه نمایش (CSS) جدا کرده ایم.
در ادامه selector ها و رخدادها را کمی بیشتر برسی می کنیم.
استفاده از selector ها و رخدادها
jQuery دو روش برای انتخاب عناصر دارد. در روش اول از ترکیب selector های XPath و CSS استفاده می شود که به صورت string به سازنده jQuery فرستاده می شود (مثلا $("div > ul a")). روش دوم از متد های شی jQuery استفاده می کند. این دو روش را میتوان ترکیب کرد.
برای ازمایش این selector ها، اولین لیست مرتب starterkit را انتخاب و تغییر می دهیم.
برای شروع، خود لیست را انتخاب میکنیم. آی دی لیست "orderedlist" است. در جاوااسکریپت، می توان با کد document.getElementById("orderedlist") انرا انتخاب کرد. با jQuery اینگونه کار می کنیم:
1: $(document).ready(function() { $("#orderedlist").addClass("red"); });
starterkit یک stylesheet با کلاس "red" دارد که یک پس زمینه قرمز رنگ را به عنصر اضافه می کند. بنابراین، وقتی صفحه را در مرورگر دوباره لود کنیم، اولین لیست مرتب باید پس زمینه قرمز داشته باشد. لیست دوم تغییر نکرده است.
حالا اجازه دهید به عناصر زیرشاخه لیست کلاس های دیگری اضافه کنیم.
1: $(document).ready(function() { $("#orderedlist > li").addClass("blue"); });
این کد تمام li های عنصری که آی دی ان orderedlist است را انتخاب و کلاس "blue" را به انها اضافه می کند.
حالا یک کار کمی پیچیده تر: می خواهیم هنگامی که کاربر موس را روی عنصر li نگه می دارد کلاس را اضافه و حذف کنیم، اما فقط برای اخرین عنصر داخل لیست.
1: $(document).ready(function() { $("#orderedlist li:last").hover(function() { $(this).addClass("green"); },function(){ $(this).removeClass("green"); }); });
selector های بسیاری با ساختار CSS و XPath وجود دارد.
برای هر رخداد به صورت onxxx، مانند onclick،onchange، onsubmit، یک معادل در jQuery وجود دارد. برخی رخدادهای دیگر، مانند Ready و hover برای سهولت بیشتر فراهم شده است.
با این Selector ها و رخدادها می توان کار های زیادی انجام داد، ولی Selector های دیگری هم وجود دارد.
1: $(document).ready(function() { $("#orderedlist").find("li").each(function(i) { $(this).append( " BAM! " + i ); }); });
find() برای جستجوی زیرعنصرهای درون عناصر انتخاب شده است، بنابراین $("#orderedlist").find("li") تقریبا همان $("#orderedlist li") است.
each() برای پویش تک تک عناصر و پردازش بیشتر است. بیشتر متدها، مانند addClass() خود از متد each() استفاده می کنند.
در این مثال، از append() برای الحاق یک متن به ان و قرار دادن ان در انتهای هر عنصر استفاده شده است.
کار دیگری که اغلب نیاز است انجام دهیم فراخوانی متدهای عناصر DOM است که در jQuery وجود ندارد. تصور کنید می خواهید یک فرم را بعد از اینکه با AJAX ارسال شد ریست کنید.
1: $(document).ready(function() { // use this to reset a single form $("#reset").click(function() { $("form")[0].reset(); }); });
این کد اولین فرم را انتخاب و تابع Reset() ان را صدا می زند. اگر بیش از یک فرم دارید این کار را بکنید:
1: $(document).ready(function() { // use this to reset several forms at once $("#reset").click(function() { $("form").each(function() { this.reset(); }); }); });
این کد تمام فرم های document را انتخاب کرده، انها را پویش و متد Reset() را برای تک تک انها فراخوانی می کند. دقت کنید که در تابع .each() ، this به خود عنصر اشاره می کند. همچنین از انجایی که تابع Reset() به فرم تعلق دارد و نه شی jQuery، نمی توانیم برای ریست کردن تمام فرمهای صفحه از $("form").reset() استفاده کنیم.
یک مسئله دیگر انتخاب عناصر خاصی از بین یک گروه از عناصر مشابه یا یکسان است. برای این منظور jQuery توابع filter() و not() را فراهم اورده است. filter() انتخاب ها را بر اساس جمله ***** کاهش می دهد در حالی که not() برعکس تمام عناصری که با جمله ان سازگاز است را حذف میکند. تصور کنید می خواهید در یک لیست مرتب تمام li هایی که دارای زیر عنصرهای ul نیستند را انتخاب کنبد.
1: $(document).ready(function() { $("li").not(":has(ul)").css("border", "1px solid black"); });
این کد تمام عنصر های li که دارای زیر عنصرهای ul هستند را انتخاب و انها را از محدوده انتخاب ها حذف می کند. بنابراین تمام li هایی که زیرعنصر ul ندارند لبه دار می شوند.
شکل دستوری [expression] از XPath گرفته شده است و می توان برای ***** کردن بر اساس attribute ها از ان استفاده کرد. ممکن است بخواهید تمام anchorهایی که دارای نام هستند را انتخاب کنید:
1: $(document).ready(function() { $("a[name]").css("background", "#eee" ); });
این کد به تمام anchorهایی که دارای attribute با نام name هستند پس زمینه اضافه می کند.
ممکن است به جای نام نیاز باشد یک anchor را بر اساس href attribute ان انتخاب کنید. این ممکن است مشکل ساز باشد چون مقدار href که مرورگرهای مختلف بر می گردانند نا سازگار با هم است ( این مشکل در jQuery ورژن های بالاتر از 1.1.1 حل شده است). برای تطبیق فقط یک بخش از مقدار می توان از contains select "*=" به جای تساوی "=" استفاده کرد:
1: $(document).ready(function() { $("a[href*='/content/gallery']").click(function() { // do something with all links that point somewhere to /content/gallery }); });
تا اینجا، تمام selector ها برای انتخاب زیرعنصرها و ***** کردن استفاده شد. حالاتی وجود دارد که می خواهیم عنصر بعدی یا قبلی (sibling) را انتخاب کنیم. یک صفحه "سوالات متداول" را تصور کنید که تمام پاسخ ها در ابتدا پنهان است، و هنگامی که روی سوال کلیک می شود پاسخ ان ظاهر می شود. کد jQuery برای این:
1: $(document).ready(function() { $('#faq').find('dd').hide().end().find('dt').click (function() { $(this).next().slideToggle(); }); });
در اینجا برای کم کردن طول کد از chaining استفاده کرده ایم،و چون "#faq" فقط یکبار انتخاب می شود افزایش سرعت و کارایی را خواهیم داشت. استفاده از end()، اولین find() خنثی را می کند. بنابراین، find() دوم جستجو را با شروع از عنصر #faq (در عوض زیر عنصرهای dd)، انجام می دهد .
درون کد پردازشگر رخداد کلیک،همان تابعی که به متد click() فرستاده شده، از $(this).next() برای پیدا کردن sibling بعدی با شروع از dt کنونی استفاده کرده ایم. به این شکل می توانیم به سرعت پاسخ پرسش کلیک شده را بیابیم.
علاوه بر sibling ها، می توانیم عنصرهای والد را نیز انتخاب کنیم ( در XPath انها را با نام ancestor می شناسیم). ممکن است بخواهید پاراگراف والد لینکی که کاربر ماوس را روی ان نگه داشته، هایلایت کنید. این کد را ازمایش کنید:
1: $(document).ready(function(){ $("a").hover(function(){ $(this).parents("p").addClass("highlight"); },function(){ $(this).parents("p").removeClass("highlight"); }); });
برای تمام لینک ها، پاراگراف والد جستجو . کلاس "highlight" اضافه و حذف می شود.
اجازه دهید قبل از ادامه دادن یک قدم به عقب برگردیم: jQuery برای کوتاه تر کردن کد و ساده تر کردن خواندن و نگهداری است. کد زیر میانبری برای $(document).ready(callback) است:
1: $(function() { // code to execute when the DOM is ready });
اگر انرا به مثال hello world! اعمال کنیم خواهیم داشت:
1: $(function() { $("a").click(function() { alert("Hello world!"); }); });
حالا که اصول را می دانیم، می خواهیم جتبه های دیگری از jQuery را برسی کنیم. اول AJAX.
استفاده از AJAX
در این بخش یک برنامه کوچک AJAX می نویسیم که کاربر می تواند با ان مانند سایت youtube.com، به یک مطلب امتیاز دهد.
برای این کار به کمی کد سرور نیاز داریم. مثال من از یک فایل php استفاده می کند که پارامتر rating را خوانده و تعداد و متوسط امتیازها را بر می گرداند.
ما نمی خواهیم این کد بدون AJAX کار کند، هر چند امکان پذیر است، بنابراین ما کد markup مورد نیاز را با jQuery نوشته، انرا به یک container div با آی دی "rating" الحاق می کنیم.
1: $(document).ready(function() { // generate markup $("#rating").append("Please rate: "); for ( var i = 1; i <= 5; i++ ) { $("#rating").append("<a href='#'>" + i + "</a>"); } // add markup to container and apply click handlers to anchors $("#rating a").click(function(e) { // stop normal link click e.preventDefault(); // send request $.post("rate.php", {rating: $(this).html()}, function(xml) { // format and output result $("#rating").html( "Thanks for rating, current average: " + $("average", xml).text() + ", number of votes: " + $("count", xml).text() ); }); }); });
این تکه کد پنج عنصر از نوع anchor تولید و انرا به عنصر container با آی دی"rating" الحاق می کند. سپس، برای هر anchor درون container ، یک پردازشگر رخداد کلیک اضافه می شود. هنگامی که anchor کلیک می شود، یک درخواست post همراه با محتویات ان anchor به عنوان یک پارامتر به rate.php فرستاده می شود. نتیجه که به صورت XML برگردانده می شود به container اضافه شده و جایگزین anchor می شود.
یک مشکل متداول هنگام لود کردن با استفاده از Ajax این است: هنگام اضافه کردن پردازشگرهای رخدادها به document، این پردازشگر ها باید مجددا به محتویات لود شده هم اعمال شود، برای جلوگیری از دوباره نویسی کد، می توان از delegate کردن تابع استفاده کرد. مثلا:
1: function addClickHandlers() { $("a.remote", this).click(function() { $("#target").load(this.href, addClickHandlers); }); } $(document).ready(addClickHandlers);
حالا addClickHandlers یکبار هنگامی که DOM لود شد و سپس هر بار که کاربر لینکی با کلاس remote را کلیک کند و لود شدن محتویات تمام شده باشد، اجرا می شود.
به کد پرس و جوی $("a.remote", this) دقت کنید، this به صورت موقعیتی(context) فرستاده شده است: برای رخداد document ready، شی this به document اشاره دارد، بنابراین تمام document برای anchorهایی با کلاس remote جستجو می شود. هنگامی که از addClickHandlers به صورت یک Callback برای load() استفاده می شود، this به یک عنصر دیگر اشاره دارد: در این مثال، عنصری با آی دیtarget . این مانع از این می شود که رخداد کلیک چندبار به یک لینک اعمال شود و نهایتا منجر به از کار افتادن برنامه شود.
مشکل دیگر Callback ها پارامترها هستند. Callback خود را مشخص کرده اید ولی نیاز دارید یک پارامتر اضافه به ان بفرستید. ساده ترین راه قرار دادن Callback درون یک تابع دیگر است:
1: // get some data var foobar = ...; // specify handler, it needs data as a paramter function handler(data) { //... } // add click handler and pass foobar! $('a').click(function() { handler(foobar); }); // if you need the context of the original handler, use apply: $('a').click(function() { handler.apply(this, [foobar]); });
با Ajax بخش زیادی از وب 2.0 را می توانیم پوشش دهیم. حالا که به اصول Ajax نگاهی انداخته ایم، بگذارید چند افکت ساده و انیمیشن به صفحه اضافه کنیم.
افکت ها
انیمیشن های ساده را می توان با show() و hide() پیاده کرد.
1: $(document).ready(function(){ $("a").toggle(function(){ $(".stuff").hide('slow'); },function(){ $(".stuff").show('fast'); }); });
با animation() می توانید هر ترکیبی از انیمیشن را مانند slide و fade بسازید:
1: $(document).ready(function(){ $("a").toggle(function(){ $(".stuff").animate({ height: 'hide', opacity: 'hide' }, 'slow'); },function(){ $(".stuff").animate({ height: 'show', opacity: 'show' }, 'slow'); }); });
نوشتن پلاگین
نوشتن پلاگین برای jQuery ساده است. اگر قوائد زیر را رعایت کنید استفاده از پلاگین شما برای دیگران هم ساده می شود.
نامگذاری پلاگین
نام پلاگین تان را انتخاب کنید، مثلا "foobar" . حالا یک فایل با نام jquery.[yourpluginname].js بسازید، یعنی jquery.foobar.js.
افزودن یک متد
با گسترش شی jQuery یک یا چند متد بسازید:
1: jQuery.fn.foobar = function() { // do something };
برای دسترسی به این متد از این کد استفاده می کنیم:
تنظیمات پیش فرض
تنظیمات پیش فرض را بنویسید که توسط کاربر قابل تغییر است، مثلا:
1: jQuery.fn.foobar = function(options) { var settings = jQuery.extend({ value: 5, name: "pete", bar: 655 }, options); };
برای صدا زدن پلاگین بدون option ها و با استفاده از مقادیر پیش فرض:
یا با چند پیش فرض:
1: $("...").foobar({ value: 123, bar: 9 });
مستند سازی
اگر پلاگین خود را منتشر می کنید، باید همراه ان چند مثال و مستندات ارایه کنید.
حالا که با اصول ساخت پلاگین اشنا شدید اجازه دهید از ان استفاده و یک پلاگین بسازیم.
پلاگین checkbox
هنگام دستکاری فرم ها با jQuery بیشتر کاربران نیاز به تیک زدن یا تیک برداشتن radiobutton ها و checkbox ها دارند. انها معمولا به این کد می رسند:
1: $(":checkbox").each(function() { this.checked = true; this.checked = false; // or, to uncheck this.checked =!this.checked; // or, to toggle });
هر گاه در کدتان یک each دارید می توانید سرراست انرا به صورت پلاگین بنویسید:
1: jQuery.fn.check = function() { return this.each(function() { this.checked = true; }); };
الان می توان از پلاگین استفاده کرد:
1: $(":checkbox").check();
حالا می توانید هم برای uncheck() و هم برای toggleCheck() پلاگین بنویسید. در عوض پلاگین مان را طوری تغییر می دهیم که option بگیرد.
1: jQuery.fn.check = function(mode) { // if mode is undefined, use 'on' as default var mode = mode || 'on'; return this.each(function() { switch(mode) { case 'on': this.checked = true; break; case 'off': this.checked = false; break; case 'toggle': this.checked =!this.checked; break; } }); };
با نوشتن مقدار پیش فرض برای option ، کاربر می تواند option را حذف و یا یکی از مقادیر "on"، "off"، یا "toggle" را بفرستد. یعنی:
1: $(":checkbox").check(); $(":checkbox").check('on'); $(":checkbox").check('off'); $(":checkbox").check('toggle');
