A First Look at JavaScript: Making Pages Interactiveسەرەتایەک بۆ JavaScript: لاپەڕەی کارلێککار

Every web page is built in three layers (What is web design?): HTML says what each part is, CSS decides how it looks, and JavaScript decides what it does. JavaScript is a programming language whose code comes with the page and runs inside the visitor's browser, on their own phone or computer: it is Client-side code, while PHP runs on the server (Server-side and client-side languages).

هەموو لاپەڕەتۆڕێک (Web page) لە سێ چین دروست دەبێت (دیزاینی وێب چییە؟): HTML دەڵێت هەر بەشێک چییە، CSS بڕیار دەدات چۆن دەردەکەوێت و JavaScript بڕیار دەدات چی دەکات. JavaScript زمانێکی بەرنامەسازییە (Programming language) کە کۆدەکەی لەگەڵ لاپەڕەکەدا دێت و لەناو تۆڕگەڕی (Web browser) سەردانیکەردا، لەسەر مۆبایل یان کۆمپیوتەری (Computer) خۆی، کار دەکات: کۆدی لای ڕاژەخوازە (Client-side)، لە کاتێکدا PHP لەسەر ڕاژەکار (Server) کار دەکات (زمانەکانی لای ڕاژەکار و لای ڕاژەخواز).

Put your JavaScript in its own file, such as script.js, next to index.html (one site, one folder: A website is a folder). Link it in the <head> with <script src="script.js" defer></script>. defer means: download the file now, but run it only after the browser has read the whole page — so every element the script looks for already exists (Where does a script go?). It also works when you open the page by double-clicking it.

JavaScriptـەکەت لە فایلێکی تایبەت بە خۆیدا دابنێ، وەک script.js، لە تەنیشت index.html (یەک تۆڕگە (Website)، یەک فۆڵدەر (Directory): تۆڕگە فۆڵدەرێکە). لە <head>ـدا بە <script src="script.js" defer></script> بیبەستەرەوە. defer واتە: فایلەکە ئێستا دابار بکە، بەڵام تەنیا دوای ئەوەی تۆڕگەڕ هەموو لاپەڕەکەی خوێندەوە جێبەجێی بکە — بۆیە هەموو ئەو توخمانەی دەسنووسەکە بەدوایاندا دەگەڕێت پێشتر هەن (دەسنووس لە کوێ دادەنرێت؟). کاتێک لاپەڕەکە بە جووت کلیک (Double-click) دەکەیتەوەش کار دەکات.

Without defer, a script in the <head> stops the browser: it must download and run the file before it reads the rest of the HTML. The page appears later, and the script cannot find the elements below it — querySelector() gives back null, and the console shows an error (next screen).

بێ defer، دەسنووسێک لە <head>ـدا تۆڕگەڕ ڕادەگرێت: دەبێت فایلەکە دابار بکات و جێبەجێی بکات پێش ئەوەی باقیی HTML بخوێنێتەوە. لاپەڕەکە دواتر دەردەکەوێت و دەسنووسەکە ناتوانێت ئەو توخمانە بدۆزێتەوە کە لە خوارییەوەن — querySelector() نرخی null دەگەڕێنێتەوە و کۆنسۆڵ هەڵەیەک پیشان دەدات (شاشەی داهاتوو).

A modern alternative is <script type="module" src="script.js"></script>. Modules wait for the page by themselves (they are deferred by default), but browsers load them only from a web server: opened as file://, the console reports a CORS policy error. Use a local server such as Live Preview, python3 -m http.server or XAMPP (file:// or http://localhost?). This lesson uses defer, so every example also works by double-clicking.

ڕێگەیەکی نوێتر <script type="module" src="script.js"></script>ـە. ئەم جۆرە دەسنووسانە خۆیان چاوەڕێی لاپەڕەکە دەکەن (بە شێوەی بنەڕەتی دوادەخرێن)، بەڵام تۆڕگەڕەکان تەنیا لە ڕاژەکاری وێبەوە (Web server) باریان دەکەن: ئەگەر بە file:// بکرێتەوە، کۆنسۆڵ هەڵەیەکی CORS policy ڕادەگەیەنێت. ڕاژەکارێکی وێبی ناوخۆیی وەک Live Preview، python3 -m http.server یان XAMPP بەکاربهێنە (file:// یان http://localhost؟). ئەم وانەیە defer بەکار دەهێنێت، بۆیە هەموو نموونەکان بە جووت کلیکیش کار دەکەن.

