Ta strona jest próbą wyjaśnienia w jaki sposób dane dynamicznie generowane przez Moodle powinny być wysłane do przeglądarki. Oczywiście stosowanie swoich własnych metod jest możliwe, jednak biorąc pod uwagę opensource'owy charakter projektu, dostosowanie się do niżej przedstawionych wytycznych wydaje się być lepszym pomysłem. Dzięki temu łatwiej ponownie używać kod i utrzymywać system.
Stosując poniższe zalecenia uczynisz swój kod lepszym, bezpieczniejszym i czytelniejszym. Proszę, poświęć kilka minut na zrozumienie tych reguł.
Oczywiście, można dyskutować na temat niżej przedstawionych funkcji, modyfikować je, a nawet dodać inne, jeśli znajdzie się ku temu dobry powód. Wystarczy, że przyłączysz się do dyskusji na ogólnym forum developerów na moodle.org.
Każdą z poniższych funkcji opiszemy, wyjaśniając najważniejsze argumenty i ich znaczenie. Zatem, obejrzyjmy je!
p() i s()
function s($var, $strip=false) function p($var, $strip=false)
Te funkcje używają wspólnego kodu, więc zostaną opisane razem. Jedyną różnicą między nimi jest fakt, iż s() zwraca cały napis, podczas gdy p() wypisuje go bezpośrednio.
Funkcje te powinny być używane do:
- wyświetlania wszystkich wartości pól formularza, takich jak elementy <input> czy <textarea>.
- aby wyświetlić czysty, prosty tekst (nie HTML), który został wprowadzony przez użytkownika (np. hasło wyszukiwarki, odpowiedzi do quizów...).
- ogólnie, wszystkie dynamiczne dane, nie będące HTML-em, które nie muszą być oczyszczane, ani przetwarzane przez żadne filtry.
Istotne jest, aby nie używać tych funkcji do tekstów, zawierających kod HTML.
Jeśli tekst przekazany do tych funkcji zawiera znaki, posiadające specjalne znaczenia w HTML ( <, >, ", ' oraz &), to zostaną one zastąpione przez encje HTML, co pozwoli na ich poprawne wyświetlenie. Zwróć uwagę na fakt, że nawet jeśli ustawisz wartości pól formularza za pomocą tych funkcji i znajdą się tam encje HTML, to ponownie wysłane dane będą z powrotem zawierać oryginalny tekst.
Kluczowym parametrem tych funkcji jest:
- strip: określa, czy chcemy wyciąć ukośniki z napisu. Domyślnie jest on ustawiony na "false", tak że ukośniki nie są wycinane. Powinniśmy ustawić ten parametr na "true" tylko wtedy, gdy przetwarzane dane nie pochodzą z bazy danych, lecz z żądań HTTP (formularze, hiperłącza...).
format_text()
function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )
Ta funkcja powinna być używana do:
- wyświetlenia tekstu html/czystego/markdown/moodle, kiedy potrzebna jest którakolwiek z poniższych funkcji. Głównie używana do długich tekstów, takich jak posty, odpowiedzi, elementy słownika...
Zwróć uwagę, że ta funkcja jest naprawdę ciężka, ponieważ obsługuje oczyszczanie z niebezpiecznych treści, stosuje filtry, wspiera różne formaty tekstu (HTML, PLAIN, MARKDOWN, MOODLE) i wykonuje mnóstwo automatycznych konwersji, takich jak dodawanie uśmieszków, czy konstruowanie hiperłączy. Zawiera także potężny mechanizm cache'owania oparty na bazie danych, który oszczędza serwerowi dużo pracy przy przetwarzaniu tych samych tekstów.
Interesującymi parametrami tej funkcji są:
- format: mówi, w jaki sposób dane zostały wprowadzone. Domyślnie przyjmuje wartość FORMAT_MOODLE, który jest dobrym formatem do obsługi czystego tekstu, ponieważ zawiera automatyczną konwersję hiperłączy, uśmieszków i dobrą konwersję do wyjściowego HTML-a. Inne dostępne formaty to: FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. Zobacz Opcje formatowania.
- options: tutaj możemy określić w jaki sposób ma być wykonane przetwarzanie. Musisz podać ten parametr tylko wtedy, gdy twoje oczekiwania różnią się od domyślnej wartości. Głównymi opcjami są:
- options->noclean: określa, czy tekst powinien być oczyszczony. Ustawienie tej opcji na "true" naraża nas na ataki i inne nadużycia związane z bezpieczeństwem. Nigdy nie powinieneś ustawiać tej opcji na "true", chyba że jesteś pewien na 200%, że tekst został wprowadzony przez zaufaną osobę (głównie administratora). Nigdy nie używaj jej przy tekstach pobieranych od użytkowników (posty...). W przeciwnym wypadku prędzej czy później zostaniesz zaatakowany! Zwróć uwagę, że ta opcja jest ignorowana, jeśli określono FORMAT_PLAIN, dla którego filtry nigdy nie są stosowane.
- options->filter: określa, czy mają być zastosowane filtry (domyślnie "true"). Ta opcja jest ignorowana przy FORMAT_PLAIN, gdzie filtry nigdy nie są stosowane.
- options->smiley: określa, czy chcemy automatycznej zamiany uśmieszków (emotikonek) na obrazki (domyślnie ustawione na "true"). Ta opcja jest ignorowana przy FORMAT_PLAIN, gdzie obrazki nigdy nie są dodawane.
- options->para: określa, czy każdy akapit tekstu ma być automatycznie objęty HTML-owymi znacznikami akapitów (<p>...</p>) (domyślnie ustawione na "true"). Ta opcja ma znaczenie tylko przy FORMAT_MOODLE.
- options->newlines: określa, czy przejścia do nowej linii w tekście powinny być konwertowane na odpowiedni element HTML (<br />) (domyślnie na "true"). Ta opcja ma znaczenie tylko w przypadku FORMAT_MOODLE.
- courseid: ten parametr powinien być zawsze przekazany, aby pomóc filtrom zadecydować, w jaki sposób powinny działać. Ten argument będzie miał coraz mniejsze znaczenie w miarę postępu prac w Moodle. Aktualnie implementowana jest funkcja trzymania id bieżącego kursu w sesji/zmiennej globalnej, jednak na dzień dzisiejszy zaleca się podawanie tego parametru.
format_string()
function format_string ($string, $striplinks = true, $courseid=NULL )
Ta funkcja powinna być używana do:
- wyświetlania krótkich, nie HTML-owych tekstów, wymagających filtrowania (tytuły ćwiczeń, tematy postów, pojęcia słownikowe...).
Zauważ, że ta funkcja jest zasadniczo okrojoną wersją pełnej funkcji format_text() opisanej powyżej i nie obsługuje żadnej z jej opcji czy zabezpieczeń. Po prostu filtruje ciąg znaków i zwraca wynik, a więc musimy upewnić się, że przetwarzany tekst został poprawnie oczyszczony w momencie pobierania przez właściwe wywołanie odpowiedniej funkcji xxx_param().
Interesującymi parametrami tej funkcji są:
- striplinks: określa, czy po przefiltrowaniu powinny być usunięte hiperłącza. Ta opcja jest użwana, gdy chcemy wyświetlić tekst wewnątrz menu, tytułów stron... (domyślnie "true").
- courseid: ten parametr powinien być zawsze przekazany, aby pomóc filtrom zadecydować, w jaki sposób powinny działać. Ten argument będzie miał coraz mniejsze znaczenie w miarę postępu prac w Moodle. Aktualnie implementowana jest funkcja trzymania id bieżącego kursu w sesji/zmiennej globalnej, jednak na dzień dzisiejszy zaleca się podawanie tego parametru.
print_textarea()
function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value='', $courseid=0, $return=false)
Ta funkcja powinna być używana do:
- wyświetlania pól <textarea>, jeśli chcemy umożliwić użytkownikom (zależnie od ich preferencji i możliwości przeglądarki) używanie wizualnego edytora HTML zamiast zwykłego, prostego pola tekstowego.
Interesującymi parametrami tej funkcji są:
- usehtmleditor: określa, czy powinien zostać wyświetlony edytor HTML. Wartość tego argumentu musi zostać określona za pomocą funkcji can_use_html_editor().
- rows, cols: jeśli zostało wyświetlone standardowe pole tekstowe, parametry te określają jego rozmiar (odpowiednio w wierszach i kolumnach).
- width, height: jeśli został wyświetlony edytor HTML, parametry te określają jego rozmiar.
- name: nazwa pola, zawierającego tekst, używana przy wysyłaniu tekstu.
- value: początkowa wartość pola tekstowego.
- courseid: ten parametr powinien być zawsze przekazany, aby pomóc filtrom zadecydować, w jaki sposób powinny działać. Ten argument będzie miał coraz mniejsze znaczenie w miarę postępu prac w Moodle. Aktualnie implementowana jest funkcja trzymania id bieżącego kursu w sesji/zmiennej globalnej, jednak na dzień dzisiejszy zaleca się podawanie tego parametru.
- return: określa, czy wygenerowany kod HTML powinien być zwrócony (true), czy wyświetlony od razu (false). Domyślnie przyjmuje wartość false.
