فیلترها – Filters


حال که با دو مدل از زبان‌های تمپلیت در جنگو — تگ‌ها و متغیرها — و نحوه استفاده از آن‌ها آشنا شدیم، در این بخش به شرح یکی دیگر از قابلیت‌های مهم تمپلیت‌ها، یعنی فیلترها (Filters)، خواهیم پرداخت.

فیلترها در تمپلیت جنگو ابزاری هستند برای تغییر، پردازش یا قالب‌بندی مقدار متغیرها پیش از آن‌که در خروجی HTML نمایش داده شوند. به بیان ساده‌تر، اگر بخواهیم داده‌ای که از View ارسال شده به شکل متفاوت یا خواناتر در رابط کاربری نمایش داده شود، می‌توانیم از فیلترها استفاده کنیم. فیلترها با علامت | (خط عمودی یا pipe) بعد از متغیر نوشته می‌شوند.

فرض کنید در تابع view متغیر customtext با مقدار "django is awesome" را به تمپلیت ارسال کرده‌ایم. اگر بخواهیم این متن به صورت حروف بزرگ نمایش داده شود، می‌توانیم از فیلتر upper استفاده کنیم:

{{ customtext|upper }}

خروجی:

DJANGO IS AWESOME
 

گفتیم که فیلترها برای تغییر خروجی متغیرها یا اعمال تبدیلات به داده‌ها در تمپلیت استفاده می‌شوند. فیلترها با استفاده از علامت | به متغیرها اضافه می‌شوند. آنها امکان می‌دهند تا قبل از نمایش، داده را شکل­دهی کرد، مقادیر را تغییر داد و یا داده‌ها را فیلتر کرد. برای این منظور در قالب یک نمونه فرض می‌گیریم که حال قصد داریم با کلیک بر روی عنوان هر پروژه در مسیر آدرس projects/ که در بخش قبلی ارائه کردیم، بتوانیم اطلاعات اختصاصی آن پروژه را در مسیر آدرس read-project/ نمایش دهیم:

فیلترهای مربوط به متن (String Filters)


String Filters در جنگو برای دست‌کاری، فرمت‌دهی و تغییر محتوای متنی به کار می‌روند. این فیلترها به ما اجازه می‌دهند داده‌های متنی که به تمپلیت ارسال شده‌اند را بدون تغییر در سطح پایگاه داده یا لاجیک برنامه، به شکل دلخواه در خروجی نمایش دهیم. برای نمونه می‌توانیم تمام حروف را کوچک یا بزرگ کنیم (lower, upper)، اولین حرف جمله یا هر کلمه را بزرگ کنیم (capfirst, title)، بخش‌هایی از متن را حذف کنیم (cut)، یا متن طولانی را کوتاه نماییم (truncatewords, truncatechars) و با length یا length_is می‌توانیم طول متن‌ها یا رشته‌ها را بسنجیم. همچنین فیلترهایی مانند linebreaks و linenumbers به ما کمک می‌کنند متن‌های چندخطی را به صورت قالب‌بندی‌شده نمایش دهیم. به طور خلاصه، این دسته از فیلترها ابزار قدرتمندی برای نمایش حرفه‌ای و کاربرپسند داده‌های متنی در تمپلیت هستند.