Open the developer tools (F12, or right-click → Inspect) and choose Console (Browsers and developer tools). console.log() writes a message there — your best friend while you learn. When something goes wrong, the error appears in red with its type, a message and the file and line (script.js:5): click it to jump to that line. You can also type JavaScript in the console and press Enter to try it at once.

ئامرازەکانی گەشەپێدەر (Developer tools) بکەرەوە (⁦F12⁩، یان کلیکی ڕاست ← Inspect) و Console هەڵبژێرە (تۆڕگەڕ و ئامرازەکانی گەشەپێدەر). console.log() پەیامێک لەوێ دەنووسێت — باشترین هاوڕێتە لە کاتی فێربووندا. کاتێک شتێک تێکدەچێت، هەڵەکە بە سوور دەردەکەوێت لەگەڵ جۆرەکەی، پەیامێک و ناوی فایل و ژمارەی دێڕ (script.js:5): کلیکی لێ بکە بۆ ئەوەی بچیتە سەر ئەو دێڕە. هەروەها دەتوانیت JavaScript لە کۆنسۆڵدا بنووسیت و Enter دابگریت بۆ ئەوەی یەکسەر تاقی بکەیتەوە.

A variable is a named box for a value (What is a variable?). In JavaScript you make one with const when the value will not change and with let when it will — MDN's rule: "const when you can, let when you have to". The old var is not needed any more. Text goes in quotes (a string); numbers do not. A template literal is text in backticks that puts values inside with ${…}, like Python's f-strings (f-strings). Names are case-sensitive: cakesLeft is not cakesleft.

گۆڕاو سندووقێکی ناونراوە بۆ نرخێک (گۆڕاو چییە؟). لە JavaScriptـدا بە const دروستی دەکەیت کاتێک نرخەکە ناگۆڕێت و بە let کاتێک دەگۆڕێت — یاسای MDN: «const هەر کاتێک دەتوانیت، let کاتێک ناچاریت». varـی کۆن چیتر پێویست نییە. دەق لەناو نیشانەی گوتەدا (Quotation mark) دەنووسرێت (زنجیرەنووسە)؛ ژمارە نا. زنجیرەنووسەی نێو `…` ⁦(template literal)⁩ نرخەکان بە ${…} دەخاتە ناو دەقەوە (تێخستنی گۆڕاو (Variable interpolation))، وەک ⁦f-string⁩ـی Python (⁦f-string⁩). ناوەکان هەستیار بە قەبارەی پیتن (Case-sensitive): cakesLeft هەمان cakesleft نییە.

When the browser reads your HTML, it builds the DOM (Document Object Model): a tree with one node for every element and every piece of text. <html> is the root node; <head> and <body> are its children, and each element inside an element is a child of it. JavaScript never edits your HTML file: it reads and changes this tree, and the browser redraws the screen at once.

کاتێک تۆڕگەڕ HTMLـەکەت دەخوێنێتەوە، DOM ⁦(Document Object Model)⁩ دروست دەکات: دارێک (Tree) کە بۆ هەموو توخم و هەموو پارچە دەقێک نۆدێکی (Node) تێدایە. <html> نۆدی ڕەگە (Root node)؛ <head> و <body> منداڵەکانی ئەون و هەر توخمێک کە لەناو توخمێکی تردایە منداڵی ئەوە. JavaScript هەرگیز فایلی HTMLـەکەت دەستکاری ناکات: ئەم دارە دەخوێنێتەوە و دەیگۆڕێت و تۆڕگەڕ یەکسەر شاشەکە دووپاتە دەکێشێتەوە.

To change an element, first find it with document.querySelector(). It takes a CSS selector — the same #id, .class and tag selectors you use in CSS (Class selectors) — and gives back the first element that matches, or null when nothing matches. document.querySelectorAll() gives back all the matches.

بۆ گۆڕینی توخمێک، سەرەتا بە document.querySelector() بیدۆزەرەوە. هەڵبژێرێکی CSS وەردەگرێت — هەمان #id، .class و ناوی تاگ کە لە CSSـدا بەکاری دەهێنیت (هەڵبژێری کلاس) — و یەکەم توخم کە دەگونجێت دەگەڕێنێتەوە، یان null ئەگەر هیچ نەگونجێت. document.querySelectorAll() هەموو ئەوانەی دەگونجێن دەگەڕێنێتەوە.

