Joomla! Documentation™

Joomla! 

2.5

Joomla! 

3.x

Joomla! 

4.x

Wprowadzenie

Ten samouczek ma na celu nauczenie programistów, jak utworzyć serwer aktualizacji do integracji z systemem aktualizacji wprowadzonym w Joomla!. Dodając listę serwerów aktualizacji do manifestu rozszerzenia, programiści umożliwiają użytkownikom aktualizowanie rozszerzeń za pośrednictwem Menadżera Aktualizacji Rozszerzeń (zobacz ekran pomocy Joomla 3.x).

Definiowanie serwera aktualizacji

Aby móc korzystać z tej funkcji, serwer aktualizacji musi być zdefiniowany w manifeście rozszerzenia. Ta definicja może być używana we wszystkich rozszerzeniach Joomla! 2.5 oraz nowszych kompatybilnych, ale nie jest dostępna dla szablonów. Możesz użyć dwóch opcji dla swojego typu serwera: kolekcji lub rozszerzenia. Zostaną one wkrótce szczegółowo objaśnione.Ten kod powinien być dodany do pliku manifestu rozszerzenia, wewnątrz głównego elementu rozszerzenia. Serwer aktualizacji jest zdefiniowany w następujący sposób dla każdego typu:

 <extension>
 <...>
 <updateservers>
    <server type="collection">https://example.com/list.xml</server>
    <server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
 </updateservers>
 </extension>

W tagu <updateservers> można zdefiniować wiele serwerów. Jeśli masz więcej niż jeden serwer aktualizacji, możesz ustawić inny priorytet dla każdego znich. W ten sposób możesz kontrolować kolejność, w jakiej sprawdzane są serwery aktualizacji.

Typy serwerów

Kolekcja

Typ serwera "kolekcja" umożliwia programistom definiowanie manifestu rozszerzenia w celu pobierania aktualizacji z kolekcji. Ten typ serwera może być używany, jeśli deweloper chce zdefiniować wszystkie aktualizacje swojego rozszerzenia w jednym pliku (niezalecane) lub jeśli jego rozszerzenie ma wiele rozszerzeń podrzędnych, które nie są dystrybuowane lub aktualizowane w tym samym czasie (takie jak typ rozszerzenia pakietu). Poniższy przykład to definicja „kolekcji” używana przez aktualizator podczas przetwarzania aktualizacji podstawowych Joomla!:

 <extensionset name="Joomla Core" description="Joomla! Core">
    <extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="https://update.joomla.org/core/extension.xml"/>
 </extensionset>

Wszystkie definicje muszą być zdefiniowane pomiędzy tagami <extensionset> w manifeście kolekcji. Tag <extensionset> posiada dwa opcjonalne parametry: nazwę i opis. Dla każdego rozszerzenia, do którego odwołuje się ta kolekcja, wymagany jest oddzielny tag <extension>. Tag <extension> ma następujące parametry, z których wszystkie są wymagane do prawidłowego przetwarzania aktualizacji:

• name – nazwa rozszerzenia
• element – nieprzetłumaczona nazwa rozszerzenia, np. mod_custom
• type – typ rozszerzenia (komponent, moduł, plugin, itp.)
• version – najnowsza wersja rozszerzenia
• detailsurl – adres URL pliku XML, który zawiera indywidualne definicje aktualizacji dla tego rozszerzenia.

Rozszerzenie

Typ serwera "extension" pozwala deweloperom na zdefiniowanie manifestu rozszerzenia w celu pobierania aktualizacji z manifestu pojedynczego rozszerzenia. Wszystkie manifesty kolekcji ostatecznie wskazują na ten plik XML. Wszystkie aktualizacje w tym pliku muszą być zdefiniowane po tagu <updates> na początku pliku. Poniższy przykład to definicja aktualizacji dla Joomla! w wersji 3.9.6:

<updates>
	<update>
		<name>Joomla! 3.9</name>
		<description>Joomla! 3.9 CMS</description>
		<element>joomla</element>
		<type>file</type>
		<version>3.9.6</version>
		<infourl title="Joomla!">https://www.joomla.org/announcements/release-news/5765-joomla-3-9-6-release.html</infourl>
		<downloads>
			<downloadurl type="full" format="zip">https://downloads.joomla.org/cms/joomla3/3-9-6/Joomla_3.9.6-Stable-Update_Package.zip</downloadurl>
			<downloadsource type="full" format="zip">https://github.com/joomla/joomla-cms/releases/download/3.9.6/Joomla_3.9.6-Stable-Update_Package.zip</downloadsource>
			<downloadsource type="full" format="zip">https://update.joomla.org/releases/3.9.6/Joomla_3.9.6-Stable-Update_Package.zip</downloadsource>
		</downloads>
		<tags>
			<tag>stable</tag>
		</tags>
		<sha256>05157273aadd3045564ee44373ea3643b437fa5321d17993a3119b38b04578e2</sha256>
		<sha384>ebd9b0666fbe84e20a420a4bcd6c10d306fc4dee4edbbe8e2133c85f0fb84e59be5a50aa97cb38c068b77f77f6bbc091</sha384>
		<sha512>a4c47644ceeaeec28944e0c74160203cf12037e0ea1439022e95055dfb6716de172667ce6d9164f12bb519d9cfcf1fdc728abea00f853b41debc7d2740f2b711</sha512>
		<maintainer>Joomla! Production Department</maintainer>
		<maintainerurl>https://www.joomla.org</maintainerurl>
		<section>STS</section>
		<targetplatform name="joomla" version="3.[789]" />
		<php_minimum>5.3.10</php_minimum>