{{ "hello world!"|upper }}            ┈┈┈⮞ "HELLO WORLD!"            <!-- Returns the text in upper case letters. -->
{{ "HELLO WORLD!"|lower }}            ┈┈┈⮞ "hello world!"            <!-- Returns the text in lower case letters. -->
{{ "hello world!"|title }}            ┈┈┈⮞ "Hello World!"            <!-- Upper cases the first character of each word in a text, all other characters are converted to lower case. -->
{{ "hello world!"|capfirst }}         ┈┈┈⮞ "Hello world!"            <!-- Returns the first letter in uppercase. -->
{{ "Hello World!"|slugify }}          ┈┈┈⮞ "hello-world"             <!-- Converts text into one long alphanumeric-lower-case word. -->
{{ "Hello World!"|make_list }}        ┈┈┈⮞ ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd', '!'] <!-- Converts a value into a list object. -->
{{ "Hello World!"|cut:"l" }}          ┈┈┈⮞ "Heo Word!"               <!-- Removes any specified character or phrases -->
{{ "Hello World!"|slice:":4" }}       ┈┈┈⮞ "Hell"                    <!-- Returns a specified slice of a text or object. -->
{{ "Hello World!"|truncatechars:4 }}  ┈┈┈⮞ "Hel..."                  <!-- Shortens a string into the specified number of characters. -->
{{ "Hello World!"|truncatewords:1 }}  ┈┈┈⮞ "Hello..."                <!-- Shortens a string into the specified number of words. -->
{{ "Hello World!"|wordcount }}        ┈┈┈⮞ 2                         <!-- Returns the number of words in a text. -->
{{ "Hello World!"|length }}           ┈┈┈⮞ 12                        <!-- Returns the number of items in an object, or the number of characters in a string. -->
{{ "Hello World!"|length_is:12 }}     ┈┈┈⮞ True                      <!-- Returns True if the length is the same as the specified number -->
{{ "Hello World!"|center:20 }}        ┈┈┈⮞ "    Hello World!    "    <!-- Centers the value in the middle of a specified width. -->
{{ "Hello World!"|ljust:20 }}         ┈┈┈⮞ "Hello World!        "    <!-- Left aligns the value according to a specified width -->
{{ "Hello World!"|rjust:20  }}        ┈┈┈⮞ "        Hello World!"    <!-- Right aligns the value according to a specified width -->
{{ "Hello \n World!"|linebreaks }}    ┈┈┈⮞ <p>Hello <br/> World!</p> <!-- Returns the text with <br> instead of line breaks, and <p> instead of more than one line break. -->
{{ "Hello \n World!"|linebreaksbr }}  ┈┈┈⮞ Hello <br/> World!        <!-- Returns the text with <br> instead of line breaks. -->
{{ "<b>Hello World!</b>"|striptags }} ┈┈┈⮞ Hello World!              <!-- Removes HTML tags from a text. -->
{{ "I'm Araz"|addslashes }}           ┈┈┈⮞ "I\'m Araz"               <!-- Adds a slash before any quote characters -->

فیلترهای مربوط به اعداد (Number Filters)


Number Filters در جنگو برای پردازش و فرمت‌دهی داده‌های عددی به کار می‌روند. این فیلترها به ما امکان می‌دهند تا اعداد را به شکلی خواناتر و مناسب‌تر برای نمایش در خروجی قالب تبدیل کنیم. برای مثال می‌توانیم یک عدد را با مقدار دیگری جمع کنیم (add)، تعداد اعشار را کنترل نماییم (floatformat)، یا بررسی کنیم که آیا عدد بر عدد دیگری بخش‌پذیر است (divisibleby). همچنین فیلترهایی مثل filesizeformat به ما کمک می‌کنند اندازه فایل‌ها را به واحدهای قابل فهم برای کاربر (KB, MB, GB) نشان دهیم. این فیلترها باعث می‌شوند داده‌های عددی به صورت کاربرپسند، دقیق و متناسب با نیاز پروژه در تمپلیت‌ها نمایش داده شوند.

{{ 5|add:10 }}                  ┈┈┈⮞ 15        <!-- Adds a specified value. -->
{{ 15|add:-10 }}                ┈┈┈⮞ 5         <!-- Subtraction a specified value. -->
{{ 10|divisibleby:5 }}          ┈┈┈⮞ True      <!-- Returns True if the value can be divided by the specified number, otherwise it returns False. -->
{{ 123456789|filesizeformat }}  ┈┈┈⮞ 117.7 MB  <!-- Returns a number into a file size format. -->
{{ 3.14159|floatformat:2 }}     ┈┈┈⮞ 3.14      <!-- Rounds floating numbers to a specified number of decimals, default one decimal. -->

