Στοιχεία HTML
Η κλάση Nette\Utils\Html είναι ένας βοηθός για τη δημιουργία κώδικα HTML, ο οποίος δεν επιτρέπει τη δημιουργία της ευπάθειας Cross Site Scripting (XSS).
Λειτουργεί έτσι ώστε τα αντικείμενά του να αντιπροσωπεύουν στοιχεία HTML, στα οποία ορίζουμε παραμέτρους και τα αφήνουμε να απεικονιστούν:
$el = Html::el('img'); // vytvoří element <img> - δημιουργεί το στοιχείο <img>
$el->src = 'image.jpg'; // nastaví atribut src - ορίζει το χαρακτηριστικό src
echo $el; // vypíše '<img src="image.jpg">' - εκτυπώνει '<img src="image.jpg">'
Εγκατάσταση:
composer require nette/utils
Όλα τα παραδείγματα προϋποθέτουν τη δημιουργία ενός ψευδώνυμου:
use Nette\Utils\Html;
Δημιουργία στοιχείου HTML
Δημιουργούμε το στοιχείο με τη μέθοδο Html::el():
$el = Html::el('img'); // vytvoří element <img> - δημιουργεί το στοιχείο <img>
Εκτός από το όνομα, μπορείτε να καθορίσετε και άλλα χαρακτηριστικά στη σύνταξη HTML:
$el = Html::el('input type=text class="red important"');
Ή να τα περάσετε ως συσχετιστικό πίνακα στη δεύτερη παράμετρο:
$el = Html::el('input', [
'type' => 'text',
'class' => 'important',
]);
Αλλαγή και επιστροφή του ονόματος του στοιχείου:
$el->setName('img');
$el->getName(); // 'img'
$el->isEmpty(); // true, jelikož <img> je prázdný element - true, επειδή το <img> είναι ένα κενό στοιχείο
Χαρακτηριστικά HTML
Μπορούμε να αλλάξουμε και να διαβάσουμε μεμονωμένα χαρακτηριστικά HTML με τρεις τρόπους, εξαρτάται από εσάς ποιος σας αρέσει περισσότερο. Ο πρώτος είναι μέσω ιδιοτήτων:
$el->src = 'image.jpg'; // nastaví atribut src - ορίζει το χαρακτηριστικό src
echo $el->src; // 'image.jpg'
unset($el->src); // zruší atribut - ακυρώνει το χαρακτηριστικό
// nebo $el->src = null; - ή $el->src = null;
Ο δεύτερος τρόπος είναι η κλήση μεθόδων, τις οποίες, σε αντίθεση με τη ρύθμιση ιδιοτήτων, μπορούμε να αλυσιδώσουμε:
$el = Html::el('img')->src('image.jpg')->alt('photo');
// <img src="image.jpg" alt="photo">
$el->alt(null); // zrušení atributu - ακύρωση χαρακτηριστικού
Και ο τρίτος τρόπος είναι ο πιο φλύαρος:
$el = Html::el('img')
->setAttribute('src', 'image.jpg')
->setAttribute('alt', 'photo');
echo $el->getAttribute('src'); // 'image.jpg'
$el->removeAttribute('alt');
Μαζικά, τα χαρακτηριστικά μπορούν να ρυθμιστούν χρησιμοποιώντας το
addAttributes(array $attrs) και να αφαιρεθούν χρησιμοποιώντας το
removeAttributes(array $attrNames).
Η τιμή του χαρακτηριστικού δεν χρειάζεται να είναι μόνο string, μπορούν να χρησιμοποιηθούν και λογικές τιμές για λογικά χαρακτηριστικά:
$checkbox = Html::el('input')->type('checkbox');
$checkbox->checked = true; // <input type="checkbox" checked>
$checkbox->checked = false; // <input type="checkbox">
Το χαρακτηριστικό μπορεί επίσης να είναι ένας πίνακας τιμών, οι οποίες εκτυπώνονται χωρισμένες με κενά, το οποίο είναι χρήσιμο, για παράδειγμα, για κλάσεις CSS:
$el = Html::el('input');
$el->class[] = 'active';
$el->class[] = null; // null se ignoruje - το Null αγνοείται
$el->class[] = 'top';
echo $el; // '<input class="active top">'
Μια εναλλακτική λύση είναι ένας συσχετιστικός πίνακας, όπου οι τιμές λένε αν το κλειδί πρέπει να εκτυπωθεί:
$el = Html::el('input');
$el->class['active'] = true;
$el->class['top'] = false;
echo $el; // '<input class="active">'
Τα στυλ CSS μπορούν να γραφτούν με τη μορφή συσχετιστικών πινάκων:
$el = Html::el('input');
$el->style['color'] = 'green';
$el->style['display'] = 'block';
echo $el; // '<input style="color: green; display: block">'
Τώρα χρησιμοποιήσαμε ιδιότητες, αλλά το ίδιο μπορεί να γραφτεί με μεθόδους:
$el = Html::el('input');
$el->style('color', 'green');
$el->style('display', 'block');
echo $el; // '<input style="color: green; display: block">'
Ή ακόμα και με τον πιο φλύαρο τρόπο:
$el = Html::el('input');
$el->appendAttribute('style', 'color', 'green');
$el->appendAttribute('style', 'display', 'block');
echo $el; // '<input style="color: green; display: block">'
Μια μικρή λεπτομέρεια στο τέλος: η μέθοδος href() μπορεί να
διευκολύνει τη σύνθεση παραμέτρων query στο URL:
echo Html::el('a')->href('index.php', [
'id' => 10,
'lang' => 'en',
]);
// '<a href="index.php?id=10&lang=en"></a>'
Χαρακτηριστικά δεδομένων
Τα χαρακτηριστικά δεδομένων έχουν ειδική υποστήριξη. Επειδή τα
ονόματά τους περιέχουν παύλες, η πρόσβαση μέσω ιδιοτήτων και μεθόδων
δεν είναι τόσο κομψή, γι' αυτό υπάρχει η μέθοδος data():
$el = Html::el('input');
$el->{'data-max-size'} = '500x300'; // není tolik elegantní - δεν είναι τόσο κομψό
$el->data('max-size', '500x300'); // je elegatní - είναι κομψό
echo $el; // '<input data-max-size="500x300">'
Αν η τιμή του χαρακτηριστικού δεδομένων είναι πίνακας, σειριοποιείται αυτόματα σε JSON:
$el = Html::el('input');
$el->data('items', [1,2,3]);
echo $el; // '<input data-items="[1,2,3]">'
Περιεχόμενο στοιχείου
Ορίζουμε το εσωτερικό περιεχόμενο του στοιχείου με τις μεθόδους
setHtml() ή setText(). Χρησιμοποιήστε την πρώτη μόνο σε περίπτωση
που γνωρίζετε ότι περνάτε ένα αξιόπιστα ασφαλές string HTML στην
παράμετρο.
echo Html::el('span')->setHtml('hello<br>');
// '<span>hello<br></span>'
echo Html::el('span')->setText('10 < 20');
// '<span>10 < 20</span>'
Και αντίστροφα, λαμβάνουμε το εσωτερικό περιεχόμενο με τις μεθόδους
getHtml() ή getText(). Η δεύτερη αφαιρεί τις ετικέτες HTML από την
έξοδο και μετατρέπει τις οντότητες HTML σε χαρακτήρες.
echo $el->getHtml(); // '10 < 20'
echo $el->getText(); // '10 < 20'
Θυγατρικοί κόμβοι
Το εσωτερικό του στοιχείου μπορεί επίσης να είναι ένας πίνακας
θυγατρικών κόμβων (children). Κάθε ένας από αυτούς μπορεί να είναι είτε ένα
string είτε ένα άλλο στοιχείο Html. Τα εισάγουμε χρησιμοποιώντας
addHtml() ή addText():
$el = Html::el('span')
->addHtml('hello<br>')
->addText('10 < 20')
->addHtml( Html::el('br') );
// <span>hello<br>10 < 20<br></span>
Ένας άλλος τρόπος για τη δημιουργία και την εισαγωγή ενός νέου κόμβου
Html:
$ul = Html::el('ul');
$ul->create('li', ['class' => 'first'])
->setText('první'); // πρώτο
// <ul><li class="first">první</li></ul>
Μπορείτε να εργαστείτε με τους κόμβους με τον ίδιο τρόπο σαν να ήταν
πίνακας. Δηλαδή, να έχετε πρόσβαση σε καθέναν από αυτούς
χρησιμοποιώντας αγκύλες, να τους μετρήσετε χρησιμοποιώντας
count() και να επαναλάβετε πάνω τους:
$el = Html::el('div');
$el[] = '<b>hello</b>';
$el[] = Html::el('span');
echo $el[1]; // '<span></span>'
foreach ($el as $child) { /* ... */ }
echo count($el); // 2
Ένας νέος κόμβος μπορεί να εισαχθεί σε μια συγκεκριμένη θέση
χρησιμοποιώντας το insert(?int $index, $child, bool $replace = false). Αν το
$replace = false, εισάγει το στοιχείο στη θέση $index και μετακινεί
τα υπόλοιπα. Αν το $index = null, προσθέτει το στοιχείο στο τέλος.
// vloží prvek na první pozici a ostatní posune - εισάγει το στοιχείο στην πρώτη θέση και μετακινεί τα υπόλοιπα
$el->insert(0, Html::el('span'));
Λαμβάνουμε όλους τους κόμβους με τη μέθοδο getChildren() και τους
αφαιρούμε με τη μέθοδο removeChildren().
Δημιουργία τμήματος εγγράφου
Αν θέλουμε να εργαστούμε με έναν πίνακα κόμβων και δεν μας ενδιαφέρει
το περιβάλλον στοιχείο, μπορούμε να δημιουργήσουμε ένα λεγόμενο
τμήμα εγγράφου περνώντας null αντί για το όνομα του
στοιχείου:
$el = Html::el(null)
->addHtml('hello<br>')
->addText('10 < 20')
->addHtml( Html::el('br') );
// hello<br>10 < 20<br>
Ένας γρηγορότερος τρόπος δημιουργίας ενός τμήματος προσφέρεται από
τις μεθόδους fromHtml() και fromText():
$el = Html::fromHtml('hello<br>');
echo $el; // 'hello<br>'
$el = Html::fromText('10 < 20');
echo $el; // '10 < 20'
Δημιουργία εξόδου HTML
Ο απλούστερος τρόπος για να εκτυπώσετε ένα στοιχείο HTML είναι να
χρησιμοποιήσετε το echo ή να μετατρέψετε τον τύπο του
αντικειμένου σε (string). Μπορείτε επίσης να εκτυπώσετε ξεχωριστά
τις ετικέτες ανοίγματος ή κλεισίματος και τα χαρακτηριστικά:
$el = Html::el('div class=header')->setText('hello');
echo $el; // '<div class="header">hello</div>'
$s = (string) $el; // '<div class="header">hello</div>'
$s = $el->toHtml(); // '<div class="header">hello</div>'
$s = $el->toText(); // 'hello'
echo $el->startTag(); // '<div class="header">'
echo $el->endTag(); // '</div>'
echo $el->attributes(); // 'class="header"'
Ένα σημαντικό χαρακτηριστικό είναι η αυτόματη προστασία από Cross Site Scripting (XSS). Όλες οι τιμές
των χαρακτηριστικών ή το περιεχόμενο που εισάγεται μέσω setText() ή
addText() γίνεται αξιόπιστα escape:
echo Html::el('div')
->title('" onmouseover="bad()')
->setText('<script>bad()</script>');
// <div title='" onmouseover="bad()'><script>bad()</script></div>
Μετατροπή HTML ↔ κείμενο
Για τη μετατροπή HTML σε κείμενο, μπορείτε να χρησιμοποιήσετε τη
στατική μέθοδο htmlToText():
echo Html::htmlToText('<span>One & Two</span>'); // 'One & Two'
HtmlStringable
Το αντικείμενο Nette\Utils\Html υλοποιεί το interface Nette\HtmlStringable,
με το οποίο, για παράδειγμα, το Latte ή οι φόρμες διακρίνουν αντικείμενα
που έχουν μια μέθοδο __toString() που επιστρέφει κώδικα HTML. Έτσι δεν
θα υπάρξει δι