</update>
</updates>

W poniższej sekcji opisano elementy pojedynczego elementu aktualizacji.

• name – nazwa rozszerzenia, ta nazwa będzie wyświetlana w kolumnie Nazwa w widoku Menedżera Aktualizacji Rozszerzeń (wymagane)
• description – krótki opis rozszerzenia (opcjonalnie) - jeśli zdecydujesz się na użycie <![CDATA[]]>, podwójne cudzysłowy złamią formatowanie HTML. Używaj pojedynczych cudzysłowów w swoich encjach HTML.
• element – zainstalowana nazwa rozszerzenia (wymagana). W przypadku wtyczek, musi to być taka sama wartość jak wartość atrybutu pluginu dla głównego pliku w manifeście wtyczki. Dla <filename plugin = "pluginname">pluginname.php</filename> wartością elementu powinna być nazwa wtyczki.
• type – typ rozszerzenia (komponent, moduł, plugin, itp.) (wymagane)
• folder – specyficzny dla wtyczek, ten tag opisuje typ aktualizowanej wtyczki (zawartość, system itp.) (wymagany w przypadku wtyczek)

• client – wymagane dla modułów i szablonów od 3.2.0. - identyfikator klienta rozszerzenia, który można znaleźć, zaglądając do tabeli #_extensions. Użyj 0 dla „strony” i 1 dla „administratora”. Ostrzeżenie! Wtyczki i moduły witryny są automatycznie instalowane z klientem 0 (strona), ale będziesz musiał określić klienta w aktualizacji lub domyślnie będzie to 1 (administrator), znaleziona aktualizacja nie zostanie wyświetlona, ponieważ nie będzie pasować do żadnego rozszerzenia.

• • Warning: nazwa tagu <client> dla Joomla! 2.5 to <client_id> dla 1.6 i 1.7. Jeśli używasz <client_id> (zamiast <client>) w witrynie 2.5, zostanie on zignorowany.

• version – wersja wydania (wymagana)
• infourl – adres URL wskazujący użytkownikom informacje o aktualizacji (opcjonalnie) (w CMS 2.5, jeśli jest ustawiony, ten adres URL będzie wyświetlany w widoku aktualizacji)
• downloads – sekcja zawierająca listę wszystkich lokalizacji pobierania
  • downloadurl – adres URL, z którego należy pobrać rozszerzenie; tag <downloadurl> ma dwa wymagane parametry:
    • type – typ pakietu (full lub upgrade)
    • format – format paczki (zip, tar itp.)
  • downloadsource – opcjonalny. Od Joomla 3.8.3. alternatywny adres URL do pobrania rozszerzenia w przypadku niepowodzenia połączenia z <downloadurl>. Dozwolonych jest wiele tagów <downloadsource>. Tag <downloadsource> ma dwa wymagane parametry:
    • type – typ pakietu (pełny lub uaktualnienie)
    • format – format paczki (zip, tar itp.)
  • NB – nie może być nowej linii przed ani po adresie URL; wszystko musi znajdować się w jednej linii, w przeciwnym razie pojawi się błąd podczas łączenia się z serwerem: źle sformułowany po uruchomieniu aktualizacji

• tags – lista tagów związanych z wersją. Joomla! 3.4 i późniejsze używają tego do określenia poziomu stabilności aktualizacji. Prawidłowe tagi to:

• • dev: wersje rozwojowe, bardzo niestabilne i pre-alpha (np. nocne kompilacje)
  • alpha: oprogramowanie o jakości alfa (niezaimplementowane funkcje, błędy krytyczne)
  • beta: oprogramowanie o jakości beta (wszystkie funkcje zaimplementowane, możliwe błędy krytyczne, niemal pewne drobne błędy)
  • rc: wydanie oprogramowania wysokiej jakości, wydanie kandydujące (brak błędów krytycznych, drobne błędy mogą nadal być obecne)
  • stable: wersja nadająca się do użytkowania zgodnie z założeniami autorów, wszystkie inne znaczniki są obecnie ignorowane. Jeśli podasz więcej niż jeden tag zawierający jedno z wyżej wymienionych słów kluczowych, tylko OSTATNI tag będzie brany pod uwagę. Jeśli nie podasz żadnych znaczników, Joomla! założy, że jest to wersja stabilna..