فیلترهای مربوط به تاریخ (Date/Time Filters)


Date/Time Filters در جنگو برای فرمت‌دهی و پردازش داده‌های زمانی به کار می‌روند و نقش مهمی در نمایش درست و کاربرپسند تاریخ‌ها و زمان‌ها دارند. با استفاده از این فیلترها می‌توانیم تاریخ‌ها (date) و یا زمان (time) را در قالب دلخواه نمایش و با فرمت مشخص نشان دهیم، یا فاصله زمانی بین دو تاریخ را به شکل قابل فهم محاسبه کنیم (timesince, timeuntil). این فیلترها مخصوصاً زمانی مفید هستند که بخواهیم داده‌های خام دیتابیس (که معمولاً به فرمت استاندارد ذخیره می‌شوند) را به فرمتی قابل درک برای کاربر تبدیل کنیم، مثل نمایش تاریخ پست‌ها، مدت‌زمان باقی‌مانده تا یک رویداد یا فاصله زمانی از آخرین به‌روزرسانی. به این ترتیب، فیلترهای تاریخ و زمان ابزاری ضروری برای هر پروژه‌ای هستند که داده‌های زمانی در آن نقش دارند.

{{ mybirthdate|date:"Y-m-d" }}          ┈┈┈⮞ 1984-04-04           <!-- Returns dates in the specified format. -->
{{ mybirthdate|time:"H:i" }}            ┈┈┈⮞ 14:35                <!-- Returns a time in the specified format. -->
{{ mybirthdate|timesince }}             ┈┈┈⮞ 20 years, 10 months  <!-- Returns the difference between two datetimes. -->
{{ mybirthdate|timesince:nowrouz }}     ┈┈┈⮞ 11 months, 13 days
{{ marslanding|timeuntil }}             ┈┈┈⮞ 24 years, 7 months   <!-- Returns the difference between two datetimes. -->
{{ marslanding|timeuntil:moonlanding }} ┈┈┈⮞ 80 years, 10 months

⌘ فیلترهای مربوط به لیست‌ها و داده‌ها (List & Data Filters)


List & Data Filters در جنگو برای کار با مجموعه‌ها (لیست، کوئری‌ست، دیکشنری و …) استفاده می‌شوند و امکان دسترسی، مرتب‌سازی یا تغییر نحوه نمایش داده‌ها را فراهم می‌کنند. برای مثال می‌توانیم اولین یا آخرین عنصر یک لیست را نمایش دهیم (first, last)، یا اعضای لیست را با یک جداکننده خاص به هم متصل کنیم (join). اگر داده‌ها به صورت دیکشنری باشند، می‌توانیم آن‌ها را بر اساس یک کلید مرتب کنیم (dictsort, dictsortreversed). همچنین می‌توانیم یک بخش خاص از لیست را انتخاب کنیم (slice)، یک عضو تصادفی از لیست نمایش دهیم (random)، یا طول داده‌ها را بررسی کنیم (length). این دسته از فیلترها زمانی بسیار کاربردی هستند که داده‌های پیچیده از سمت ویو به تمپلیت ارسال می‌شوند و نیاز داریم آن‌ها را به شکل ساده‌تر، مرتب‌تر و قابل‌فهم‌تر در خروجی نشان دهیم.

{{ mylist|first }}                    <!-- Returns the first item of an object (for Strings, the first character is returned). -->
{{ mylist|last }}                     <!-- Returns the last item of an object (for Strings, the last character is returned). -->
{{ mylist|join:", " }}                <!-- Returns the items of a list into a string. -->
{{ mylist|random }}                   <!-- Returns a random item of an object -->
{{ mylist|slice:":2" }}               <!-- Returns a specified slice of a text or object. -->
{{ mylist|dictsort:"name" }}          <!-- Sorts a dictionary by the given value. -->
{{ mylist|dictsortreversed:"name" }}  <!-- Sorts a dictionary reversed, by the given value. -->

