{"title":"Γράφοντας δικά σας template tags και φίλτρα","version":"1.11","locale":"el","docname":"howto/custom-template-tags","url":"/el/1.11/howto/custom-template-tags/","canonical":"https://djangodocs.dev/el/1.11/howto/custom-template-tags/","summary":"Η γλώσσα template του Django έρχεται με μια μεγάλη ποικιλία από προεγκατεστημένα tags και φίλτρα που έχουν σχεδιαστεί για να αντιμετωπίσουν τις ανάγκες της…","html":"

Γράφοντας δικά σας template tags και φίλτραLink to this heading#

\n

Η γλώσσα template του Django έρχεται με μια μεγάλη ποικιλία από προεγκατεστημένα tags και φίλτρα που έχουν σχεδιαστεί για να αντιμετωπίσουν τις ανάγκες της παρουσίασης της εφαρμογής σας. Παρόλ” αυτά, ίσως χρειαστείτε κάποια λειτουργία η οποία δεν υπάρχει στο βασικό πακέτο των template tags και φίλτρων. Μπορείτε να επεκτείνετε την template μηχανή του Django ορίζοντας δικά σας tags και φίλτρα χρησιμοποιώντας, τι άλλο, Python. Αφού τα δημιουργήσετε μπορείτε να τα χρησιμοποιήσετε στα templates σας αφού πρώτα τα φορτώσετε με το tag {% load %}.

\n
\n

Διάταξη κώδικαLink to this heading#

\n

Το πιο κοινό μέρος για να προσδιορίσετε τα δικά σας template tags και φίλτρα είναι μέσα στη Django εφαρμογή σας. Αν σχετίζονται, δε, και με την ήδη υπάρχουσα εφαρμογή, τότε είναι πολύ λογικό να ζουν μέσα στο φάκελο της. Αν όχι, τότε μπορούν να προστεθούν σε κάποια καινούργια εφαρμογή. Αν τα δικά σας template tags και φίλτρα αφορούν γενικά το project ή κάποια άλλη λειτουργία, μπορείτε να φτιάξετε μια νέα εφαρμογή πχ my_utils και να τα αποθηκεύσετε εκεί. Όταν ένα Django app προστίθεται στη λίστα INSTALLED_APPS, οποιοδήποτε tag που είναι ορισμένο στη συμβατική τοποθεσία που περιγράφεται παρακάτω, αυτόματα γίνεται διαθέσιμο για να φορτωθεί μέσα στα templates.

\n

Η εφαρμογή πρέπει να περιέχει ένα φάκελο templatetags, στο ίδιο επίπεδο με τα αρχεία models.py, views.py, κλπ. Αν ο φάκελος δεν υπάρχει ήδη, δημιουργήστε τον – μη ξεχάσετε να προσθέσετε το αρχείο __init__.py για να εξασφαλίσετε ότι ο φάκελος αυτός θα αντιμετωπιστεί ως ένα Python package.

\n\n

Τα δικά σας tags και φίλτρα θα υπάρχουν σε ένα module (όποτε λέμε module εννοούμε ένα φάκελο μαζί με το κενό αρχείο __init__.py μέσα του) μέσα στο templatetags. Το όνομα αυτού του module θα είναι αυτό που θα χρησιμοποιείτε αργότερα, για να φορτώνετε τα tags/φίλτρα, οπότε να είστε προσεκτικοί στην επιλογή του ονόματος ούτως ώστε να μην προκύψουν modules με το ίδιο όνομα σε άλλη εφαρμογή.

\n

Για παράδειγμα, αν τα δικά σας tags/φίλτρα βρίσκονται σε ένα αρχείο με το όνομα poll_extras.py, η δομή των αρχείων της εφαρμογής σας θα δείχνει κάπως έτσι:

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

Και μέσα στο template σας θα μπορείτε να κάνετε διαθέσιμα τα tags/φίλτρα αυτού του αρχείου ως εξής:

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

Η εφαρμογή που περιέχει τα δικά σας tags πρέπει να βρίσκεται μέσα στα INSTALLED_APPS προκειμένου το tag {% load %} να δουλέψει. Αυτό γίνεται για λόγους ασφαλείας: σας επιτρέπει να έχετε Python κώδικα από πολλές template βιβλιοθήκες σε μια μηχανή χωρίς να δοθεί πρόσβαση σε όλες αυτές για κάθε εγκατάσταση του Django.

\n

Δεν υπάρχει όριο στον αριθμό των modules που θα βάλετε μέσα στο templatetags. Θυμηθείτε όμως ότι το tag {% load %} θα φορτώσει τα tags/φίλτρα για το δοθέν όνομα του Python module που βρίσκεται μέσα στο templatetags, όχι το όνομα της εφαρμογής.

\n

Για να είναι μια έγκυρη tag βιβλιοθήκη, το module πρέπει να περιέχει μια μεταβλητή, επιπέδου module, με το όνομα register, ήτοι ένα instance της κλάσης template.Library, με την οποία όλα τα tags και τα φίλτρα θα γίνουν register. Επομένως, στην αρχή του module poll_extras.py, προσθέστε τα ακόλουθα:

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

Εναλλακτικά, τα modules του template tag μπορούν να γίνουν register μέσω του argument 'libraries' της κλάσης DjangoTemplates. Αυτό είναι χρήσιμο αν θέλετε να χρησιμοποιήσετε ένα διαφορετικό label από το όνομα του module όταν φορτώνετε τα template tags. Επίσης σας επιτρέπει να κάνετε register τα tags χωρίς την εγκατάσταση κάποια εφαρμογής.

\n\n
\n
\n

Γράφοντας δικά σας template φίλτραLink to this heading#

\n

Τα παραμετροποιήσιμα φίλτρα είναι απλώς Python συναρτήσεις οι οποίες δέχονται ένα ή δύο arguments:

\n\n

Για παράδειγμα, μέσα στη σύνταξη του φίλτρου {{ var|foo:"bar" }}, το φίλτρο foo θα λάβει μια μεταβλητή var (input) και ένα argument "bar".

\n

Εφόσον η γλώσσα του template δεν παρέχει exception handling, κάθε exception που θα γίνει raised από ένα template filter θα εμφανιστεί ως server error. Επομένως, οι συναρτήσεις των φίλτρων θα πρέπει να αποφεύγουν να κάνουν raise τυχόν exceptions αν υπάρχει κάποια λογική τιμή να επιστραφεί, ως fallback. Σε περίπτωση κάποιου input λόγω του οποίου φαίνεται ξεκάθαρα κάποιο bug στο template, το να κάνετε raise κάποιο exception είναι καλύτερο από το να το αφήσετε απαρατήρητο κάτι το οποίο θα κρύψει το bug.

\n

Παρακάτω φαίνεται ένα παράδειγμα ορισμού ενός φίλτρου:

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

Και εδώ φαίνεται ένα παράδειγμα του πως θα χρησιμοποιηθεί αυτό το φίλτρο στο template:

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

Τα περισσότερα φίλτρα δεν παίρνουν arguments. Σε αυτή την περίπτωση, απλώς αφήστε το εκτός από την συνάρτηση σας. Παράδειγμα:

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

Κάνοντας register τα δικά σας φίλτραLink to this heading#

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

Όταν γράψετε τον ορισμό του φίλτρου σας, θα χρειαστεί να το κάνετε register με το instance της κλάσης Library, για να το κάνετε διαθέσιμο στη γλώσσα template του Django:

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

Η μέθοδος Library.filter() παίρνει δύο ορίσματα:

\n
    \n

  1. Το όνομα του φίλτρου – τύπου string.

    2. \n

  2. Τη συνάρτηση του φίλτρου – μια Python συνάρτηση (όχι το όνομα της συνάρτησης ως string).

    3. \n
\n

Μπορείτε, αντ” αυτού, να χρησιμοποιήσετε τη μέθοδο register.filter() ως decorator:

\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

Αν δεν περάσετε το όρισμα name, όπως στο δεύτερο παράδειγμα παραπάνω, το Django θα χρησιμοποιήσει το όνομα της συνάρτησης ως το όνομα του φίλτρου.

\n

Εν τέλει, η μέθοδος register.filter() δέχεται τρία keyword arguments, το is_safe, το needs_autoescape και το expects_localtime. Αυτά τα arguments περιγράφονται στα φίλτρα και auto-escaping και στα φίλτρα και ζώνες ώρας παρακάτω.

\n
\n
\n

Template φίλτρα που περιμένουν stringsLink to this heading#

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

Αν γράφετε ένα template φίλτρο το οποίο περιμένει ένα argument τύπου string ως πρώτο argument, θα πρέπει να χρησιμοποιήσετε τον decorator stringfilter. Αυτό θα μετατρέψει το object στην string τιμή του πριν περαστεί στη συνάρτηση σας:

\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

Με αυτό τον τρόπο, θα μπορείτε να περνάτε, ας πούμε, έναν integer σε αυτό το φίλτρο και αυτό δεν θα προκαλέσει κάποιο AttributeError (επειδή οι integers δεν έχουν την μέθοδο lower()).

\n
\n
\n

Φίλτρα και auto-escapingLink to this heading#

\n

Όταν γράφετε ένα δικό σας φίλτρο, σκεφτείτε λιγάκι το πως θα αλληλεπιδρά με την auto-escaping συμπεριφορά του Django. Όταν λέμε auto-escaping εννοούμε τη δυνατότητα αυτόματης αποφυγής εμφάνισης συγκεκριμένων χαρακτήρων-λέξεων οι οποίοι αν εμφανιζόντουσαν θα προκαλούσαν, ενδεχομένως, πρόβλημα στο rendering της σελίδας. Σημειώστε ότι υπάρχουν τρεις τύποι strings οι οποίοι μπορούν να περαστούν μέσα σε κώδικα template:

\n\n

Ο κώδικας ενός template φίλτρου εμπίπτει σε μια από τις δύο ακόλουθες καταστάσεις:

\n
    \n

  1. Your filter does not introduce any HTML-unsafe characters (<, >,\n', " or &) into the result that were not already present. In\nthis case, you can let Django take care of all the auto-escaping\nhandling for you. All you need to do is set the is_safe flag to True\nwhen you register your filter function, like so:

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

    Αυτό το flag λέει στο Django ότι αν ένα «ασφαλές» string περαστεί στο φίλτρο σας, το αποτέλεσμα θα εξακολουθήσει να είναι «ασφαλές» ακόμη και αν ένα μη-ασφαλές string περαστεί, το Django, αυτόματα θα το κάνει escape, εάν χρειαστεί.

    \n

    Μπορείτε να το σκεφτείτε αλλιώς: «αυτό το φίλτρο είναι ασφαλές – δεν υπάρχει πιθανότητα τυχόν μη ασφαλούς HTML».

    \n

    Ο λόγος που το flag is_safe είναι απαραίτητο είναι επειδή υπάρχουν πολλών ειδών λειτουργίες για τα strings οι οποίες θα μετατρέψουν ένα object τύπου SafeData πίσω σε ένα κανονικό object τύπου str ή unicode (παρά να προσπαθήσουν να πιάσουν όλα τα strings κάτι το οποίο είναι δύσκολο) και το Django θα επιδιορθώσει τυχόν ζημιά αφού το φίλτρο έχει ολοκληρώσει τις εργασίες του.

    \n

    Για παράδειγμα, ας υποθέσουμε ότι έχετε ένα φίλτρο το οποίο προσθέτει το string xx στο τέλος κάθε input. Επειδή αυτό δεν εισάγει επικινδύνους HTML χαρακτήρες στο αποτέλεσμα (εκτός αυτού που είναι ήδη παρόν), θα πρέπει να μαρκάρετε το φίλτρο σας με το is_safe:

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

    Όταν αυτό το φίλτρο χρησιμοποιείται σε ένα template όπου το auto-escaping είναι ενεργοποιημένο, το Django θα κάνει escape την έξοδο οποτεδήποτε το input δεν είναι μαρκαρισμένο ως «ασφαλές».

    \n

    Από προεπιλογή, το flag is_safe είναι False και μπορείτε να το παραλείψετε από τα φίλτρα όπου δεν χρειάζεται.

    \n

    Να είστε προσεκτικοί όταν αποφασίζετε αν το φίλτρο σας αφήνει όντως τα safe strings ως safe. Εάν αφαιρείτε χαρακτήρες, μπορεί ακούσια να αφήσετε μη-ισορροπημένα HTML tags (χωρίς το start ή το end tag) ή οντότητες στο αποτέλεσμα. Για παράδειγμα, όταν αφαιρείτε ένα > από το input μπορεί να μετατρέψει ένα <a> σε <a, το οποίο θα χρειαστεί να γίνει escaped στην έξοδο για την αποφυγή τυχόν προβλημάτων. Ομοίως, η αφαίρεση του ; μπορεί να μετατρέψει το &amp; σε &amp, η οποία δεν είναι πλέον μια έγκυρη οντότητα και επομένως χρειάζεται περαιτέρω escaping. Οι περισσότερες περιπτώσεις δεν θα είναι τόσο πολύπλοκες αλλά προσέχετε για τέτοιου είδους προβλήματα όταν επανεξετάζετε τον κώδικα σας.

    \n

    Μαρκάροντας ένα φίλτρο ως is_safe θα αναγκάσει την επιστρεφόμενη τιμή του φίλτρου να γίνει ένα string. Αν το φίλτρο σας θα πρέπει να επιστρέψει μια τιμή τύπου boolean ή κάποια άλλη πέρα από string, μαρκάροντας το ως is_safe θα έχει πιθανόν ακούσιες συνέπειες (όπως τη μετατροπή της τιμής False τύπου boolean στο string “False”).

    \n
    2. \n

  2. Εναλλακτικά, ο κώδικας του φίλτρου σας μπορεί να χειριστεί χειροκίνητα, τυχόν αναγκαίο escaping. Αυτό είναι απαραίτητο όταν εισάγετε καινούργιο HTML κώδικα στο αποτέλεσμα σας. Θα θέλετε να μαρκάρετε την έξοδο ως ασφαλή από περαιτέρω escaping ούτως ώστε ο HTML κώδικας να μην γίνει περαιτέρω escape, οπότε θα χρειαστεί εσείς να χειριστείτε το input.

    \n

    Για να μαρκάρετε την έξοδο ως ασφαλή string, χρησιμοποιήστε τη συνάρτηση django.utils.safestring.mark_safe().

    \n

    Προσέχετε όμως. Θα χρειαστεί να κάνετε παραπάνω πράγματα από το να μαρκάρετε μόνο την έξοδο ως ασφαλή. Θα χρειαστεί να εξασφαλίσετε ότι είναι όντως ασφαλή και ότι κάνετε εξαρτάται από το αν το auto-escaping είναι ενεργοποιημένο ή όχι. Η ιδέα είναι να γράφετε φίλτρα τα οποία μπορούν να δρουν σε templates όπου το auto-escaping είναι είτε ενεργοποιημένο ή όχι, προκειμένου να κάνετε ευκολότερη τη δουλειά για τους συντάκτες των templates.

    \n

    Για να ξέρει το φίλτρο σας την κατάσταση του auto-escaping, θέστε το flag needs_autoescape σε True όταν κάνετε register το φίλτρο σας. (Αν δεν θέσετε αυτό το flag, η προεπιλεγμένη του τιμή είναι False). Αυτό το flag λέει στο Django ότι η συνάρτηση του φίλτρου σας δέχεται ένα επιπλέον keyword argument, με το όνομα autoescape, δηλαδή True αν το auto-escaping είναι ενεργοποιημένο και False αν όχι. Προτείνεται να θέσετε την προεπιπλεγμένη τιμή της παραμέτρου autoescape σε True, ούτως ώστε αν καλέσετε τη συνάρτηση του φίλτρου σας από τον Python κώδικα σας, το φίλτρο σας θα έχει το escaping ενεργοποιημένο από προεπιλογή.

    \n

    Για παράδειγμα, ας γράψουμε ένα φίλτρο το οποίο δίνει έμφαση στον πρώτο χαρακτήρα ενός string:

    \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

    Tο flag needs_autoescape και το keyword argument autoescape σημαίνουν ότι η συνάρτηση μας θα ξέρει αν το automatic escaping είναι ενεργοποιημένο ή όχι όταν το φίλτρο μας τρέξει. Χρησιμοποιούμε το autoescape για να αποφασίσουμε αν τα input data (το string που πέρασε στο φίλτρο μέσα από την HTML) θα χρειαστεί να περάσουν μέσα από την μέθοδο django.utils.html.conditional_escape ή όχι. (Στην τελευταία περίπτωση χρησιμοποιούμε μια lambda συνάρτηση ως την «escape» συνάρτηση.) Η συνάρτηση conditional_escape() είναι σαν την escape() αλλά κάνει escape το input το οποίο δεν είναι instance της κλάσης SafeData. Αν ένα instance μιας κλάσης SafeData περαστεί στη συνάρτηση conditional_escape(), τα δεδομένα θα επιστραφούν ανέπαφα.

    \n

    Στο παραπάνω παράδειγμα, θυμόμαστε να μαρκάρουμε το αποτέλεσμα ως ασφαλή ούτως ώστε η HTML που θα εισαχθεί απ” ευθείας μέσα στο template να μην υποστεί περαιτέρω escaping.

    \n

    Δεν υπάρχει λόγος να ανησυχούμε για το flag is_safe σε αυτή την περίπτωση (παρόλου που το περιλαμβάνουμε δεν βλάπτει κανέναν). Οποτεδήποτε χειρίζεστε χειροκίνητα τα θέματα του auto-escaping και επιστρέφετε ένα ασφαλή string, το flag is_safe δεν θα αλλάξει τίποτα με τον ένα ή τον άλλο τρόπο.

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

Φίλτρα και ζώνες ώραςLink to this heading#

\n

Αν γράφετε δικά σας φίλτρα τα οποία δρουν σε objects του τύπου datetime, συνήθως θα το κάνετε register με το flag expects_localtime ως 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

Όταν αυτό το flag είναι True, αν η πρώτη παράμετρος του φίλτρου σας είναι ένα datetime με επίγνωση της ζώνης ώρας (time zone aware datetime), το Django θα το μετατρέψει στην τρέχουσα ζώνη ώρας, κατά περίπτωση, πριν το περάσει στο φίλτρο σας, σύμφωνα με τους κανόνες μετατροπής ζωνών ώρας στα templates.

\n
\n
\n
\n

Γράφοντας δικάς σας template tagsLink to this heading#

\n

Τα tags είναι περισσότερο πολύπλοκα από τα φίλτρα, επειδή τα tags μπορούν να κάνουν τα πάντα. Το Django παρέχει έναν αριθμό από συντομεύσεις που κάνει τη συγγραφή των περισσότερων τύπων tags ευκολότερη. Πρώτα θα εξερευνήσουμε αυτές τις συντομεύσεις και ύστερα θα εξηγήσουμε πως να γράψετε ένα tag από την αρχή για τις περιπτώσεις που κάποια συντόμευση δεν σας καλύπτει.

\n
\n

Απλά tagsLink to this heading#

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

Πολλά template tags παίρνουν έναν αριθμό από παραμέτρους – strings ή μεταβλητές template – και επιστρέφουν ένα αποτέλεσμα αφού κάνουν κάποια επεξεργασία βασιζόμενα στις παραμέτρους και σε τυχόν εξωτερικές πληροφορίες. Για παράδειγμα, ένα tag με το όνομα current_time μπορεί να δεχτεί ένα string μορφοποίησης και να επιστρέψει την ώρα ως string, μορφοποιημένη σύμφωνα με αυτό που περάστηκε.

\n

Για να διευκολύνουμε τη δημιουργία αυτού του τύπου των tags, το Django παρέχει μια βοηθητική συνάρτηση, τη simple_tag. Αυτή η συνάρτηση, η οποία είναι μέθοδος της κλάσης django.template.Library, δέχεται μια συνάρτηση η οποία δέχεται παραμέτρους ανεξαρτήτως αριθμού, την κάνει wrap σε μια render συνάρτηση και άλλων απαραίτητων στοιχείων που αναφέρθηκαν παραπάνω και την κάνει register με το σύστημα του template.

\n

Η συνάρτηση μας current_time θα μπορούσε, επομένως, να γραφτεί κάπως έτσι:

\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

Μερικά πράγματα που πρέπει να σημειώσετε για την βοηθητική συνάρτηση simple_tag:

\n\n

Σε αντίθεση με λειτουργίες άλλων tags, το simple_tag περνάει την έξοδο του μέσα από τη συνάρτηση conditional_escape() αν το template context είναι σε λειτουργία autoescape, για να εξασφαλίσει σωστή HTML και για να σας προστατέψει από τρωτά σημεία του XSS.

\n

Αν δεν επιθυμείτε κάποιο πρόσθετο escaping, θα χρειαστεί να χρησιμοποιήσετε τη συνάρτηση mark_safe() αν είστε απόλυτα σίγουροι ότι ο κώδικας σας δεν είναι ευάλωτος σε XSS επιθέσεις. Για το χτίσιμο μικρών HTML αποσπασμάτων, η χρήση της συνάρτησης format_html() προτείνεται έναντι της mark_safe().

\n

Αν το template tag χρειάζεται να έχει πρόσβαση στο τρέχων template context, μπορείτε να χρησιμοποιήσετε την παράμετρο takes_context όταν κάνετε register το tag σας:

\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

Σημειώστε ότι η πρώτη παράμετρος πρέπει να ονομαστεί context.

\n

Για περισσότερες πληροφορίες σχετικά με τη λειτουργία της παραμέτρου takes_context, δείτε στην ενότητα inclusion tags.

\n

Αν χρειαστεί να μετονομάσετε το tag σας, μπορείτε να του δώσετε ένα δικό σας όνομα:

\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

Οι συναρτήσεις simple_tag μπορούν να δεχτούν απεριόριστο αριθμό από positional ή keyword arguments. Για παράδειγμα:

\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

Μετά, στο template, όλα τα arguments διαχωρισμένα με κενά (space character) μπορούν να περαστούν στο template tag. Όπως και στην Python, οι τιμές των keyword arguments ορίζονται με το σύμβολο της ισότητας (»=») και πρέπει να δηλωθούν μετά τα positional arguments. Για παράδειγμα:

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

Είναι πιθανόν να αποθηκεύσετε το αποτέλεσμα ενός tag σε μια template μεταβλητή παρά να την εμφανίζετε απ” ευθείας στο template σας. Αυτό γίνεται χρησιμοποιώντας το argument as ακολουθούμενο από το όνομα της template μεταβλητής όπου και θα αποθηκευτεί. Με αυτό τον τρόπο μπορείτε να εκτυπώσετε την τιμή αυτή οπουδήποτε αλλού στο template σας ή και με κάποια επιπλέον επεξεργασία (είτε σε αλλο tag ή φίλτρο):

\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

Inclusion tagsLink to this heading#

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

Ένας άλλο κοινός τύπος ενός template tag είναι ο τύπος που εμφανίζει κάποια δεδομένα κάνοντας rendering ένα άλλο template. Για παράδειγμα, το admin interface του Django χρησιμοποιεί δικά του template tags για να εμφανίζει τα κουμπιά στο κάτω μέρος της σελίδας της φόρμας που προσθέτετε ή αλλάζετε κάποιο object. Αυτά τα κουμπιά δείχουν παντού το ίδιο, αλλά το target του link αλάζει ανάλογα το object που επεξεργάζεται εκείνη τη στιγμή – αποτελούν λοιπόν μια τέλεια περίπτωση για τη χρήση μικρών template το οποίο είναι γεμάτο λεπτομέρειες από το τρέχων object. (Στην περίπτωση του admin, το tag ονομάζεται submit_row.)

\n

Αυτού του είδους τα tags ονομάζονται «inclusion tags».

\n

Η συγγραφή των inclusion tags φαίνεται καλύτερα μέσα από ένα παράδειγμα. Ας γράψουμε ένα tag το οποίο εξάγει μια λίστα από επιλογές για ένα δοθέν Poll object, το οποίο δημιουργήθηκε μέσα από το δεύτερο μέρος του οδηγού μας. Θα χρησιμοποιήσουμε το tag ως εξής:

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

…και η έξοδος του θα μοιάζει κάπως έτσι:

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

Πρώτα, πρέπει να ορίσετε τη συνάρτηση η οποία παίρνει το argument και επιστρέφει ένα dictionary από δεδομένα. Το σημαντικό εδώ είναι ότι το μόνο που χρειάζεται να επιστρέψουμε είναι ένα dictionary, όχι κάτι περίπλοκο. Αυτό θα χρησιμοποιηθεί ως template context για το κομμάτι του template. Παράδειγμα:

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

Επόμενο βήμα είναι να δημιουργήσετε το template το οποίο θα κάνει render την έξοδο του tag. Αυτό το template είναι ένα μόνιμο χαρακτηριστικό του tag: το προσδιορίζει ο συντάκτης του tag και όχι ο σχεδιαστής του template. Εν ακολουθία του παραδείγματος μας, το template είναι πολύ απλό:

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

Τώρα, δημιουργήστε και κάντε register το inclusion tag καλώντας τη μέθοδο inclusion_tag() σε ένα object της κλάσης Library. Ακολουθώντας το παράδειγμα μας, αν το παραπάνω template βρίσκεται σε ένα αρχείο με το όνομα results.html σε κάποιο φάκελο που είναι ανιχνεύσιμος από τον template loader, θα κάναμε register το tag κάπως έτσι:

\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

Εναλλακτικά μπορείτε να κάνετε register το inclusion tag χρησιμοποιώντας ένα instance της κλάσης :class:`django.template.

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

…όταν πρωτο-δημιουργείτε τη συνάρτηση.

\n

Μερικές φορές, τα inclusion tags μπορεί να χρειάζονται έναν μεγάλο αριθμό από παραμέτρους, κάνοντας δύσκολο για τους συντάκτες των templates να περάσουν όλες τις παραμέτρους και να θυμούνται τη σειρά τους. Για την αντιμετώπιση αυτού του προβλήματος, το Django προσφέρει την επιλογή takes_context τύπου boolean για inclusion tags. Αν τη θέσετε ``True `` όταν δημιουργείτε τη συνάρτηση, το tag δεν θα έχει απαιτούμενες παραμέτρους και η Python συνάρτηση του tag θα έχει μόνο μια παράμετρο – το template context όπως είναι όταν κλήθηκε το tag.

\n

Για παράδειγμα, ας υποθέσουμε ότι γράφετε ένα inclusion tag το οποίο θα χρησιμοποιείται πάντα σε κάποιο context που περιέχει τις μεταβλητές home_link και home_title οι οποίες θα οδηγούν πίσω στην αρχική σελίδα. Η Python συνάρτηση του tag θα δείχνει κάπως έτσι:

\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

Σημειώστε ότι η πρώτη παράμετρος της συνάρτησης πρέπει να ονομάζεται context.

\n

Στη γραμμή register.inclusion_tag(), προσδιορίσαμε το keyword argument takes_context=True και το όνομα του template. Το template link.html θα δείχνει κάπως έτσι:

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

Έπειτα, κάθε φορά που θέλετε να χρησιμοποιήσετε αυτό το tag, φορτώστε τη βιβλιοθήκη ({% load <όνομα_αρχείου> %}) και καλέσετε τη χωρίς ορίσματα, ως εξής:

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

Σημειώστε ότι, όταν χρησιμοποιείτε το takes_context=True, δεν χρειάζεται να περάσετε παραμέτρους μέσα στο template tag. Αυτόματα, έχει πρόσβαση στο template context.

\n

Η προεπιλεγμένη τιμή της παραμέτρου takes_context είναι False. Όταν τη θέτετε True, περνάει το context object μέσα στο tag, όπως σε αυτό το παράδειγμα. Αυτή είναι η μόνη διαφορά μεταξύ αυτής της περίπτωσης και του προηγούμενου inclusion_tag παραδείγματος.

\n

Οι συναρτήσεις των inclusion_tag μπορούν να δεχτούν αναρίθμητα positional ή keyword arguments. Για παράδειγμα:

\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

Μετά, στο template, όλα τα arguments διαχωρισμένα με κενά (space character) μπορούν να περαστούν στο template tag. Όπως και στην Python, οι τιμές των keyword arguments ορίζονται με το σύμβολο της ισότητας (»=») και πρέπει να δηλωθούν μετά τα positional arguments. Για παράδειγμα:

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

Assignment tagsLink to this heading#

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

Για την διευκόλυνση της δημιουργίας μια μεταβλητής στο template context μέσω των tags, το Django παρέχει μια βοηθητική συνάρτηση, την assignment_tag. Αυτή η συνάρτηση δουλεύει με τον ίδιο τρόπο όπως η μέθοδος simple_tag() με τη μόνη διαφορά ότι η assignment_tag αποθηκεύει το αποτέλεσμα του tag σε μια μεταβλητή του context αντί να την εκτυπώνει απ” ευθείας στο template.

\n

Η προηγούμενη συνάρτηση current_time θα μπορούσε, επομένως, να γραφτεί ως:

\n
Code
@register.assignment_tag\ndef get_current_time(format_string):\n    return datetime.datetime.now().strftime(format_string)\n
\n

Μπορείτε πλέον να αποθηκεύσετε το αποτέλεσμα σε μια μεταβλητή του template χρησιμοποιώντας το argument as ακολουθούμενο από το όνομα της μεταβλητής. Έπειτα μπορείτε να εκτυπώσετε την τιμή της μεταβλητής οπουδήποτε μέσα στο template επιθυμείτε:

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

Παραμετροποιήσιμα template tags για προχωρημένουςLink to this heading#

\n

Μερικές φορές τα βασικά χαρακτηριστικά για τη δημιουργία του δικού σας template tag δεν είναι αρκετά. Μην ανησυχείτε, το Django σας δίνει πλήρη πρόσβαση στα εσωτερικά που απαιτούνται για να φτιάξετε ένα template tag από την αρχή.

\n
\n
\n

Μια γρήγορη ματιάLink to this heading#

\n

Το σύστημα του template λειτουργεί ακολουθώντας μια διαδικασία δύο σταδίων: compiling και rendering. Για να ορίσετε ένα δικό σας template tag, πρέπει να προσδιορίσετε πως δουλεύει το compilation και πως το rendering.

\n

Όταν το Django συντάσσει (compiles) ένα template, χωρίζει το κείμενο του template σε μια λίστα από “”nodes””. Κάθε node είναι ένα instance της κλάσης django.template.Node και έχει μια μέθοδο render(). Ένα compiled template είναι, απλώς, μια λίστα από objects τύπου Node. Όταν καλείτε τη μέθοδο render() σε ένα compiled template object, το template καλεί τη μέθοδο render() για καθένα Node που βρίσκεται στη λίστα του, με το δοθέν context. Τα αποτελέσματα ενώνονται όλα μεταξύ τους για να συνθέσουν την έξοδο του template.

\n

Επομένως, για να ορίσετε ένα δικό σας template tag, προσδιορίζετε πως ένα template tag μετατρέπεται σε ένα Node (η συνάρτηση του compilation) και τι κάνει η μέθοδος render() του node.

\n
\n
\n

Γράφοντας τη συνάρτηση του compilationLink to this heading#

\n

Για κάθε template tag που βρίσκει ο template parser, καλείται μια Python συνάρτηση με τα περιεχόμενα του tag και το ίδιο το parser object. Αυτή η συνάρτηση είναι υπεύθυνη να επιστρέψει ένα instance του Node βασιζόμενη στα περιεχόμενα του tag.

\n

Για παράδειγμα, ας γράψουμε μια πλήρης υλοποίηση του απλού μας template tag, {% current_time %}, το οποίο εμφανίζει την τρέχουσα ημερομηνία/ώρα, μορφοποιημένη σύμφωνα με τις παραμέτρους (σύνταξη func:~time.strftime) που δόθηκαν στο tag. Είναι καλή ιδέα να αποφασίσετε τη σύνταξη του tag πριν από οτιδήποτε άλλο. Στη δικιά μας περίπτωση, ας πούμε ότι το tag θα πρέπει να χρησιμοποιείται κάπως έτσι:

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

Ο parser για αυτή τη συνάρτηση θα πρέπει να παίρνει την παράμετρο και να δημιουργεί ένα object του 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

Σημειώσεις

\n\n
\n
\n

Γράφοντας τον rendererLink to this heading#

\n

Το δεύτερο βήμα για τη δημιουργία δικών μας tags είναι ο ορισμός της subclass της Node η οποία έχει μια μέθοδο render().

\n

Συνεχίζοντας το παραπάνω παράδειγμα, χρειάζεται να ορίσουμε το 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

Σημειώσεις

\n\n

Τελικώς, αυτή η αποσύνδεση μεταξύ του compilation και του rendering έχει ως αποτέλεσμα ένα αποδοτικό σύστημα template, επειδή ένα template μπορεί να κάνει render πολλαπλά contexts χωρίς να χρειαστεί να γίνει parsed πολλές φορές.

\n
\n
\n

Εκτιμήσεις σχετικά με το auto-escapingLink to this heading#

\n

Η έξοδος των template tags δεν περνούν αυτόματα μέσα από auto-escaping φίλτρα (εκτός της μεθόδου simple_tag(), όπως περιγράφηκε παραπάνω). Ωστόσο, υπάρχουν ακόμη μερικά πράγματα που πρέπει να έχετε στο νου σας όταν γράφετε ένα template tag.

\n

Αν η συνάρτηση render() του template σας αποθηκεύει το αποτέλεσμα σε μια context variable (αντί να επιστρέφει το αποτέλεσμα σε ένα string), θα πρέπει να φροντίσει να καλέσει την mark_safe(), αν αυτό είναι απαραίτητο. Όταν η μεταβλητή γίνει, τελικώς, rendered (εμφανιστεί-τυπωθεί στο template, αν θέλετε), θα επηρεαστεί από τη ρύθμιση του auto-escape (αναλόγως αν είναι ενεργοποιημένη ή όχι), οπότε το περιεχόμενο που πρέπει να είναι safe από περαιτέρω escaping χρειάζεται να μαρκαριστεί.

\n

Επίσης, αν το template tag σας δημιουργεί ένα καινούργιο context για να εκτελέσει κάποιο sub-rendering, θέστε το attribute του auto-escape στην τιμή του τρέχοντος context. Η μέθοδος __init__ για την κλάση Context δέχεται μια παράμετρο με το όνομα autoescape, την οποία μπορείτε να χρησιμοποιήσετε για αυτό το σκοπό. Για παράδειγμα:

\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

Αυτό δεν είναι μια συνηθισμένη περίπτωση, αλλά είναι χρήσιμο να το ξέρετε αν κάνετε rendering ένα template εσείς οι ίδιοι.

\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

Αν δεν περνάγαμε την τιμή του context.autoescape στο νέο μας Context σε αυτό το παράδειγμα, τα αποτελέσματα θα γινόντουσαν πάντα αυτόματα escaped, κάτι το οποίο μπορεί να μην ήταν η επιθυμητική συμπεριφορά αν το template tag χρησιμοποιούταν μέσα στο block tag {% autoescape off %}.

\n
\n
\n

Εκτιμήσεις σχετικά με την ασφάλεια των threadsLink to this heading#

\n

Όταν ένα node γίνει parsed, η render μέθοδος του μπορεί να καλεστεί πολλές φορές. Επειδή το Django, μερικές φορές, τρέχει σε περιβάλλοντα multi-threaded, ένα απλό node μπορεί ταυτοχρόνως να γίνει rendering με διαφορετικά contexts ως response για δύο ξεχωριστά requests. Επομένως, είναι σημαντικό να εξασφαλίσετε ότι τα template tags σας είναι thread safe.

\n

Για να το εξασφαλίσετε αυτό, δεν θα πρέπει να αποθηκεύετε ποτέ τις πληροφορίες της κατάστασης στο ίδιο το node. Για παράδειγμα, το Django παρέχει ένα προεγκατεστημένο template tag cycle το οποίο ανατρέχει μια λίστα από δοθέντα strings κάθε φορά που γίνεται rendered:

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

Μια απλοϊκή υλοποίηση του CycleNode θα έμοιαζε κάπως έτσι:

\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

Αλλά, ας υποθέσουμε ότι την ίδια χρονική στιγμή, δύο templates κάνουν rendering το κομμάτι του template παραπάνω:

\n
    \n

  1. Το Thread 1 πραγματοποιεί την πρώτη επανάληψη του βρόγχου, η μέθοδος CycleNode.render() επιστρέφει “row1”

    2. \n

  2. Το Thread 2 πραγματοποιεί την πρώτη επανάληψη του βρόγχου, η μέθοδος CycleNode.render() επιστρέφει “row2”

    3. \n

  3. Το Thread 1 πραγματοποιεί την δεύτερη επανάληψη του βρόγχου, η μέθοδος CycleNode.render() επιστρέφει “row1”

    4. \n

  4. Το Thread 2 πραγματοποιεί την δεύτερη επανάληψη του βρόγχου, η μέθοδος CycleNode.render() επιστρέφει “row2”

    5. \n
\n

Το CycleNode κάνει την επανάληψη (iterating), αλλά την κάνει καθολικά (globally). Όσον αφορά τα Thread 1 και Thread 2, το καθένα επιστρέφει πάντα την ίδια τιμή. Αυτό, φυσικά, δεν είναι αυτό που θέλουμε!

\n

Για την αποφυγή τέτοιων καταστάσεων, το Django παρέχει ένα render_context το οποίο σχετίζεται με το context του template το οποίο γίνεται εκείνη τη στιγμή rendered. Το render_context συμπεριφέρεται όπως ένα Python dictionary και θα πρέπει να χρησιμοποιείται για να αποθηκεύονται οι καταστάσεις του Node μεταξύ κλήσεων της μεθόδου render.

\n

Ας αλλάξουμε την υλοποίηση της κλάσης CycleNode για να χρησιμοποιεί το 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

Σημειώστε ότι δεν είναι καθόλου λάθος να αποθηκεύετε ως attribute καθολικές πληροφορίες οι οποίες δεν αλλάζουν κατά τη διάρκεια της ζωής ενός Node. Στην περίπτωση του CycleNode, το argument cyclevars δεν αλλάζει μετά την αρχικοποίηση του Node, οπότε δεν χρειάζεται να το βάλουμε μέσα στο render_context. Αλλά η πληροφορία της κατάστασης η οποία είναι συγκεκριμένη στο template το οποίο γίνεται rendered, όπως η τρέχουσα επανάληψη βρόγχου του CycleNode, θα πρέπει να αποθηκευτεί μέσα στο render_context.

\n\n
\n
\n

Κάνοντας register το tagLink to this heading#

\n

Τέλος, κάντε register το tag με το instance του module Library, όπως εξηγήθηκε στην ενότητα γράφοντας δικά σας template φίλτρα παραπάνω. Παράδειγμα:

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

Η μέθοδος tag() λαμβάνει δύο arguments:

\n
    \n

  1. Το όνομα του template tag – ένα string. Αν αυτό παραλειφθεί, θα χρησιμοποιηθεί το όνομα της συνάρτησης του compilation.

    2. \n

  2. Τη συνάρτηση του φίλτρου – μια Python συνάρτηση (όχι το όνομα της συνάρτησης ως string).

    3. \n
\n

Όπως και με το registration των φιλτρών, μπορείτε να χρησιμοποιήσετε έναν 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

Αν παραλείψετε την παράμετρο name, όπως στο δεύτερο παράδειγμα παραπάνω, το Django θα χρησιμοποιήσει το όνομα της συνάρτησης ως το όνομα του tag.

\n
\n
\n

Περνώντας template μεταβλητές στο tagLink to this heading#

\n

Όπως γνωρίζετε μπορείτε να περάσετε οποιοδήποτε αριθμό από παραμέτρους σε ένα template tag και χρησιμοποιώντας τη μέθοδο token.split_contents() οι παράμετροι θα είναι διαθέσιμες σε εσάς ως strings. Ωστόσο, χρειάζεται λίγη περισσότερη δουλειά για να περάσετε δυναμικό περιεχόμενο (μια template μεταβλητή) στο template tag ως παράμετρο.

\n

Ενώ τα προηγούμενα παραδείγματα μορφοποιούσαν την τρέχουσα ώρα σε ένα string και επέστρεφαν το string, υποθέστε τώρα ότι θέλετε να περάσετε ένα DateTimeField από ένα object και θέλετε το template tag να μορφοποιήσει αυτό το object (αυτή την ημερομηνία-ώρα, αν θέλετε):

\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

Αρχικά, η μέθοδος token.split_contents() θα επιστρέψει τρεις τιμές:

\n
    \n

  1. Το όνομα του tag, format_time.

    2. \n

  2. Το string 'blog_entry.date_updated' (χωρίς τα μονά εισαγωγικά).

    3. \n

  3. Το string που θα χρησιμοποιηθεί για την μορφοποίηση '"%Y-%m-%d %I:%M %p"'. Η επιστρεφόμενη τιμή από τη μέθοδο split_contents() θα συμπεριλάβει τα διπλά εισαγωγικά στην αρχή και το τέλος των strings (όπως ακριβώς εισήχθησαν στο tag μέσα στο template).

    4. \n
\n

Τώρα το tag θα αρχίσει να μοιάζει κάπως έτσι:

\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

Θα χρειαστεί επίσης να αλλάξετε και τον renderer για να λάβει τα πραγματικά περιεχόμενα του date_updated property του object blog_entry. Αυτό μπορεί να επιτευχθεί χρησιμοποιώντας την κλάση Variable() μέσα στο django.template.

\n

Για να χρησιμοποιήσετε την κλάση Variable, απλώς αρχικοποιήστε τη με το όνομα της μεταβλητής η οποία θα γίνει resolved και μετά καλέστε τη μέθοδο variable.resolve(context). Άρα, για παράδειγμα:

\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

Η αναζήτηση της μεταβλητής (variable resolution) θα κάνει throw ένα exception VariableDoesNotExist αν δεν μπορεί να γίνει resolve το string ('blog_entry.date_updated') που περάστηκε στο τρέχων context της σελίδας.

\n
\n
\n

Θέτοντας μια μεταβλητή στο contextLink to this heading#

\n

Το παραπάνω παράδειγμα απλώς εξάγει μια τιμή. Γενικότερα, είναι περισσότερο ευέλικτο αν τα template tags σας θέτουν template μεταβλητές αντί να εξάγουν (εκτυπώνουν) τις τιμές τους. Με αυτό τον τρόπο, οι συντάκτες των template θα μπορούν να επαναχρησιμοποιούν τις τιμές τις οποίες δημιούργησαν τα template tags σας.

\n

Για να θέσετε μια μεταβλητή στο context, απλώς χρησιμοποιήστε την εκχώρηση της στο dictionary του context object μέσα στη μέθοδο render(). Παρακάτω φαίνεται μια ενημερωμένη έκδοση της κλάσης CurrentTimeNode η οποία θέτει την template μεταβλητή current_time αντί απλώς να την εκτυπώνει:

\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

Σημειώστε ότι η μέθοδος render() επιστρέφει ένα κενό string. Η render() θα πρέπει πάντα να επιστρέφει ένα string. Αν το μόνο που κάνει ένα template tag είναι να ορίζει μια μεταβλητή, τότε η render() θα πρέπει να επιστρέφει ένα κενό string.

\n

Παρακάτω φαίνεται πως μπορείτε να χρησιμοποιείτε τη νέα αυτή έκδοση του tag:

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

Αλλά υπάρχει ένα πρόβλημα με την κλάση CurrentTimeNode2: Το όνομα της μεταβλητής current_time είναι γραμμένο hard-coded. Αυτό σημαίνει ότι πρέπει να σιγουρευτείτε πως το template σας δεν χρησιμοποιεί πουθενά αλλού το {{ current_time }}, επειδή το {% current_time %} θα έκανε overwrite την τιμή της μεταβλητής. Μια πιο καθαρή λύση είναι να κάνετε το template tag να προσδιορίσει ένα όνομα για τη μεταβλητή, ως εξής:

\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

Για να το κάνετε αυτό, θα χρειαστεί να αλλάξετε και τη συνάρτηση του compilation και την κλάση Node, ως εξής:

\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

Η διαφορά εδώ είναι ότι η μέθοδος do_current_time() παίρνει το format μορφοποίησης και το όνομα της μεταβλητής και δίνει και τα δύο στην κλάση CurrentTimeNode3.

\n

Τέλος, αν θέλετε μόνο να έχετε μια απλή σύνταξη για το δικό σας template tag που αλληλεπιδρά με το context και το ενημερώνει, σκεφτείτε να χρησιμοποιήσετε τη συντόμευση simple_tag(), η οποία υποστηρίζει τον ορισμό μεταβλητής της εξόδου ενός tag (μέσω της λέξη-κλειδί as, όπως είδαμε παραπάνω).

\n
\n
\n

Κάνοντας parsing μέχρι να βρεθεί κάποιο άλλο block tagLink to this heading#

\n

Τα template tags μπορούν να δουλέψουν αλυσιδωτά. Για παράδειγμα, το στάνταρντ tag {% comment %} αγνοεί τα πάντα μέχρι να βρει το tag {% endcomment %}. Για να δημιουργήσετε ένα template tag όπως αυτό, χρησιμοποιήστε τη μέθοδο parser.parse() μέσα στη συνάρτηση του compilation.

\n

Εδώ φαίνεται η υλοποίηση της απλοποιημένης έκδοσης του tag {% comment %}:

\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() παίρνει ένα tuple από ονόματα block tags “”να γίνει parse μέχρι””. Επιστρέφει ένα instance του django.template.NodeList, το οποίο είναι μια λίστα από Node objects τα οποία βρήκε ο parser “”πριν”” βρει κάποιο από τα tags που είναι μέσα στο tuple.

\n

Στο "nodelist = parser.parse(('endcomment',))" στο παραπάνω παράδειγμα, η nodelist είναι μια λίστα από όλα τα nodes μεταξύ του {% comment %} και του {% endcomment %}, χωρίς τα ίδια τα {% comment %} και {% endcomment %}.

\n

Αφού καλεστεί η parser.parse(), ο parser δεν έχει «καταναλώσει» ακόμα το {% endcomment %} tag, οπότε ο κώδικας χρειάζεται να καλέσει ρητώς τη μέθοδο parser.delete_first_token().

\n

Η μέθοδος CommentNode.render() απλώς επιστρέφει ένα κενό string. Οτιδήποτε μεταξύ του {% comment %} και {% endcomment %} αγνοείται.

\n
\n
\n

Κάνοντας parsing μέχρι να βρεθεί κάποιο άλλο block tag και αποθήκευση περιεχομένωνLink to this heading#

\n

Στο προηγούμενο παράδειγμα, η συνάρτηση do_comment() απέρριπτε τα πάντα μεταξύ του blck tag {% comment %} και {% endcomment %}, επειδή θεωρούνταν σχόλια και αυτά δεν γινόντουσαν render στην τελική σελίδα που θα έβλεπε ο χρήστης. Αντί να γίνεται αυτό, μπορείτε να κάνετε κάτι με τον κώδικα μεταξύ των block tags.

\n

Για παράδειγμα, εδώ φαίνεται ένα παραμετροποιήσιμο template tag, με το όνομα {% upper %}, το οποίο μετατρέπει σε κεφαλαία γράμματα όλους τους χαρακτήρες μεταξύ του ίδιου και του {% endupper %}.

\n

Χρήση

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

Όπως στο προηγούμενο παράδειγμα, θα χρησιμοποιήσουμε τη μέθοδο parser.parse(). Αλλά αυτή τη φορά, θα περάσουμε τη nodelist στο Node, εν αντιθέσει με την προηγούμενη φορά που επιστρέφαμε το CommentNode() χωρίς κάποιο nodelist μέσα:

\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

Η μοναδική καινούργια έννοια εδώ είναι το self.nodelist.render(context) μέσα στη μέθοδο UpperNode.render().

\n

Για περισσότερα παραδείγματα περίπλοκων renderings, δείτε τον πηγαίο κώδικα του tag {% for %} στο αρχείο django/template/defaulttags.py και το tag {% if %} στο αρχείο django/template/smartif.py.

\n
\n
","rootId":"custom-template-tags-and-filters","toc":[{"title":"Διάταξη κώδικα","anchor":"code-layout","children":[]},{"title":"Γράφοντας δικά σας template φίλτρα","anchor":"writing-custom-template-filters","children":[{"title":"Κάνοντας register τα δικά σας φίλτρα","anchor":"registering-custom-filters","children":[]},{"title":"Template φίλτρα που περιμένουν strings","anchor":"template-filters-that-expect-strings","children":[]},{"title":"Φίλτρα και auto-escaping","anchor":"filters-and-auto-escaping","children":[]},{"title":"Φίλτρα και ζώνες ώρας","anchor":"filters-and-time-zones","children":[]}]},{"title":"Γράφοντας δικάς σας template tags","anchor":"writing-custom-template-tags","children":[{"title":"Απλά tags","anchor":"simple-tags","children":[]},{"title":"Inclusion tags","anchor":"inclusion-tags","children":[]},{"title":"Assignment tags","anchor":"assignment-tags","children":[]},{"title":"Παραμετροποιήσιμα template tags για προχωρημένους","anchor":"advanced-custom-template-tags","children":[]},{"title":"Μια γρήγορη ματιά","anchor":"a-quick-overview","children":[]},{"title":"Γράφοντας τη συνάρτηση του compilation","anchor":"writing-the-compilation-function","children":[]},{"title":"Γράφοντας τον renderer","anchor":"writing-the-renderer","children":[]},{"title":"Εκτιμήσεις σχετικά με το auto-escaping","anchor":"auto-escaping-considerations","children":[]},{"title":"Εκτιμήσεις σχετικά με την ασφάλεια των threads","anchor":"thread-safety-considerations","children":[]},{"title":"Κάνοντας register το tag","anchor":"registering-the-tag","children":[]},{"title":"Περνώντας template μεταβλητές στο tag","anchor":"passing-template-variables-to-the-tag","children":[]},{"title":"Θέτοντας μια μεταβλητή στο context","anchor":"setting-a-variable-in-the-context","children":[]},{"title":"Κάνοντας parsing μέχρι να βρεθεί κάποιο άλλο block tag","anchor":"parsing-until-another-block-tag","children":[]},{"title":"Κάνοντας parsing μέχρι να βρεθεί κάποιο άλλο block tag και αποθήκευση περιεχομένων","anchor":"parsing-until-another-block-tag-and-saving-contents","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"Οδηγοί «Πως-να»","url":"/el/1.11/howto/"}],"prev":{"docname":"howto/custom-lookups","title":"Παραμετροποιήσιμα Lookups","url":"/el/1.11/howto/custom-lookups/"},"next":{"docname":"howto/custom-file-storage","title":"Γράφοντας ένα δικό σας σύστημα αποθήκευσης (storage system)","url":"/el/1.11/howto/custom-file-storage/"},"formats":{"html":"/el/1.11/howto/custom-template-tags/","markdown":"/el/1.11/howto/custom-template-tags.md","json":"/el/1.11/howto/custom-template-tags.json"},"source":"https://github.com/django/django/blob/stable/1.11.x/docs/howto/custom-template-tags.txt","official":"https://docs.djangoproject.com/el/1.11/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"],"inLocales":["en","fr","ja","id","pt-br","ko","es","el","pl"]}