Do stron można dodawać pliki i linki, dzięki czemu mogą być one cytowane w treści oraz udostępniane do pobrania. Dostęp do załączników zależy od uprawnień do przeglądania danej strony, więc użytkownicy mogą otwierać tylko te pliki, które znajdują się na stronach, do których mają dostęp.
Załączniki służą głównie do wygodnego przechowywania i korzystania z plików. System nie wykonuje na nich żadnych specjalnych operacji, takich jak skanowanie czy indeksowanie zawartości, ponieważ dokumentacja jest tworzona z myślą o umieszczaniu treści bezpośrednio w tekście stron.
Tworzenie i przesyłanie załączników
Załączniki można dodawać za pomocą paska bocznego w edytorze strony. Sekcja załączników jest oznaczona ikoną spinacza i po jej otwarciu wygląda następująco:
W tej sekcji dostępne są opcje „Prześlij plik” lub „Dołącz link”. Plik można też przeciągnąć i upuścić w obszarze przycisków, aby szybko go przesłać ze swojego urządzenia. Najczęściej przesyła się pliki, ale można także dodać link do strony, który działa jako kontrolowany pod względem uprawnień odnośnik/URL do używania i udostępniania.
Poniżej przycisków widoczna jest lista wszystkich przesłanych załączników. Za pomocą uchwytów po lewej stronie można je przestawiać. Każdy załącznik ma przyciski do usunięcia lub edycji. Podczas edycji można zmienić nazwę załącznika oraz podmienić plik lub link, przy czym oryginalny URL pozostaje niezmieniony. Jest też przycisk pozwalający wstawić załącznik do strony, co opisano w sekcji „Używanie załączników na stronach”.
Warto pamiętać, że załączniki są powiązane ze stronami, do których zostały dodane. Dostęp do załącznika zależy od możliwości przeglądania strony. Jeśli strona zostanie usunięta, wszystkie powiązane z nią załączniki również zostaną usunięte.
Dostęp do załączników
Po przesłaniu, załączniki będą widoczne w pasku bocznym podczas przeglądania strony. Można kliknąć załącznik, aby go otworzyć. Linki otwierają się w nowej karcie, natomiast pliki można pobrać lub obejrzeć w nowej karcie za pomocą menu rozwijanego po prawej stronie załącznika:
Alternatywnie można przytrzymać klawisz Ctrl (lub Cmd na Macu) i kliknąć załącznik, aby otworzyć go bezpośrednio w nowej karcie. Należy pamiętać, że załączniki otwierane w nowej karcie mogą nadal zostać pobrane, jeśli format pliku nie jest uważany za bezpieczny do wyświetlenia w przeglądarce lub jeśli takie jest domyślne zachowanie przeglądarki.
Używanie załączników na stronach
Chociaż załączniki widoczne są w pasku bocznym podczas przeglądania strony, można też tworzyć do nich odnośniki bezpośrednio w treści. Jest to przydatne, gdy chcemy dodać kontekst lub wskazać konkretny załącznik w danym miejscu dokumentacji. Istnieje kilka sposobów, aby to zrobić.
Pierwsza metoda polega na użyciu przycisku z ikoną „linku” przy załączniku w pasku bocznym. Kliknięcie tego przycisku wstawi odnośnik do strony w miejscu, gdzie znajduje się kursor, z poprawnym URL i nazwą załącznika.
Druga metoda to przeciąganie i upuszczanie. Można przeciągnąć załącznik z paska bocznego, korzystając z jego uchwytu lub nazwy, a następnie upuścić go w edytorze – w tym miejscu automatycznie zostanie wstawiony link do załącznika.
Trzeci sposób wykorzystuje standardowe funkcje przeglądarki i edytora. Można kliknąć prawym przyciskiem myszy na załącznik, skopiować jego URL, a następnie wstawić link w treści strony w zwykły sposób, korzystając ze skopiowanego adresu.
Szczegóły techniczne
Podczas przesyłania i pobierania załączników system stara się przesyłać pliki strumieniowo tam, gdzie to możliwe. Dzięki temu aplikacja może obsługiwać duże pliki szybko, bez nadmiernego zużycia pamięci systemowej lub konieczności zwiększania limitu pamięci PHP. Jeśli używany jest magazyn oparty na S3, pliki są obecnie przesyłane strumieniowo z aplikacji do serwera, ale nie w drugą stronę, więc w przypadku dużych plików lepiej przechowywać i udostępniać je bezpośrednio z magazynu, jeśli to możliwe.
Nawet przy przesyłaniu strumieniowym mogą wystąpić limity po stronie serwera lub proxy dotyczące rozmiaru pliku lub czasu oczekiwania. Dokumentacja administracyjna dotycząca przesyłania plików może pomóc w rozwiązywaniu takich problemów.
Gdy załączniki są wyświetlane w linii (otwierane w nowej karcie lub z parametrem open=true), system stara się wykryć typ MIME pliku, a następnie udostępnia go z tym typem MIME, aby umożliwić jego podgląd w przeglądarce, jeśli jest obsługiwany i uznany za bezpieczny. Na przykład pliki HTML nie są wyświetlane w linii. Proces ten opiera się na wewnętrznej liście dozwolonych typów MIME.