فیلترهای منطقی و کمکی (Logic & Utility Filters)


Logic & Utility Filters در جنگو برای مدیریت شرایط خاص و ساده‌سازی نمایش داده‌ها استفاده می‌شوند. این فیلترها بیشتر زمانی به کار می‌آیند که داده‌ها ممکن است خالی، None یا غیرمنتظره باشند و ما بخواهیم در تمپلیت بدون نیاز به تغییر در تابع view آن‌ها را مدیریت کنیم. برای نمونه می‌توانیم اگر یک متغیر خالی بود مقدار پیش‌فرض نشان دهیم (default)، یا فقط در صورت None بودن مقدار جایگزین بگذاریم (default_if_none). با استفاده از yesno می‌توانیم مقادیر بولی را به متن قابل فهم برای کاربر تبدیل کنیم (مثلاً True → Yes و False → No). همچنین pluralize برای جمع بستن واژه‌ها کاربرد دارد (مانند اضافه کردن s در انگلیسی) و باعث می‌شود متن‌ها از نظر دستوری صحیح‌تر باشند. این فیلترها درواقع ابزارهای کمکی هستند که منطق ساده و پرکاربرد را مستقیماً در لایه‌ی نمایش (تمپلیت) پیاده‌سازی می‌کنند.

{{ myvar|default:"No Value" }}       <!-- Returns a specified value if the value is False. -->
{{ myvar|default_if_none:"Empty" }}  <!-- Returns a specified value if the value is None. -->
{{ mycondition|yesno:"Yes,No" }}     <!-- Converts Booleans values into specified values. -->

فیلترهای مخصوص URL و JSON


URL & JSON Filters در جنگو برای پردازش داده‌هایی به کار می‌روند که نیاز به استفاده در لینک‌ها، اسکریپت‌ها یا تبادل داده با مرورگر دارند. این فیلترها به ما کمک می‌کنند متن‌ها یا مقادیر را به شکلی امن و استاندارد در آدرس‌ها یا کدهای جاواسکریپت قرار دهیم. برای مثال، با urlencode می‌توانیم متن را به فرمت امن URL تبدیل کنیم (مثل تبدیل فاصله به + یا %20)، و با urlize یا urlizetrunc لینک‌های موجود در متن را به تگ‌های <a> تبدیل کرده و آن‌ها را قابل کلیک کنیم. همچنین iriencode برای کدگذاری در URIهای بین‌المللی استفاده می‌شود. در بخش JSON هم فیلتر json_script داده‌ها را به صورت امن داخل یک تگ <script> قرار می‌دهد تا بدون مشکل امنیتی (مثل XSS) در جاواسکریپت استفاده شوند. این فیلترها مخصوصاً در پروژه‌هایی که تعامل زیادی با مرورگر، APIها یا داده‌های داینامیک دارند بسیار حیاتی هستند.

{{ "a b c"|urlencode }}                        ┈┈┈⮞ a%20b%20c                                         <!-- encodes for query strings (form data) -->
{{ "visit https://arazsx.ir"|urlize }}         ┈┈┈⮞ <a href="https://arazsx.ir">https://arazsx.ir</a> <!-- Returns any URLs in a string as HTML link -->
{{ "visit https://arazsx.ir"|urlizetrunc:15 }} ┈┈┈⮞ <a href="https://arazsx.ir">https://arazsx…</a>   <!-- Returns any URLs in a string as HTML links, but shortens the links into the specified number of characters. -->
{{ mydata|json_script:"my-data" }}             ┈┈┈⮞ <script id="my-data" type="application/json">[{"brand": "Ford", "model": "Mustang", "year": 1964}]</script> <!-- Returns an object into a JSON object surrounded by <script></script> tags. -->