• maintainer – nazwa opiekuna rozszerzenia (podobnie jak w tagu <author> w manifeście) (opcjonalnie)
• maintainerurl – witryna opiekuna rozszerzenia (podobna do tagu <authorUrl> w manifeście) (opcjonalnie)
• section – opcjonalne (nieznane zastosowanie)
• targetplatform – tag definiujący wymagania platformy (od jest również używany do wykrywania zgodności rozszerzeń dla komponentu aktualizacji Joomla ) wymaga następujących elementówː
  • name – nazwa zależności platformy; na dzień dzisiejszy powinna to być TYLKO "joomla"
  • version – wersja Joomla!, którą obsługuje rozszerzenie
  • min_dev_level oraz max_dev_level – atrybuty te zostały dodane w wersji 3.0.1, aby umożliwić wybór platformy docelowej na podstawie poziomu deweloperskiego ("z" w x.y.z). Są opcjonalne. Możesz określić jedną lub obie. W przypadku pominięcia dopasowywane są wszystkie poziomy deweloperskie. Na przykład następujący kod odpowiada wersjom 4.0.0 i 4.0.1. <targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/>
    • Uwaga: jeśli Twoje rozszerzenie jest kompatybilne z Joomla! 2.5 i/lub 3.1, będziesz musiał mieć oddzielne definicje <update> dla każdej wersji ze względu na sposób, w jaki aktualizator sprawdza wersję, jeśli podasz liczbę. Jednak, aby pokazać swoje rozszerzenie na wszystkich wersjach Joomla, które obsługują automatyczne aktualizacje (i tym samym oznaczyć jako kompatybilne z wszystkimi przyszłymi, niewydanymi wersjami Joomla w aktualizacjach Joomla) dodaj <targetplatform name="joomla" version=".*"/>. Jeśli chcesz, aby Twoje rozszerzenie wyświetlało się we wszystkich wersjach , zamiast określać wersję w znaczniku wersji, dodaj<targetplatform name="joomla" version="3.[012345]"/>.Spowoduje to wyświetlenie aktualizacji do wszystkich wersji 3.x od wersji 3.0 do 3.5. Jeśli chcesz dołączyć wersję 3.10, możesz użyć | w ten sposób: <targetplatform name="joomla" version="3.[012345]|10"/>. Jeśli chcesz wyświetlić aktualizacje dla wszystkich wersji 3.8.x i wszystkich wersji 3.10.x możesz użyć<targetplatform name="joomla" version="3.(8|10)"/>
• php_minimum – począwszy od wersji 3.2.2, minimalna obsługiwana wersja PHP może być dostarczana w strumieniu aktualizacji. Jeśli serwer nie spełnia wymagań minimalnych, wyświetlany jest komunikat informujący, że aktualizacja jest dostępna, ale nie można jej zainstalować z powodu nieobsługiwanych wymagań.
• supported_databases – Począwszy od wersji 3.7, minimalna obsługiwana baza danych + sprawdzanie wersji może być dostarczane w strumieniu aktualizacji. Gdy serwer nie spełnia minimalnych wymagań, wyświetlany jest komunikat informujący, że aktualizacja jest dostępna, ale nie można jej zainstalować z powodu nieobsługiwanych wymagań. Uwaga: As of 3.9.12 istnieje również specjalny przypadek dla mariadb, możesz więc ustawić konkretną minimalną wersję również dla niego.
  • Przykład może wyglądać następująco: <supported_databases mysql="5.5.3" mariadb="10.1" postgresql="9.2" mssql="10.50.1600.1" />
• sha256, sha384, sha512 – opcjonalnie. Od wersji Joomla 3.9.0 możesz dodawać sumy kontrolne plików w tych skróconych formatach. Należy pamiętać, że w Joomla 3 jest wyświetlana tylko informacja o aktualizacjach, jeśli suma kontrolna jest nieprawidłowa. To wszystko. Aktualizacja nie kończy się wtedy. W Joomla 4 aktualizacje i instalacje zostaną zatrzymane, jeśli podana suma kontrolna nie będzie zgodna.

Oddzielna definicja <update> będzie wymagana dla każdej wersji twojego rozszerzenia, którą wypuścisz.

Wartości element, type, client_id oraz folder powinny pasować do tych w tabeli #_extensions.

Ważne dla wtyczek: aby wtyczki działały poprawnie, muszą zawierać elementy <folder> i <client>.

Rozwiązywanie problemów

• Skrypt aktualizacji SQL nie jest wykonywany podczas aktualizacji.

Jeśli skrypt aktualizacji SQL (na przykład w folderze sql/updates/mysql) nie jest wykonywany podczas procesu aktualizacji, może to być spowodowane brakiem numeru wersji w tabeli #_schemas dla tego rozszerzenia "przed aktualizacją". Ta wartość jest określana na podstawie nazwy ostatniego skryptu w folderze aktualizacji SQL. Jeśli ta wartość jest pusta, podczas tego cyklu aktualizacji nie będą wykonywane żadne skrypty SQL. Aby upewnić się, że ta wartość jest ustawiona poprawnie, upewnij się, że w tym folderze znajduje się skrypt SQL, którego nazwa jest numerem wersji (na przykład 1.2.3.sql, jeśli wersja to 1.2.3). Plik może być pusty lub zawierać tylko wiersz komentarza SQL. Należy to zrobić w starej wersji - tej sprzed aktualizacji. Alternatywnie, możesz dodać tę wartość do #_schemas za pomocą zapytania SQL.