Once you have an element, change it. textContent reads or replaces its text, always as plain text. classList.add(), .remove() and .toggle() add or remove a class, and your CSS decides what that class looks like. Prefer classes to the style property: the look stays in the CSS file, one class can change many properties, and themes and media queries keep working (MDN). hidden = true hides an element; hidden = false shows it again.

کاتێک توخمەکەت دۆزییەوە، بیگۆڕە. textContent دەقەکەی دەخوێنێتەوە یان دەیگۆڕێت، هەمیشە وەک دەقی ئاسایی. classList.add()، .remove() و .toggle() کلاسێک زیاد یان لادەبەن و CSSـەکەت بڕیار دەدات ئەو کلاسە چۆن دەردەکەوێت. کلاس لە تایبەتمەندیی style باشترە: ڕووخسار لە فایلی CSSـدا دەمێنێتەوە، یەک کلاس دەتوانێت چەندین تایبەتمەندی (Property (CSS)) بگۆڕێت و تێمەکان (Theme) و پرسەکانی میدیا (Media query) بەردەوام کار دەکەن ⁦(MDN)⁩. hidden = true توخمێک دەشارێتەوە؛ hidden = false دووپاتە پیشانی دەداتەوە.

On a web page an event is a click, a key press, typing in a field or the page finishing loading. addEventListener("click", function) asks the browser to run your function every time that event happens on that element; the function is called a listener (or handler). The order is always the same: click → event → your function → a change in the DOM → the browser redraws the page — with no new page from the server.

لە لاپەڕەتۆڕدا ڕووداو واتە کلیکێک، داگرتنی دوگمەیەکی کیبۆرد، نووسین لە خانەیەکدا یان تەواوبوونی بارکردنی لاپەڕەکە. addEventListener("click", function) داوا لە تۆڕگەڕ دەکات هەر جارێک ئەو ڕووداوە لەسەر ئەو توخمە ڕوو بدات کردارەکەت جێبەجێ بکات؛ ئەم کردارە پێی دەگوترێت گوێگر (Listener) (یان handler). ڕیزبەندییەکە هەمیشە وەک یەکە: کلیک ← ڕووداو ← کردارەکەت ← گۆڕانێک لە DOMـدا ← تۆڕگەڕ لاپەڕەکە دووپاتە دەکێشێتەوە — بێ لاپەڕەیەکی نوێ لە ڕاژەکارەوە.

In A dark theme the colours switch when the system setting changes. A button lets visitors choose for themselves: JavaScript only adds or removes one class, dark, on the <html> element (document.documentElement), and the custom properties do the rest. classList.toggle() adds the class when it is missing, removes it when it is there and gives back true when the class is now on. aria-pressed tells screen-reader users whether the toggle is on; the button's text stays “Dark mode” (WAI-ARIA).

لە دۆخی تاریکـدا ڕەنگەکان کاتێک ڕێکخستنی سیستەم دەگۆڕێت دەگۆڕێن. دوگمەیەک ڕێگە بە سەردانیکەران دەدات خۆیان هەڵبژێرن: JavaScript تەنیا یەک کلاس، dark، بۆ توخمی <html> (document.documentElement) زیاد یان لادەبات و تایبەتمەندییە دڵخوازەکان باقیی کارەکە دەکەن. classList.toggle() کلاسەکە زیاد دەکات ئەگەر نەبێت، لای دەبات ئەگەر هەبێت و true دەگەڕێنێتەوە ئەگەر کلاسەکە ئێستا هەبێت. aria-pressed بە بەکارهێنەرانی خوێنەرەوەی شاشە (Screen reader) دەڵێت سویچەکە هەڵکراوە یان نا؛ دەقی دوگمەکە هەر «Dark mode» دەمێنێتەوە ⁦(WAI-ARIA)⁩.

On phones a long menu often hides behind a Menu button (Menus on phones). Use a real <button> with aria-expanded: false while the menu is closed and true while it is open, so a screen reader says “Menu, button, collapsed” or “expanded”. aria-controls names the list it opens. Here the HTML shows the menu and hides the button; the script does the opposite when it starts — so if it never runs, every link is still there.

