{"title":"Penyesuaian etiket cetakan dan saringan","version":"3.2","locale":"id","docname":"howto/custom-template-tags","url":"/id/3.2/howto/custom-template-tags/","canonical":"https://djangodocs.dev/id/3.2/howto/custom-template-tags/","summary":"Cetakan bahasa Django datang dengan beragam luas dari built-in tags and filters dirancang untuk megnalamatkan kebutuhan pembawaan logis dari aplikasi anda. Namun,…","html":"

Penyesuaian etiket cetakan dan saringanLink to this heading#

\n

Cetakan bahasa Django datang dengan beragam luas dari built-in tags and filters dirancang untuk megnalamatkan kebutuhan pembawaan logis dari aplikasi anda. Namun, anda mungkin menemukan diri anda sendiri membutuhkan fungsi yang tidak dicakupi oleh inti kumpulan dari cetakan primitif. Anda dapat memperpanjang cetakan mesin dengan menentukan penyesuaian etiket dan penyaring menggunakan Python, dan membuat mereka tersedua pada cetakan anda menggunakan etiket {% load %}.

\n
\n

Tata letak kodeLink to this heading#

\n

Tempat paling umum untuk menentukan cetakan etiket dan penyaring adalah didalam aplikasi Django. Jika mereka terhubung pada aplikasi yang ada, dia masuk akal untuk menggabungkan mereka; kalau tidak, mereka dapat ditambahkan ke aplikasi baru. Ketika aplikasi Django ditambahkan ke INSTALLED_APPS, etiket apapun dia tentukan dalam tempat biasa dibawah otomatis dibuat tersedia untuk dimuat dengan cetakan.

\n

Aplikasi harus mengandung sebuah direktori templatetags, pada tingkatan sama seperti models.py, views.py, dll. Jika ini tidak ada, buat dia - jangan lupakan berkas __init__.py untuk memastikan direktori diperlakukan sebagai paket Python.

\n\n

Penyesuaian etiket dan penyaring anda akan berada dalam sebuah modul didalam direktori templatetags. Nama dari berkas modul adalah nama anda akan gunakan untuk memuat etiket kemudian, jadi berhati-hatilah untuk mengambil sebuah nama yang tidak akan bentrok dengan penyesuaian etiket dan penyaring di aplikasi lain.

\n

Sebagai contoh, jika penyesuaian etiket/penyaring anda berada dalam sebuah berkas yang dipanggil poll_extras.py, tata letak eplikasi anda mungkin terlihat seperti ini:

\n
Code
polls/\n    __init__.py\n    models.py\n    templatetags/\n        __init__.py\n        poll_extras.py\n    views.py\n
\n

Dan di cetakan anda, anda akan menggunakan berikut:

\n
Django template
{% load poll_extras %}\n
\n

Aplikasi yang mengandung penyesuaian etiket harus berada dalam INSTALLED_APPS agar etiket {% load %} bekerja. Ini adalah fitur keamanan: Dia mengizinkan anda untuk menempatkan kode Python untuk banyak cetakan pustaka pada sebuah mesin rumah tunggal tanpa mengadakan akses ke semua dari mereka untuk setiap pemasangan Django.

\n

Tidak ada batasan pada bagaimana banyak modul anda taruh dalam paket templatetags. Hanya perlu diingat bahwa sebuah pernyataan {% load %} akan memuatetiket/penyaring untuk nama modul Python yang diberikan, bukan nama dari aplikasi.

\n

Untuk menjadi pustaka sah, modul harus mengandung sebuah variabel tingkat-modul yang dinamai register yaitu sebuah instance template.Library, dimana semua etiket dan penyaring didaftarkan. Jadi dekat diatas modul anda, taruh berikut:

\n
Code
from django import template\n\nregister = template.Library()\n
\n

Kalau tidak, cetakan modul etiket dapat didaftarkan melalui argumen 'libraries' ke DjangoTemplates. Ini berguna jika anda ingin menggunakan label berbeda dari nama cetakan modul etiket ketika memuat cetakan etiket. Dia juga mengadakan anda untuk mendaftar etiket tanpa memasang sebuah aplikasi.

\n\n
\n
\n

Menulis saringan cetakan penyesuaianLink to this heading#

\n

Penyaring penyesuaian adalah fungsi Python yang mengambil satu atau dua argumen:

\n\n

Sebagai contoh, dalam saringan {{ var|foo:"bar" }}, the filter foo akan dilewatkan variabel var dan argumen ''bar''.

\n

Sejak cetakan bahasa tidak menyediakan penanganan pengecualian, setiap pengecualian yang muncul dari sebuah cetakan saringan akan tidak terlindungi sebagai sebuah kesalahan peladen. Dengan demikian, fungsi penyaring harus menghindari memunculkan pengecualian jika ada alasan nilai mundur untuk kembali. Dalam kasus dari masukan yang mewakili kesalahan jelas dalam sebuah cetakan, menampilkan pencegualian mungkin masih lebih baik daripada kegagalan diam yang menyembunyikan kesalahan.

\n

Ini adalah sebuah contoh pengertian saringan

\n
Code
def cut(value, arg):\n    """Removes all values of arg from the given string"""\n    return value.replace(arg, '')\n
\n

Dan ini adalah sebuah contoh bagaimana saringan itu akan digunakan:

\n
Django template
{{ somevariable|cut:"0" }}\n
\n

Kebanyakan penyaring tidak mengambil argumen. Dalam kasus ini, tinggalkan argumen dari fungsi anda:

\n
Code
def lower(value): # Only one argument.\n    """Converts a string into all lowercase"""\n    return value.lower()\n
\n
\n

Mendaftarkan saringan penyesuaianLink to this heading#

\n
\n
\ndjango.template.Library.filter()Link to this definition#
\n
\n\n

Sekali anda telah menulis arti saringan anda, anda butuh mendaftarkannya dengan instance Library anda, untuk membuatnya tersedia pada bahasa cetakan Django:

\n
Code
register.filter('cut', cut)\nregister.filter('lower', lower)\n
\n

Cara Library.filter() mengambil dua argumen:

\n
    \n

  1. Nama dari saringan -- sebuah deretan karakter.

    2. \n

  2. Fungsi himpunan -- Sebuah fungsi Python (bukan nama fungsi sebagai deretan karakter).

    3. \n
\n

Anda dapat menggunakan register.filter() sebagai penghias:

\n
Code
@register.filter(name='cut')\ndef cut(value, arg):\n    return value.replace(arg, '')\n\n@register.filter\ndef lower(value):\n    return value.lower()\n
\n

Jika anda tidak mengubah argumen name, seperti di contoh kedua di atas, Django akan menggunakan nama fungsi sebagai nama filter.

\n

Akhirnya, register.filter() juga menerima tiga argumen katakunci, is_safe, needs_autoescape, dan expects_localtime. Argumen ini digambarkan dalam penyaring dan pelolosan otomatis dan penyaring dan zona waktu dibawah.

\n
\n
\n

Cetakan penyaring yang mengharapkan deretan karakterLink to this heading#

\n
\n
\ndjango.template.defaultfilters.stringfilter()Link to this definition#
\n
\n\n

Jika anda sedang menulis sebuah cetakan penyaring yang hanya menerima sebuah deretan karakter sebagai argumen pertama, anda harus menggunakan decorator stringfilter. Ini akan merubah sebuah obyek ke nilai deretan karakternya sebelum dilewatkan ke fungsi anda:

\n
Code
from django import template\nfrom django.template.defaultfilters import stringfilter\n\nregister = template.Library()\n\n@register.filter\n@stringfilter\ndef lower(value):\n    return value.lower()\n
\n

Jalan ini, anda akan dapat melewatkan, katakan, sebuah integer ke penyaring ini, dan dia tidak menyebabkan sebuah AttributeError (karena integer tidak mempunyai cara lower()).

\n
\n
\n

Penyaring dan pelolosan otomatisLink to this heading#

\n

Ketika menulis penyesuaian penyaring, berikan beberapa pemikiran bagaimana penyaring akan berinteraksi dengan perilaku pelolosan-otomatis Django. Catat bahwa dua jenis dari string dapat dilewatkan didalam sekitar kode cetakan:

\n\n

Kode cetakan penyaring gagal kedalam satu dari dua keadaan:

\n
    \n

  1. Penyaring anda tidak memperkenalkan salah satu karakter tidak aman (<, >, ', " atau &) kedalam hasil yang tidak hadir. Dalam kasus ini, anda dapat membiarkan Django mengambil semua penanganan pelolosan otomatis untuk anda. Semua anda butuh untuk dilakukan adalah menyetel bendera is_safe ke True ketika anda mendaftar fungsi penyaringan, seperti begitu:

    \n
    Code
    @register.filter(is_safe=True)\ndef myfilter(value):\n    return value\n
    \n

    Bendera ini memberitahu Django bahwa jika sebuah deretan karakter "safe" dilewatkan kedalam penyaring anda, hasil akan masih menjadi "safe" dan jika sebuah deretan karakter tidak aman dilewatkan, Django akan otomatis meloloskannya, jika diperlukan.

    \n

    Anda dapat berpikir dari ini sebagai berarti "penyaring ini aman -- dia tidak memperkenalkan kemungkinan apapun dari HTML tidak aman."

    \n

    Alasan is_safe perlu adalah karena ada banyak tindakan-tindakan string biasa yang akan merubah sebuah obyek SafeData kembali ke obyek str biasa dan, daripada mencoba menangkap mereka semua, yang akan sangat sulit, Django memperbaiki kerusakan setelah penyaring lengkap.

    \n

    Sebagi contoh, andaikan anda mempunyai sebuah penyaring yang menambahkan deretan karakter xx ke akhir dari masukan. Sejak ini diperkenalkan karakter HTML tidak berbahaya ke hasil (selain dari apapun itu sudah hadir), anda harus menandai penyaring anda dengan is_safe:

    \n
    Code
    @register.filter(is_safe=True)\ndef add_xx(value):\n    return '%sxx' % value\n
    \n

    Ketika penyaring ini digunakan dalam sebuah cetakan dimana pelolosan otomatis diadakan, Django akan meloloskan keluaran ketika masukan belum ditandai sebagai "safe".

    \n

    Secara awalan, is_safe adalah False, dan anda dapat menghilangkannya dari saringan dimana dia tidak wajib.

    \n

    Hati-hati ketika memutuskan jika penyaring anda sangat membiarkan deretan karakter aman sebagai safe. Jika anda sedang memidnahkan karakter, anda mungkin secara tidak sengaja membiarkan etiket HTML tidak seimbang atau kesatuan dalam hasil. Sebagai contoh, memindahkan sebuah > dari masukan mungkin mengubah <a> menjadi <a, yang akan butuh diloloskan pada keluaran untuk menghindari masalah. Demikian pula, memindahkan titik koma (;) dapat merubah &amp; into &amp, yang tidak lagi kesatuan sah dan demikian butuh pelolosan. Kebanyakan kasus tidak dekat dengan trik ini, tetapi jaga mata anda untuk masalah apapun seperti itu ketika meninjau kode anda.

    \n

    Menandai sebuah penyaring is_safe akan memaksa nilai kembalian penyaring menjadi deretan karakter. Jika penyaring anda harus mengembalikan sebuah boolean atau nilai bukan deretan karakter, tandai dia is_safe akan mungkin mempunyai konsekuensi yang tidak diinginkan (seperti merubah boolean False menjadi deretan karakter 'False').

    \n
    2. \n

  2. Kalau tidak, kode penyaring anda dapat secara manual merawat pelolosan apapun yang dibutuhkan. Ini adalah penting ketika anda sedang memperkenalkan markah HTML baru kedalam hasil. Anda ingin menandai keluaran sebagai aman dari pelolosan lebih lanjut sehingga markah HTML anda tidak diloloskan lebih lanjut, jadi anda akan butuh menangani masukan diri anda sendiri.

    \n

    Untuk menandai keluaran sebagai deretan karakter aman, gunakan django.utils.safestring.mark_safe().

    \n

    Berhati-hatilah, meskipun. Anda butuh melakukan lagi daripada hanya menandai keluaran sebagai aman. Anda butuh memastikan dia sangat adalah aman, dan apa yang anda lakukan tergantung pada apakah pelolosan otomatis berpengaruh. Idenya adalah menulis penyaring yang dapat berjalan dalam cetakan dimana pelolosan otomatis salah satunya nyala atau mati agar membuat hal-hal semakin mudah untuk cetakan penulis anda.

    \n

    Agar penyaring anda mengetahui keadaan pelolosan otomatis saat ini, setel bendera needs_autoescape ke True ketika anda mendaftar fungsi penyaring anda. (Jika anda tidak menentukan bendera ini, dia awalnya adalah False). Bendera ini mengatakan Django bahwa fungsi penyaring anda ingin dilewatkan sebuah argumen katakunci tambahan, dipanggil autoescape, yaitu True jika pelolosan otomatis dalam efek dan False sebaliknya. Sangat dianjurkan untuk menyetel parameter autoescape ke True, sehingga jika anda memanggil fungsi dari kode Python dia akan mempunyai pelolosan diadakan secara awal.

    \n

    Sebagai contoh, mari kita menulis penyaring yang menekankan karakter pertama dari sebuah deretan karakter:

    \n
    Code
    from django import template\nfrom django.utils.html import conditional_escape\nfrom django.utils.safestring import mark_safe\n\nregister = template.Library()\n\n@register.filter(needs_autoescape=True)\ndef initial_letter_filter(text, autoescape=True):\n    first, other = text[0], text[1:]\n    if autoescape:\n        esc = conditional_escape\n    else:\n        esc = lambda x: x\n    result = '<strong>%s</strong>%s' % (esc(first), esc(other))\n    return mark_safe(result)\n
    \n

    The needs_autoescape flag and the autoescape keyword argument mean\nthat our function will know whether automatic escaping is in effect when the\nfilter is called. We use autoescape to decide whether the input data\nneeds to be passed through django.utils.html.conditional_escape or not.\n(In the latter case, we use the identity function as the "escape" function.)\nThe conditional_escape() function is like escape() except it only\nescapes input that is not a SafeData instance. If a SafeData\ninstance is passed to conditional_escape(), the data is returned\nunchanged.

    \n

    Akhirnya, dalam contoh diatas, kami ingat untuk menandai hasil sebagai aman sehingga HTML kami dimasukkan langsung kedalam cetakan tanpa pelolosan lanjut.

    \n

    Tidak perlu khawatir tentang bendera is_safe dalam kasus ini (meskipun termasuknya tidak akaan melukai apapun). Kapanpun anda secara manual menangani masalah pelolosan otomatis dan mengembalikan sebuah deretan karakter aman, bendera is_safe tidak merubah apapun.

    \n
    3. \n
\n\n
\n
\n

Saringan dan zona waktuLink to this heading#

\n

Jika anda menulis sebuah penyesuaian penyaring yang dijalankan pada obyek datetime, anda akan biasanya mendaftarkannya dengan bendera expects_localtime disetel ke True:

\n
Code
@register.filter(expects_localtime=True)\ndef businesshours(value):\n    try:\n        return 9 <= value.hour < 17\n    except AttributeError:\n        return ''\n
\n

Ketika bendera ini disetel, jika argumen pertama pada penyaring anda adalah zona waktu perhatikan datetime, Django akan merubahnya ke zona waktu saat ini sebelum melewatkannya ke penyaring anda ketika sesuai, menurut pada aturan untuk perubahan zona waktu dalam cetakan.

\n
\n
\n
\n

Menulis etiket cetakan penyesuaianLink to this heading#

\n

Etiket lebih rumit daripada penyaring, karena etiket dapat melakukan apapun. Django menyediakan sejumlah jalan pintas yang membuat penulisan kebanyakan jenis etiket lebih mudah. Pertama kami akan menjelajahi jalan pintas tersebut, kemudian menjelaskan bagaimana menulis sebuah etiket dari goresan untuk kasus-kasus tersebut ketika jalan pintas tidak cukup kuat.

\n
\n

Etiket sederhanaLink to this heading#

\n
\n
\ndjango.template.Library.simple_tag()Link to this definition#
\n
\n\n

Banyak cetakan etiket mengambil sejumlah argumen -- deretan karakter atau cetakan variabel -- dan mengembalikan sebuah hasil setelah melakukan beberapa pengolahan berdasarkan hanya pada masukan argumen dan beberapa informasi luar. Sebagai contoh, sebuah etiket current_time mungkin menerima sebuah bentuk deretan karakter dan mengembalikan waktu sebagai bentuk deretan karakter.

\n

Untuk meringankan pembuatan dari jenis ini dari etiket, Django menyediakan fungsi pembantu, simple_tag. Fungsi ini, yaitu sebuah cara dari django.template.Library, mengambil sebuah fungsi yang menerima angka apapun dari argumen, membungkusnya dalam fungsi render dan bit-bit yang dibutuhkan lainnya disebutkan diatas dan mendaftarkannya dengan cetakan sistem.

\n

Fungsi current_time kami dapat jadi ditulis seperti ini:

\n
Code
import datetime\nfrom django import template\n\nregister = template.Library()\n\n@register.simple_tag\ndef current_time(format_string):\n    return datetime.datetime.now().strftime(format_string)\n
\n

Beberapa hal untuk dicatat tentang fungsi pembantu simple_tag:

\n\n

Tidak seperti peralatan etiket lain, simple_tag melewatkan keluarannya melalui conditional_escape() jika konteks cetakan dalam suasana pelolosan otomatis, untuk memastikan HTML benar dan melindungi anda dari kerentanan XSS.

\n

Jika tambahan pelolosan tidak diharapkan, anda akan butuh menggunakan mark_safe() jika anda sepenuhnya yakin bahwa kode anda tidak mengandung kerentanan XSS. Untuk membangun potongan kecil HTML, gunakan format_html() daripada mark_safe() sangat kuat dianjurkan.

\n

Jika etiket cetakan anda butuh untuk mengakses konteks saat ini, anda dapat menggunakan argumen takes_context ketika mendaftarkan etiket anda:

\n
Code
@register.simple_tag(takes_context=True)\ndef current_time(context, format_string):\n    timezone = context['timezone']\n    return your_get_current_time_method(timezone, format_string)\n
\n

Catat bahwa argumen pertama harus dipanggil context.

\n

Untuk informasi lebih pada bagaimana pilihan takes_context bekerja, lihat bagian pada inclusion tags.

\n

Jika anda butuh menamai kembali etiket anda, anda dapat menyediakan nama penyesuaian untuknya:

\n
Code
register.simple_tag(lambda x: x - 1, name='minusone')\n\n@register.simple_tag(name='minustwo')\ndef some_function(value):\n    return value - 2\n
\n

Fungsi simple_tag mungkin menerima angka apapun dari argumen terkait atau kata kunci. Sebagai contoh:

\n
Code
@register.simple_tag\ndef my_tag(a, b, *args, **kwargs):\n    warning = kwargs['warning']\n    profile = kwargs['profile']\n    ...\n    return ...\n
\n

Kemudian dalam cetakan angka apapun dari argumen, dipisahkan oleh spasi, mungkin dilewatkan ke cetakan etiket. Seperti dalam Python, nilai untuk argumen katakunci disetel menggunakan tanda sama dengan ("=") dan harus disediakan setelah penempatan argumen. Sebagai contoh:

\n
Django template
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\n
\n

Itu dimungkinkan untuk menyimpan hasil etiket dalam sebuah cetakan variabel daripada secara langsung mengeluarkannya. Ini dilakukan dengan menggunakan argumen as diikuti oleh nama variabel. Melakukannya mengadakan anda untuk mengeluarkan isi diri anda dimana anda melihatnya cocok:

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" as the_time %}\n<p>The time is {{ the_time }}.</p>\n
\n
\n
\n

Penyertaaan etiketLink to this heading#

\n
\n
\ndjango.template.Library.inclusion_tag()Link to this definition#
\n
\n\n

Jenis umum lainnya dari cetakan etiket adalah jenis yang menampilkan beberapa data dengan membangun cetakan lain. Sebagai contoh, antarmuka admin Django menggunakan penyesuaian etiket cetakan untuk menampilkan tombol dibawah dari halaman formulir "add/change". Tombol-tombol tersebut selalu terlihat sama, tetapi ssaran tautan berubah tergantung pada obyek yang sedang disunting -- sehingga mereka kasus sempurna untuk menggunakan cetakan kecil yang diisi dengan rincian dari obyek saat ini. (Dalam kasus admin, ini adalah etiket submit_row.)

\n

Urutan etiket ini dipanggil "penyertaan etiket".

\n

Menulis pencatuman etiket adalah mungkin pertunjukan terbaik dengan contoh. Mari kita menulis sebuah etiket yang mengeluarkan daftar pilihan untuk obyek Poll yang diberikan, seperti dibuat dalam tutorial. Kami akan menggunakan etiket seperti ini:

\n
Django template
{% show_results poll %}\n
\n

...dan keluaran akan kelihatan seperti ini:

\n
Html
<ul>\n  <li>First choice</li>\n  <li>Second choice</li>\n  <li>Third choice</li>\n</ul>\n
\n

Pertama, tentukan fungsi yang mengambil argumen dan menghasulkan kamus dari data untuk hasil. Titik terpenting disini adalah kami hanya butuh mengembalikan sebuah kamus, bukan apapun lebih rumit. Ini akan digunakan sebagai konteks cetakan untuk fragmen cetakan. Contoh:

\n
Code
def show_results(poll):\n    choices = poll.choice_set.all()\n    return {'choices': choices}\n
\n

Next, create the template used to render the tag's output. This template is a\nfixed feature of the tag: the tag writer specifies it, not the template\ndesigner. Following our example, the template is very short:

\n
Django template
<ul>\n{% for choice in choices %}\n    <li> {{ choice }} </li>\n{% endfor %}\n</ul>\n
\n

Sekarang, buat dan daftar penyertaan etiket dengan memanggil cara inclusion_tag() pada sebuah obyek Library. Mengikuti contoh kami, jika cetakan diatas dalam sebuah berkas dipanggil results.html dalam sebuah direktori yang dicari oleh pemuat cetakan, kami akan mendaftar etiket seperti ini:

\n
Code
# Here, register is a django.template.Library instance, as before\n@register.inclusion_tag('results.html')\ndef show_results(poll):\n    ...\n
\n

Kemungkinan lain dia memungkinkan mendaftarkan pemasukan etiket menggunakan instace django.template.Template:

\n
Code
from django.template.loader import get_template\nt = get_template('results.html')\nregister.inclusion_tag(t)(show_results)\n
\n

...ketika pertama membuat fungsi.

\n

Terkadang, penyertaan etiket anda mungkin membutuhkan sejumlah besar argumen, membuatnya sakit untuk cetakan penulis melewatkan semua argumen dan mengingat urutan mereka. Untuk mengatasi ini, Django menyediakan sebuah pilihan takes_context untuk penyertaan etiket. Jika anda menentukan takes_context dalam sebuah cetakan etiket, etiket tidak akan mempunyai argumen wajib, dan pokok fungsi Python akan mempunyai satu argumen -- konteks cetakan mulai ketika etiket dipanggil.

\n

Sebagai contoh, katakan anda sedang menulis sebuah penyertaan etiket yang akan selalu digunakan dalam sebuah konteks yang mengandung variabel home_link dan home_title yang menunjuk kembali ke halaman utama. Disini fungsi Python akan kelihatan seperti:

\n
Code
@register.inclusion_tag('link.html', takes_context=True)\ndef jump_link(context):\n    return {\n        'link': context['home_link'],\n        'title': context['home_title'],\n    }\n
\n

Catat bahwa parameter pertama pada fungsi harus dipanggil context.

\n

Dalam baris register.inclusion_tag() itu, kami mencirikan takes_context=True dan nama dari cetakan. Ini adalah cetakan link.html mungkin kelihatan seperti:

\n
Django template
Jump directly to <a href="{{ link }}">{{ title }}</a>.\n
\n

Lalu, kapanpun anda ingin menggunakan tag tersuai, muat pustakanya dan panggil tanpa argument, seperti:

\n
Django template
{% jump_link %}\n
\n

Catat bahwa ketika anda menggunakan takes_context=True, tidak perlu melewatkan argumen ke etiket cetakan. Dia otomatis mendapatkan akses ke konteks.

\n

Parameter takes_context awalnya adalah False. Ketika disetel ke True, etiket melewatkan obyek konteks, seperti dalam contoh ini. Itu hanya oerbedaan diantara kasus ini dan contoh inclusion_tag sebelumnya.

\n

Fungsi inclusion_tag mungkin menerima angka apapun dari penempatan atau argumen kata kunci. Sebagai contoh:

\n
Code
@register.inclusion_tag('my_template.html')\ndef my_tag(a, b, *args, **kwargs):\n    warning = kwargs['warning']\n    profile = kwargs['profile']\n    ...\n    return ...\n
\n

Kemudian dalam cetakan angka apapun dari argumen, dipisahkan oleh spasi, mungkin dilewatkan ke cetakan etiket. Seperti dalam Python, nilai untuk argumen katakunci disetel menggunakan tanda sama dengan ("=") dan harus disediakan setelah penempatan argumen. Sebagai contoh:

\n
Django template
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\n
\n
\n
\n

Etiket cetakan penyesuaian tingkat lanjutLink to this heading#

\n

Terkadang fitur dasar untuk pembuatan etiket cetakan penyesuaian tidak cukup. Jangan khawatir, Django memberikan anda akses lengkap ke internal yang diwajibkan untuk membangun sebuah etiket cetakan dari bawah ke atas.

\n
\n
\n

Ikhtisar cepatLink to this heading#

\n

Sistem cetakan bekerja dalam dua langkah pengolahan: menyusun dan membangun. Untuk menentukan etiket cetakan penyesuaian, anda menentukan bagaimana penyusunan bekerja dan bagaimana pembangunan bekerja.

\n

When Django compiles a template, it splits the raw template text into\n''nodes''. Each node is an instance of django.template.Node and has\na render() method. A compiled template is a list of Node objects. When\nyou call render() on a compiled template object, the template calls\nrender() on each Node in its node list, with the given context. The\nresults are all concatenated together to form the output of the template.

\n

Jadi, untuk menentukan penyesuaian cetakan etiket, anda menentukan bagaimana cetakan etiket mentah dirubah kedalam Node (fungsi penyusunan), dan apa cara render() node lakukan.

\n
\n
\n

Menulis fungsi himpunanLink to this heading#

\n

Untuk setiap etiket cetakan pertemuan pengurai cetakan, dia memanggil fungsi Python dengan isi etiket dan pengurai obyek itu sendiri. Fungsi ini bertanggung jawab untuk mengembalikan sebuah contoh Node berdasarkan pada isi dari etiket.

\n

For example, let's write a full implementation of our template tag,\n{% current_time %}, that displays the current date/time, formatted according\nto a parameter given in the tag, in strftime() syntax. It's a good\nidea to decide the tag syntax before anything else. In our case, let's say the\ntag should be used like this:

\n
Django template
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>\n
\n

Pengurai untuk fungsi ini harus mengambil parameter dan membuat obyek Node:

\n
Code
from django import template\n\ndef do_current_time(parser, token):\n    try:\n        # split_contents() knows not to split quoted strings.\n        tag_name, format_string = token.split_contents()\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires a single argument" % token.contents.split()[0]\n        )\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return CurrentTimeNode(format_string[1:-1])\n
\n

Catatan:

\n\n
\n
\n

Menulis pembangunLink to this heading#

\n

Langkah kedua dalam menulis penyesuaian etiket adalah menentukan sebuah subkelas Node yang mempunyai cara render().

\n

Melanjutkan contoh diatas, kami butuh menentukan CurrentTimeNode:

\n
Code
import datetime\nfrom django import template\n\nclass CurrentTimeNode(template.Node):\n    def __init__(self, format_string):\n        self.format_string = format_string\n\n    def render(self, context):\n        return datetime.datetime.now().strftime(self.format_string)\n
\n

Catatan:

\n\n

Akhirnya, pemisahan ini dari hasil penyusunan dan pembangunan dalam sebuah sistem cetakan efesien, karena sebuah cetakan dapat membangun banyak konteks tanpa harus diuraikan banyak kali.

\n
\n
\n

Pertimbangan pelolosan otomatisLink to this heading#

\n

Keluaran dari cetakan etiket tidak* otomatis berjalan melalui penyaring pelolosan otomatis (dengan pencegualian dari simple_tag() seperti yang digambarkan diatas). Bagaimanapun, masih terdapat sepasang hal anda harus ingat ketika menulis sebuah cetakan etiket.

\n

If the render() method of your template tag stores the result in a context\nvariable (rather than returning the result in a string), it should take care\nto call mark_safe() if appropriate. When the variable is ultimately\nrendered, it will be affected by the auto-escape setting in effect at the\ntime, so content that should be safe from further escaping needs to be marked\nas such.

\n

Juga, jika cetakan etiket anda membuat konteks baru untuk melakukan beberapa sub pembangunan, setel atribut pelolosan otomatis ke nilai konteks saat ini. Cara __init__ untuk kelas Context mengambil parameter dipanggil autoescape dimana anda dapat menggunakan untuk tujuan ini. Sebagai contoh:

\n
Code
from django.template import Context\n\ndef render(self, context):\n    # ...\n    new_context = Context({'var': obj}, autoescape=context.autoescape)\n    # ... Do something with new_context ...\n
\n

Ini bukan situasi paling umum, tetapi ini berguna jika anda membangun cetakan anda sendiri. Sebagai contoh:

\n
Code
def render(self, context):\n    t = context.template.engine.get_template('small_fragment.html')\n    return t.render(Context({'var': obj}, autoescape=context.autoescape))\n
\n

Jika kami mempunyai terlantar untuk dilewatkan dalam nilai context.autoescape saat ini ke Context baru kami dalam contoh ini, hasil akan mempunyai selalu otomatis diloloskan, yang mungkin perilaku yang tidak diinginkan jika cetakan etiket digunakan dalam sebuah blok {% autoescape off %}.

\n
\n
\n

Pertimbangan Thread-safetyLink to this heading#

\n

Sekali node diuraikan, cara render dia mungkin dipanggil sejumlah kali. Sejak Django terkadang berjalan dalam lingkungan banyak-rangkaian, sebuah node tunggal mungkin secara berkelanjutan membangun dengan konteks berbeda dalam menjawab ke dua permintaan terpisah. Oleh sebab itu, sangat penting untuk memastikan cetakan etiket anda adalah aman.

\n

Untuk memastikan cetakan etiket anda thread safe, anda harus jangan menyimpan informasi keadaan pada node itu sendiri. Sebagai contoh, Django menyediakan cetakan etiket cycle siap pakai yang berputar terhadap sebuah daftar dari deretan karakter yang diberikan setiap kali dia dibangun:

\n
Django template
{% for o in some_list %}\n    <tr class="{% cycle 'row1' 'row2' %}">\n        ...\n    </tr>\n{% endfor %}\n
\n

Sebuah penerapan yang dibuat-buat dari CycleNode mungkin kelihatan kurang lebih seperti ini:

\n
Code
import itertools\nfrom django import template\n\nclass CycleNode(template.Node):\n    def __init__(self, cyclevars):\n        self.cycle_iter = itertools.cycle(cyclevars)\n\n    def render(self, context):\n        return next(self.cycle_iter)\n
\n

Tetapi, seandainya kami mempunyai dua cetakan membangun potongan cetakan dari atas pada waktu bersamaan:

\n
    \n

  1. Urutan 1 melakukan pengulangan pertamanya, CycleNode.render() mengembalikan 'row1'

    2. \n

  2. Urutan 2 melakukan pengulangan pertamanya, CycleNode.render() mengembalikan 'row2'

    3. \n

  3. Urutan 1 melakukan pengulangan keduanya, CycleNode.render() mengembalikan 'row1'

    4. \n

  4. Urutan 2 melakukan pengulangan keduanya, CycleNode.render() mengembalikan 'row2'

    5. \n
\n

The CycleNode is iterating, but it's iterating globally. As far as Thread 1\nand Thread 2 are concerned, it's always returning the same value. This is\nnot what we want!

\n

Untuk mengalamatkan masalah ini, Django menyediakan sebuah render_context yang terhubung dengan context dari cetakan yang saat ini sedang dibangun. render_context berperilaku seperti sebuah kamus Python, dan harus digunakan untuk menyimpan keadaan Node diantara permohonan dari cara render.

\n

Mari kita refactor penerapan CycleNode kami untuk menggunakan render_context:

\n
Code
class CycleNode(template.Node):\n    def __init__(self, cyclevars):\n        self.cyclevars = cyclevars\n\n    def render(self, context):\n        if self not in context.render_context:\n            context.render_context[self] = itertools.cycle(self.cyclevars)\n        cycle_iter = context.render_context[self]\n        return next(cycle_iter)\n
\n

Catat bahwa ini sangat aman untuk menyimpan informasi umum yang tidak akan merubah keseluruhan hidup dari Node sebagai sebuah atribut. Dalam kasus CycleNode, argumen cyclevars tidak berubah setelah Node dipakai, jadi kami tidak butuh menaruhnya ke dalam render_context. Tetapi keadaan informasi yang khusus pada cetakan yang saat ini sedang dibangun, seperti putaran saat ini dari CycleNode, harus disimpan dalam render_context.

\n\n
\n
\n

Mendaftarkan etiketLink to this heading#

\n

Akhirnya, daftar etiket dengan instance Library modul anda, seperti dijelaskan dalam writing custom template tags diatas. Contoh:

\n
Code
register.tag('current_time', do_current_time)\n
\n

Cara tag() mengambil dua argumen:

\n
    \n

  1. Nama dari cetakan etiket -- sebuah deretan karakter. Jika ini dihilangkan dari fungsi penyusunan akan digunakan.

    2. \n

  2. Fungsi himpunan -- Sebuah fungsi Python (bukan nama fungsi sebagai deretan karakter).

    3. \n
\n

Dengan pendaftaran penyaring, dia juga memungkinkan menggunakan ini sebagai decorator:

\n
Code
@register.tag(name="current_time")\ndef do_current_time(parser, token):\n    ...\n\n@register.tag\ndef shout(parser, token):\n    ...\n
\n

Jika anda meninggalkan argumen name, seperti dalam contoh kedud diatas, Django akan menggunakan nama fungsi sebagai nama etiket.

\n
\n
\n

Melewatkan variabel cetakan ke etiketLink to this heading#

\n

Meskipun anda dapat melewatkan angka apapun dari argumen ke etiket cetakan menggunakan token.split_contents(), argumen semua tidak dipaketkan sebagai harfiah string. Sedikit kerja lebih diwajibkan untuk melewatkan isi dinamis (variabel cetakan) ke etiket cetakan sebagai sebuah argumen.

\n

Selagi contoh sebelumnya telah membentuk waktu saat ini ke dalam string dan mengembalikan string, misalkan anda ingin melewatkan di DateTimeField dari sebuah obyek dan mempunyai bentuk etiket cetakan yang tanggal-waktu:

\n
Django template
<p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>\n
\n

Mulanya, token.split_contents() akan mengembalikan tiga nilai:

\n
    \n

  1. Nama etiket format_time.

    2. \n

  2. String 'blog_entry.date_updated' (tanpa dikelilingi kutip).

    3. \n

  3. Pembentukan deretan karakter '"%Y-%m-%d %I:%M %p"'. Mengembalikan nilai dari split_contents() akan menyertakan kutipan awal dan akhir untuk deretan karakter persis seperti ini.

    4. \n
\n

Sekarang etiket anda harus kelihatan seperti ini:

\n
Code
from django import template\n\ndef do_format_time(parser, token):\n    try:\n        # split_contents() knows not to split quoted strings.\n        tag_name, date_to_be_formatted, format_string = token.split_contents()\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires exactly two arguments" % token.contents.split()[0]\n        )\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return FormatTimeNode(date_to_be_formatted, format_string[1:-1])\n
\n

Anda juga mempunyai kesemparan pembangun untuk mengambil isi sebenarnya dari sifat date_updated dari obyek blog_entry. Ini dapat diselesaikan dengan menggunakan kelas Variable() dalam django.template.

\n

Untuk menggunakan kelas Variable, instansiasikan itu dengan nama dari variabel untuk diselesaikan, dan panggil variable.resolve(context). Jadi, sebagai contoh:

\n
Code
class FormatTimeNode(template.Node):\n    def __init__(self, date_to_be_formatted, format_string):\n        self.date_to_be_formatted = template.Variable(date_to_be_formatted)\n        self.format_string = format_string\n\n    def render(self, context):\n        try:\n            actual_date = self.date_to_be_formatted.resolve(context)\n            return actual_date.strftime(self.format_string)\n        except template.VariableDoesNotExist:\n            return ''\n
\n

Keputusan variabel akan melempar sebuah pengecualian VariableDoesNotExist jika dia tidak dapat menyelesaikan deretan karakter dilewatkan ke dia dalam konteks saat ini dari halaman.

\n
\n
\n

Menyetel sebuah variabel di konteksLink to this heading#

\n

Contoh diatas mengengeluarkan nilai. Umumnya, itu lebih fleksibel jika etiket cetakan anda mensetel variabel cetakan daripada mengeluarkan nilai. Cara itu, penulis cetakan dapat menggunakan kembali nilai yang etiket cetakan anda buat.

\n

To set a variable in the context, use dictionary assignment on the context\nobject in the render() method. Here's an updated version of\nCurrentTimeNode that sets a template variable current_time instead of\noutputting it:

\n
Code
import datetime\nfrom django import template\n\nclass CurrentTimeNode2(template.Node):\n    def __init__(self, format_string):\n        self.format_string = format_string\n    def render(self, context):\n        context['current_time'] = datetime.datetime.now().strftime(self.format_string)\n        return ''\n
\n

Catat bahwa render() mengembalikan deretan karakter kosong. render() harus selalu mengembalikan keluaran deretan karakter. Jika semua cetakan etiket disetel variabel, ``render() harus mengembalikan deretan karakter kosong.

\n

Ini adalah bagaimana anda akan menggunakan versi baru dari etiket:

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" %}<p>The time is {{ current_time }}.</p>\n
\n\n

Tetapi, ada masalah dengan CurrentTimeNode2: Nama variabel current_time adalah dikode keraskan. Ini berarti anda akan butuh untuk memastikan cetakan anda tidak menggunakan {{ current_time }} dimanapun juga, karena {% current_time %} akan membabi buta meniban nilai variabel itu. Sebuah solusi pembersih adalah membuat cetakan etiket menentukan nama dari variabel keluaran, seperti begitu:

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" as my_current_time %}\n<p>The current time is {{ my_current_time }}.</p>\n
\n

Untuk melakukannya, anda akan butuh me refaktor kedua fungsi penyusun dan kelas Node, seperti begitu:

\n
Code
import re\n\nclass CurrentTimeNode3(template.Node):\n    def __init__(self, format_string, var_name):\n        self.format_string = format_string\n        self.var_name = var_name\n    def render(self, context):\n        context[self.var_name] = datetime.datetime.now().strftime(self.format_string)\n        return ''\n\ndef do_current_time(parser, token):\n    # This version uses a regular expression to parse tag contents.\n    try:\n        # Splitting by None == splitting by spaces.\n        tag_name, arg = token.contents.split(None, 1)\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires arguments" % token.contents.split()[0]\n        )\n    m = re.search(r'(.*?) as (\\w+)', arg)\n    if not m:\n        raise template.TemplateSyntaxError("%r tag had invalid arguments" % tag_name)\n    format_string, var_name = m.groups()\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return CurrentTimeNode3(format_string[1:-1], var_name)\n
\n

Perbedaan disini adalah bahwa do_current_time() mengambil bentuk deretan karakter dan nama variabel, melewatkan keduanya ke CurrentTimeNode3.

\n

Akhirnya, jika anda hanya butuh mempunyai sintaksis sederhana untuk penyesuaian pembaharuan-konteks cetakan etiket, pertimbangkan menggunakan jalan pintas simple_tag(), yang mendukung menetapkan hasil etiket ke cetakan variabel.

\n
\n
\n

Menguraikan sampai blok etiket lainLink to this heading#

\n

Cetakan etiket dapat bekerja dalam berduaan. Sebagai contoh, standar etiket {% comment %} menyembunyikan semua sampai {% endcomment %}. Untuk membuat sebuah cetakan etiket seperti ini, gunakan parser.parse() dalam fungsi penyusun anda

\n

Ini adalah bagaimana menyederhanakan etiket {% comment %} mungkin diterapkan:

\n
Code
def do_comment(parser, token):\n    nodelist = parser.parse(('endcomment',))\n    parser.delete_first_token()\n    return CommentNode()\n\nclass CommentNode(template.Node):\n    def render(self, context):\n        return ''\n
\n\n

parser.parse() mengambil sebuah tuple dari nama dari blok etiket "untuk diurai sampai". Dia mengembalikan sebuah contoh dari django.template.NodeList, yaitu sebuah daftar dari semua obyek Node yang pengurai jumpai "sebelum" dia menjumpai etiket dinamai apapun dalam tuple.

\n

Dalam "nodelist = parser.parse(('endcomment',))" di contoh atas, nodelist adalah sebuah daftar dari semua node diantara {% comment %} dan {% endcomment %}, bukan menghitung {% comment %} dan {% endcomment %} mereka sendiri.

\n

Setelah parser.parse() dipanggil, pengurai belum "mengkonsumsi" etiket {% endcomment %}, jadi kode butuh secara eksplisit memanggil parser.delete_first_token().

\n

CommentNode.render() mengembalikan string kosong. Apapun diantara {% comment %} dan {% endcomment %} diabaikan.

\n
\n
\n

Mengurai sampai blok etiket lainnya, dan menyimpan isiLink to this heading#

\n

Di contoh sebelumnya, do_comment() menyingkirkan apapun diantara {% comment %} and {% endcomment %}. Daripada melakukan itu, dimungkinkan untuk melakukan sesuatu dengan kode diantara blok etiket.

\n

Sebagai contoh, ini adalah penyesuaian cetakan etiket, {% upper %}, yang menghuruf besarkan semuanya diantara dia sendiri dan {% endupper %}.

\n

Penggunaan:

\n
Django template
{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}\n
\n

Seperti di contoh sebelumnya, kami akan menggunakan parser.parse(). Tetapi kali ini, kami melewatkan hasil nodelist ke Node:

\n
Code
def do_upper(parser, token):\n    nodelist = parser.parse(('endupper',))\n    parser.delete_first_token()\n    return UpperNode(nodelist)\n\nclass UpperNode(template.Node):\n    def __init__(self, nodelist):\n        self.nodelist = nodelist\n    def render(self, context):\n        output = self.nodelist.render(context)\n        return output.upper()\n
\n

Satu-satunya konsep disini adalah self.nodelist.render(context) dalam UpperNode.render().

\n

Untuk lebih contoh dari pembangunan rumit, lihat kode sumber dari {% for %} dalam django/template/defaulttags.py dan {% if %} di django/template/smartif.py.

\n
\n
","rootId":"custom-template-tags-and-filters","toc":[{"title":"Tata letak kode","anchor":"code-layout","children":[]},{"title":"Menulis saringan cetakan penyesuaian","anchor":"writing-custom-template-filters","children":[{"title":"Mendaftarkan saringan penyesuaian","anchor":"registering-custom-filters","children":[]},{"title":"Cetakan penyaring yang mengharapkan deretan karakter","anchor":"template-filters-that-expect-strings","children":[]},{"title":"Penyaring dan pelolosan otomatis","anchor":"filters-and-auto-escaping","children":[]},{"title":"Saringan dan zona waktu","anchor":"filters-and-time-zones","children":[]}]},{"title":"Menulis etiket cetakan penyesuaian","anchor":"writing-custom-template-tags","children":[{"title":"Etiket sederhana","anchor":"simple-tags","children":[]},{"title":"Penyertaaan etiket","anchor":"inclusion-tags","children":[]},{"title":"Etiket cetakan penyesuaian tingkat lanjut","anchor":"advanced-custom-template-tags","children":[]},{"title":"Ikhtisar cepat","anchor":"a-quick-overview","children":[]},{"title":"Menulis fungsi himpunan","anchor":"writing-the-compilation-function","children":[]},{"title":"Menulis pembangun","anchor":"writing-the-renderer","children":[]},{"title":"Pertimbangan pelolosan otomatis","anchor":"auto-escaping-considerations","children":[]},{"title":"Pertimbangan Thread-safety","anchor":"thread-safety-considerations","children":[]},{"title":"Mendaftarkan etiket","anchor":"registering-the-tag","children":[]},{"title":"Melewatkan variabel cetakan ke etiket","anchor":"passing-template-variables-to-the-tag","children":[]},{"title":"Menyetel sebuah variabel di konteks","anchor":"setting-a-variable-in-the-context","children":[]},{"title":"Menguraikan sampai blok etiket lain","anchor":"parsing-until-another-block-tag","children":[]},{"title":"Mengurai sampai blok etiket lainnya, dan menyimpan isi","anchor":"parsing-until-another-block-tag-and-saving-contents","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"Panduan \"Bagaimana\"","url":"/id/3.2/howto/"}],"prev":{"docname":"howto/custom-template-backend","title":"Custom template backend","url":"/id/3.2/howto/custom-template-backend/"},"next":{"docname":"howto/custom-file-storage","title":"Menulis sistem penyimpanan disesuaikan","url":"/id/3.2/howto/custom-file-storage/"},"formats":{"html":"/id/3.2/howto/custom-template-tags/","markdown":"/id/3.2/howto/custom-template-tags.md","json":"/id/3.2/howto/custom-template-tags.json"},"source":"https://github.com/django/django/blob/stable/3.2.x/docs/howto/custom-template-tags.txt","official":"https://docs.djangoproject.com/id/3.2/howto/custom-template-tags/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}