لەسەر مۆبایل مێنیوێکی (Menu) درێژ زۆرجار لە پشت دوگمەیەکی Menuـەوە دەشاردرێتەوە (مێنیو لەسەر مۆبایل). <button>ـێکی ڕاستەقینە لەگەڵ aria-expanded بەکاربهێنە: false تا مێنیوەکە داخراوە و true تا کراوەیە، بۆیە خوێنەرەوەی شاشە دەڵێت «⁦Menu, button, collapsed⁩» یان «expanded». aria-controls ناوی ئەو لیستە دەبات کە دەیکاتەوە. لێرەدا HTMLـەکە مێنیوەکە پیشان دەدات و دوگمەکە دەشارێتەوە؛ دەسنووسەکە کاتێک دەست پێدەکات پێچەوانەکەی دەکات — بۆیە ئەگەر هەرگیز کار نەکات، هەموو بەستەرەکان (Hyperlink) هەر لەوێن.

Let HTML check what it can first: here maxlength="120" stops typing after 120 characters, and required, type="email" or pattern can do more (Checking answers: when and how). JavaScript then helps: the input event fires on every change, so the page can say how many characters are left while people type. The aria-live="polite" paragraph is read out when the typing pauses. Browser checks never replace the server: anyone can switch them off, so PHP must check again (Client-side checks are not security).

سەرەتا با HTML ئەوە بپشکنێت کە دەتوانێت: لێرەدا maxlength="120" دوای ⁦120⁩ نووسە ڕێگە لە نووسین دەگرێت و required، type="email" یان pattern دەتوانن زیاتر بکەن (پشکنینی وەڵامەکان: کەی و چۆن). پاشان JavaScript یارمەتی دەدات: ڕووداوی input لە هەموو گۆڕانێکدا ڕوو دەدات، بۆیە لاپەڕەکە دەتوانێت لە کاتی نووسیندا بڵێت چەند نووسە ماوە. بڕگەی aria-live="polite" کاتێک نووسین دەوەستێت دەخوێنرێتەوە. پشکنینەکانی تۆڕگەڕ هەرگیز جێی ڕاژەکار ناگرنەوە: هەر کەسێک دەتوانێت بیانکوژێنێتەوە، بۆیە PHP دەبێت دووپاتە بپشکنێتەوە (پشتڕاستکردنەوەی لای ڕاژەخواز ئاسایش نییە).

Scripts fail more often than you think: a slow phone network, an old browser, a blocked file, one typing mistake that stops the whole script. So build in layers: first HTML that works for everyone — real links, real buttons, forms that send — then CSS for the look, then JavaScript that makes it nicer where it runs. The menu above follows this: without JavaScript every link is still on the page.

دەسنووسەکان زیاتر لەوەی بیری لێ دەکەیتەوە سەرناکەون: ئینتەرنێتی (Internet) هێواشی مۆبایل، تۆڕگەڕێکی کۆن، فایلێکی ڕێگەپێنەدراو، یەک هەڵەی نووسین کە هەموو دەسنووسەکە ڕادەگرێت. بۆیە بە چین دروستی بکە: سەرەتا HTML کە بۆ هەمووان کار دەکات — بەستەری ڕاستەقینە، دوگمەی ڕاستەقینە و فۆرمی ڕاستەقینە کە دەنێردرێن — پاشان CSS بۆ ڕووخسار، پاشان JavaScript کە لەو شوێنانەی کار دەکات باشتری دەکات. مێنیوەکەی سەرەوە ئەمە پەیڕەو دەکات: بێ JavaScript هەموو بەستەرەکان هەر لەسەر لاپەڕەکەن.

Two habits help most: use real <a> and <button> elements, never clickable <div>s, so the keyboard and screen readers work (Everything with the keyboard); and keep the focus outline visible on everything your script makes clickable.

دوو خوو زۆرترین یارمەتی دەدەن: توخمە ڕاستەقینەکانی <a> و <button> بەکاربهێنە، هەرگیز <div>ـی کلیکپێکراو، بۆ ئەوەی کیبۆرد و خوێنەرەوەکانی شاشە کار بکەن (هەموو شتێک بە کیبۆرد)؛ هەروەها نیشانەی فۆکەس (Focus indicator) لەسەر هەموو ئەو شتانەی دەسنووسەکەت کلیکپێکراویان دەکات دیار بهێڵەرەوە.

This lesson showed the most useful part: scripts, the console, a few values, the DOM, events and three patterns. To go further:

ئەم وانەیە بەسوودترین بەشی پیشان دا: دەسنووسەکان، کۆنسۆڵ، چەند نرخێک، DOM، ڕووداوەکان و سێ نموونە. بۆ ئەوەی زیاتر بڕۆیت: