From b2915b6585925077ed7ff0fae1caaf0b0a5bc6b9 Mon Sep 17 00:00:00 2001 From: WoltLab GmbH Date: Tue, 16 Aug 2022 11:36:34 +0000 Subject: [PATCH] Deployed a07e516a to 6.0 with MkDocs 1.3.1 and mike 1.1.2 --- .../wsc55/deprecations_removals/index.html | 5 +- 6.0/migration/wsc55/javascript/index.html | 22 +- 6.0/search/search_index.json | 2 +- 6.0/sitemap.xml | 242 +++++++++--------- 6.0/sitemap.xml.gz | Bin 1053 -> 1054 bytes 5 files changed, 147 insertions(+), 124 deletions(-) diff --git a/6.0/migration/wsc55/deprecations_removals/index.html b/6.0/migration/wsc55/deprecations_removals/index.html index 24f9d23b..0f661730 100644 --- a/6.0/migration/wsc55/deprecations_removals/index.html +++ b/6.0/migration/wsc55/deprecations_removals/index.html @@ -3049,6 +3049,9 @@

Functions#

Options#

JavaScript#

+

Database Tables#

Templates#

Template Modifiers#

@@ -3208,7 +3211,7 @@ Last update: - 2022-08-13 + 2022-08-16 diff --git a/6.0/migration/wsc55/javascript/index.html b/6.0/migration/wsc55/javascript/index.html index cf4751ca..bf2645b3 100644 --- a/6.0/migration/wsc55/javascript/index.html +++ b/6.0/migration/wsc55/javascript/index.html @@ -1733,6 +1733,13 @@ Minimum requirements + + +
  • + + Subscribe Button (WCF.User.ObjectWatch.Subscribe) + +
    • @@ -2515,6 +2522,13 @@ Minimum requirements + + +
  • + + Subscribe Button (WCF.User.ObjectWatch.Subscribe) + +
    • @@ -2538,13 +2552,19 @@

    Migrating from WoltLab Suite 5.5 - TypeScript and JavaScript#

    Minimum requirements#

    The ECMAScript target version has been increased to es2019 from es2017.

    +

    Subscribe Button (WCF.User.ObjectWatch.Subscribe)#

    +

    We have replaced the old jQuery-based WCF.User.ObjectWatch.Subscribe with a more modern replacement WoltLabSuite/Core/Ui/User/ObjectWatch.

    +

    The new implementation comes with a ready-to-use template (__userObjectWatchButton) for use within contentInteractionButtons: +

    1
    {include file='__userObjectWatchButton' isSubscribed=$isSubscribed objectType='foo.bar' objectID=$id}
+

    +

    See WoltLab/WCF#4962 for details.

    Last update: - 2022-07-21 + 2022-08-16
    diff --git a/6.0/search/search_index.json b/6.0/search/search_index.json index f12679c4..3a470641 100644 --- a/6.0/search/search_index.json +++ b/6.0/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"WoltLab Suite 6.0 Documentation # Introduction # This documentation explains the basic API functionality and the creation of own packages. It is expected that you are somewhat experienced with PHP , object-oriented programming and MySQL . Head over to the quick start tutorial to learn more. About WoltLab Suite # WoltLab Suite Core as well as most of the other packages are available on GitHub and are licensed under the terms of the GNU Lesser General Public License 2.1 .","title":"WoltLab Suite 6.0 Documentation"},{"location":"#woltlab-suite-60-documentation","text":"","title":"WoltLab Suite 6.0 Documentation"},{"location":"#introduction","text":"This documentation explains the basic API functionality and the creation of own packages. It is expected that you are somewhat experienced with PHP , object-oriented programming and MySQL . Head over to the quick start tutorial to learn more.","title":"Introduction"},{"location":"#about-woltlab-suite","text":"WoltLab Suite Core as well as most of the other packages are available on GitHub and are licensed under the terms of the GNU Lesser General Public License 2.1 .","title":"About WoltLab Suite"},{"location":"getting-started/","text":"Creating a simple package # Setup and Requirements # This guide will help you to create a simple package that provides a simple test page. It is nothing too fancy, but you can use it as the foundation for your next project. There are some requirements you should met before starting: Text editor with syntax highlighting for PHP, Notepad++ is a solid pick *.php and *.tpl should be encoded with ANSI/ASCII *.xml are always encoded with UTF-8, but omit the BOM (byte-order-mark) Use tabs instead of spaces to indent lines It is recommended to set the tab width to 8 spaces, this is used in the entire software and will ease reading the source files An active installation of WoltLab Suite An application to create *.tar archives, e.g. 7-Zip on Windows The package.xml File # We want to create a simple page that will display the sentence \"Hello World\" embedded into the application frame. Create an empty directory in the workspace of your choice to start with. Create a new file called package.xml and insert the code below: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 Simple Package A simple package to demonstrate the package system of WoltLab Suite Core 1.0.0 2019-04-28 Your Name http://www.example.com com.woltlab.wcf There is an entire chapter on the package system that explains what the code above does and how you can adjust it to fit your needs. For now we'll keep it as it is. The PHP Class # The next step is to create the PHP class which will serve our page: Create the directory files in the same directory where package.xml is located Open files and create the directory lib Open lib and create the directory page Within the directory page , please create the file TestPage.class.php Copy and paste the following code into the TestPage.class.php : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 */ class TestPage extends AbstractPage { /** * @var string */ protected $greet = '' ; /** * @inheritDoc */ public function readParameters () { parent :: readParameters (); if ( isset ( $_GET [ 'greet' ])) $this -> greet = $_GET [ 'greet' ]; } /** * @inheritDoc */ public function readData () { parent :: readData (); if ( empty ( $this -> greet )) { $this -> greet = 'World' ; } } /** * @inheritDoc */ public function assignVariables () { parent :: assignVariables (); WCF :: getTPL () -> assign ([ 'greet' => $this -> greet ]); } } The class inherits from wcf\\page\\AbstractPage , the default implementation of pages without form controls. It defines quite a few methods that will be automatically invoked in a specific order, for example readParameters() before readData() and finally assignVariables() to pass arbitrary values to the template. The property $greet is defined as World , but can optionally be populated through a GET variable ( index.php?test/&greet=You would output Hello You! ). This extra code illustrates the separation of data processing that takes place within all sort of pages, where all user-supplied data is read from within a single method. It helps organizing the code, but most of all it enforces a clean class logic that does not start reading user input at random places, including the risk to only escape the input of variable $_GET['foo'] 4 out of 5 times. Reading and processing the data is only half the story, now we need a template to display the actual content for our page. You don't need to specify it yourself, it will be automatically guessed based on your namespace and class name, you can read more about it later . Last but not least, you must not include the closing PHP tag ?> at the end, it can cause PHP to break on whitespaces and is not required at all. The Template # Navigate back to the root directory of your package until you see both the files directory and the package.xml . Now create a directory called templates , open it and create the file test.tpl . 1 2 3 4 5 6 7 { include file = 'header' }
    Hello { $greet } !
    { include file = 'footer' } Templates are a mixture of HTML and Smarty-like template scripting to overcome the static nature of raw HTML. The above code will display the phrase Hello World! in the application frame, just as any other page would render. The included templates header and footer are responsible for the majority of the overall page functionality, but offer a whole lot of customization abilities to influence their behavior and appearance. The Page Definition # The package now contains the PHP class and the matching template, but it is still missing the page definition. Please create the file page.xml in your project's root directory, thus on the same level as the package.xml . 1 2 3 4 5 6 7 8 9 10 wcf\\page\\TestPage Test Page system You can provide a lot more data for a page, including logical nesting and dedicated handler classes for display in menus. Building the Package # If you have followed the above guidelines carefully, your package directory should now look like this: 1 2 3 4 5 6 7 8 \u251c\u2500\u2500 files \u2502 \u2514\u2500\u2500 lib \u2502 \u2514\u2500\u2500 page \u2502 \u2514\u2500\u2500 TestPage.class.php \u251c\u2500\u2500 package.xml \u251c\u2500\u2500 page.xml \u2514\u2500\u2500 templates \u2514\u2500\u2500 test.tpl Both files and templates are archive-based package components, that deploy their payload using tar archives rather than adding the raw files to the package file. Please create the archive files.tar and add the contents of the files/* directory, but not the directory files/ itself. Repeat the same process for the templates directory, but this time with the file name templates.tar . Place both files in the root of your project. Last but not least, create the package archive com.example.test.tar and add all the files listed below. files.tar package.xml page.xml templates.tar The archive's filename can be anything you want, all though it is the general convention to use the package name itself for easier recognition. Installation # Open the Administration Control Panel and navigate to Configuration > Packages > Install Package , click on Upload Package and select the file com.example.test.tar from your disk. Follow the on-screen instructions until it has been successfully installed. Open a new browser tab and navigate to your newly created page. If WoltLab Suite is installed at https://example.com/wsc/ , then the URL should read https://example.com/wsc/index.php?test/ . Congratulations, you have just created your first package! Developer Tools # The developer tools provide an interface to synchronize the data of an installed package with a bare repository on the local disk. You can re-import most PIPs at any time and have the changes applied without crafting a manual update. This process simulates a regular package update with a single PIP only, and resets the cache after the import has been completed. Registering a Project # Projects require the absolute path to the package directory, that is, the directory where it can find the package.xml . It is not required to install an package to register it as a project, but you have to install it in order to work with it. It does not install the package by itself! There is a special button on the project list that allows for a mass-import of projects based on a search path. Each direct child directory of the provided path will be tested and projects created this way will use the identifier extracted from the package.xml . Synchronizing # The install instructions in the package.xml are ignored when offering the PIP imports, the detection works entirely based on the default filename for each PIP. On top of that, only PIPs that implement the interface wcf\\system\\devtools\\pip\\IIdempotentPackageInstallationPlugin are valid for import, as it indicates that importing the PIP multiple times will have no side-effects and that the result is deterministic regardless of the number of times it has been imported. Some built-in PIPs, such as sql or script , do not qualify for this step and remain unavailable at all times. However, you can still craft and perform an actual package update to have these PIPs executed. Appendix # Template Guessing # The class name including the namespace is used to automatically determine the path to the template and its name. The example above used the page class name wcf\\page\\TestPage that is then split into four distinct parts: wcf , the internal abbreviation of WoltLab Suite Core (previously known as WoltLab Community Framework) \\page\\ (ignored) Test , the actual name that is used for both the template and the URL Page (page type, ignored) The fragments 1. and 3. from above are used to construct the path to the template: /templates/test.tpl (the first letter of Test is being converted to lower-case).","title":"Getting Started"},{"location":"getting-started/#creating-a-simple-package","text":"","title":"Creating a simple package"},{"location":"getting-started/#setup-and-requirements","text":"This guide will help you to create a simple package that provides a simple test page. It is nothing too fancy, but you can use it as the foundation for your next project. There are some requirements you should met before starting: Text editor with syntax highlighting for PHP, Notepad++ is a solid pick *.php and *.tpl should be encoded with ANSI/ASCII *.xml are always encoded with UTF-8, but omit the BOM (byte-order-mark) Use tabs instead of spaces to indent lines It is recommended to set the tab width to 8 spaces, this is used in the entire software and will ease reading the source files An active installation of WoltLab Suite An application to create *.tar archives, e.g. 7-Zip on Windows","title":"Setup and Requirements"},{"location":"getting-started/#the-packagexml-file","text":"We want to create a simple page that will display the sentence \"Hello World\" embedded into the application frame. Create an empty directory in the workspace of your choice to start with. Create a new file called package.xml and insert the code below: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 Simple Package A simple package to demonstrate the package system of WoltLab Suite Core 1.0.0 2019-04-28 Your Name http://www.example.com com.woltlab.wcf There is an entire chapter on the package system that explains what the code above does and how you can adjust it to fit your needs. For now we'll keep it as it is.","title":"The package.xml File"},{"location":"getting-started/#the-php-class","text":"The next step is to create the PHP class which will serve our page: Create the directory files in the same directory where package.xml is located Open files and create the directory lib Open lib and create the directory page Within the directory page , please create the file TestPage.class.php Copy and paste the following code into the TestPage.class.php : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 */ class TestPage extends AbstractPage { /** * @var string */ protected $greet = '' ; /** * @inheritDoc */ public function readParameters () { parent :: readParameters (); if ( isset ( $_GET [ 'greet' ])) $this -> greet = $_GET [ 'greet' ]; } /** * @inheritDoc */ public function readData () { parent :: readData (); if ( empty ( $this -> greet )) { $this -> greet = 'World' ; } } /** * @inheritDoc */ public function assignVariables () { parent :: assignVariables (); WCF :: getTPL () -> assign ([ 'greet' => $this -> greet ]); } } The class inherits from wcf\\page\\AbstractPage , the default implementation of pages without form controls. It defines quite a few methods that will be automatically invoked in a specific order, for example readParameters() before readData() and finally assignVariables() to pass arbitrary values to the template. The property $greet is defined as World , but can optionally be populated through a GET variable ( index.php?test/&greet=You would output Hello You! ). This extra code illustrates the separation of data processing that takes place within all sort of pages, where all user-supplied data is read from within a single method. It helps organizing the code, but most of all it enforces a clean class logic that does not start reading user input at random places, including the risk to only escape the input of variable $_GET['foo'] 4 out of 5 times. Reading and processing the data is only half the story, now we need a template to display the actual content for our page. You don't need to specify it yourself, it will be automatically guessed based on your namespace and class name, you can read more about it later . Last but not least, you must not include the closing PHP tag ?> at the end, it can cause PHP to break on whitespaces and is not required at all.","title":"The PHP Class"},{"location":"getting-started/#the-template","text":"Navigate back to the root directory of your package until you see both the files directory and the package.xml . Now create a directory called templates , open it and create the file test.tpl . 1 2 3 4 5 6 7 { include file = 'header' }
    Hello { $greet } !
    { include file = 'footer' } Templates are a mixture of HTML and Smarty-like template scripting to overcome the static nature of raw HTML. The above code will display the phrase Hello World! in the application frame, just as any other page would render. The included templates header and footer are responsible for the majority of the overall page functionality, but offer a whole lot of customization abilities to influence their behavior and appearance.","title":"The Template"},{"location":"getting-started/#the-page-definition","text":"The package now contains the PHP class and the matching template, but it is still missing the page definition. Please create the file page.xml in your project's root directory, thus on the same level as the package.xml . 1 2 3 4 5 6 7 8 9 10 wcf\\page\\TestPage Test Page system You can provide a lot more data for a page, including logical nesting and dedicated handler classes for display in menus.","title":"The Page Definition"},{"location":"getting-started/#building-the-package","text":"If you have followed the above guidelines carefully, your package directory should now look like this: 1 2 3 4 5 6 7 8 \u251c\u2500\u2500 files \u2502 \u2514\u2500\u2500 lib \u2502 \u2514\u2500\u2500 page \u2502 \u2514\u2500\u2500 TestPage.class.php \u251c\u2500\u2500 package.xml \u251c\u2500\u2500 page.xml \u2514\u2500\u2500 templates \u2514\u2500\u2500 test.tpl Both files and templates are archive-based package components, that deploy their payload using tar archives rather than adding the raw files to the package file. Please create the archive files.tar and add the contents of the files/* directory, but not the directory files/ itself. Repeat the same process for the templates directory, but this time with the file name templates.tar . Place both files in the root of your project. Last but not least, create the package archive com.example.test.tar and add all the files listed below. files.tar package.xml page.xml templates.tar The archive's filename can be anything you want, all though it is the general convention to use the package name itself for easier recognition.","title":"Building the Package"},{"location":"getting-started/#installation","text":"Open the Administration Control Panel and navigate to Configuration > Packages > Install Package , click on Upload Package and select the file com.example.test.tar from your disk. Follow the on-screen instructions until it has been successfully installed. Open a new browser tab and navigate to your newly created page. If WoltLab Suite is installed at https://example.com/wsc/ , then the URL should read https://example.com/wsc/index.php?test/ . Congratulations, you have just created your first package!","title":"Installation"},{"location":"getting-started/#developer-tools","text":"The developer tools provide an interface to synchronize the data of an installed package with a bare repository on the local disk. You can re-import most PIPs at any time and have the changes applied without crafting a manual update. This process simulates a regular package update with a single PIP only, and resets the cache after the import has been completed.","title":"Developer Tools"},{"location":"getting-started/#registering-a-project","text":"Projects require the absolute path to the package directory, that is, the directory where it can find the package.xml . It is not required to install an package to register it as a project, but you have to install it in order to work with it. It does not install the package by itself! There is a special button on the project list that allows for a mass-import of projects based on a search path. Each direct child directory of the provided path will be tested and projects created this way will use the identifier extracted from the package.xml .","title":"Registering a Project"},{"location":"getting-started/#synchronizing","text":"The install instructions in the package.xml are ignored when offering the PIP imports, the detection works entirely based on the default filename for each PIP. On top of that, only PIPs that implement the interface wcf\\system\\devtools\\pip\\IIdempotentPackageInstallationPlugin are valid for import, as it indicates that importing the PIP multiple times will have no side-effects and that the result is deterministic regardless of the number of times it has been imported. Some built-in PIPs, such as sql or script , do not qualify for this step and remain unavailable at all times. However, you can still craft and perform an actual package update to have these PIPs executed.","title":"Synchronizing"},{"location":"getting-started/#appendix","text":"","title":"Appendix"},{"location":"getting-started/#template-guessing","text":"The class name including the namespace is used to automatically determine the path to the template and its name. The example above used the page class name wcf\\page\\TestPage that is then split into four distinct parts: wcf , the internal abbreviation of WoltLab Suite Core (previously known as WoltLab Community Framework) \\page\\ (ignored) Test , the actual name that is used for both the template and the URL Page (page type, ignored) The fragments 1. and 3. from above are used to construct the path to the template: /templates/test.tpl (the first letter of Test is being converted to lower-case).","title":"Template Guessing"},{"location":"javascript/code-snippets/","text":"Code Snippets - JavaScript API # This is a list of code snippets that do not fit into any of the other articles and merely describe how to achieve something very specific, rather than explaining the inner workings of a function. ImageViewer # The ImageViewer is available on all frontend pages by default, you can easily add images to the viewer by wrapping the thumbnails with a link with the CSS class jsImageViewer that points to the full version. 1 2 3 < a href = \"http://example.com/full.jpg\" class = \"jsImageViewer\" > < img src = \"http://example.com/thumbnail.jpg\" > ","title":"Code Snippets"},{"location":"javascript/code-snippets/#code-snippets-javascript-api","text":"This is a list of code snippets that do not fit into any of the other articles and merely describe how to achieve something very specific, rather than explaining the inner workings of a function.","title":"Code Snippets - JavaScript API"},{"location":"javascript/code-snippets/#imageviewer","text":"The ImageViewer is available on all frontend pages by default, you can easily add images to the viewer by wrapping the thumbnails with a link with the CSS class jsImageViewer that points to the full version. 1 2 3 < a href = \"http://example.com/full.jpg\" class = \"jsImageViewer\" > < img src = \"http://example.com/thumbnail.jpg\" > ","title":"ImageViewer"},{"location":"javascript/general-usage/","text":"General JavaScript Usage # WoltLab Suite 5.4 introduced support for TypeScript, migrating all existing modules to TypeScript. The JavaScript section of the documentation is not yet updated to account for the changes, possibly explaining concepts that cannot be applied as-is when writing TypeScript. You can learn about basic TypeScript use in WoltLab Suite, such as consuming WoltLab Suite\u2019s types in own packages, within in the TypeScript section . The History of the Legacy API # The WoltLab Suite 3.0 introduced a new API based on AMD-Modules with ES5-JavaScript that was designed with high performance and visible dependencies in mind. This was a fundamental change in comparison to the legacy API that was build many years before while jQuery was still a thing and we had to deal with ancient browsers such as Internet Explorer 9 that felt short in both CSS and JavaScript capabilities. Fast forward a few years, the old API is still around and most important, it is actively being used by some components that have not been rewritten yet. This has been done to preserve the backwards-compatibility and to avoid the significant amount of work that it requires to rewrite a component. The components invoked on page initialization have all been rewritten to use the modern API, but some deferred objects that are invoked later during the page runtime may still use the old API. However, the legacy API is deprecated and you should not rely on it for new components at all. It slowly but steadily gets replaced up until a point where its last bits are finally removed from the code base. Embedding JavaScript inside Templates # The { * do not include `` here, the footer template is the last bit of code! * } { include file = 'footer' } Content Header # There are two different methods to set the content header, one sets only the actual values, but leaves the outer HTML untouched, that is generated by the header template. This is the recommended approach and you should avoid using the alternative method whenever possible. Recommended Approach # 1 2 3 4 5 6 { * This is automatically set using the page data and should not be set manually! * } { capture assign = 'contentTitle' } Custom Content Title { /capture } { capture assign = 'contentDescription' } Optional description that is displayed right after the title. { /capture } { capture assign = 'contentHeaderNavigation' } List of navigation buttons displayed right next to the title. { /capture } Alternative # 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { capture assign = 'contentHeader' }

    Custom Content Title

    Custom Content Description

    { /capture }","title":"Templates"},{"location":"migration/wcf21/templates/#wcf-21x-templates","text":"","title":"WCF 2.1.x - Templates"},{"location":"migration/wcf21/templates/#page-layout","text":"The template structure has been overhauled and it is no longer required nor recommended to include internal templates, such as documentHeader , headInclude or userNotice . Instead use a simple {include file='header'} that now takes care of of the entire application frame. Templates must not include a trailing after including the footer template. The documentHeader , headInclude and userNotice template should no longer be included manually, the same goes with the element, please use {include file='header'} instead. The sidebarOrientation variable for the header template has been removed and no longer works. header.boxHeadline has been unified and now reads header.contentHeader Please see the full example at the end of this page for more information.","title":"Page Layout"},{"location":"migration/wcf21/templates/#sidebars","text":"Sidebars are now dynamically populated by the box system, this requires a small change to unify the markup. Additionally the usage of
    has been deprecated due to browser inconsistencies and bugs and should be replaced with section.box . Previous markup used in WoltLab Community Framework 2.1 and earlier: 1 2 3 4 5 6 7 < fieldset > < legend > < div > The new markup since WoltLab Suite 3.0: 1 2 3 4 5 6 7 < section class = \"box\" > < h2 class = \"boxTitle\" > < div class = \"boxContent\" > ","title":"Sidebars"},{"location":"migration/wcf21/templates/#forms","text":"The input tag for session ids SID_INPUT_TAG has been deprecated and no longer yields any content, it can be safely removed. In previous versions forms have been wrapped in
    \u2026
    which no longer has any effect and should be removed. If you're using the preview feature for WYSIWYG-powered input fields, you need to alter the preview button include instruction: 1 { include file = 'messageFormPreviewButton' previewMessageObjectType = 'com.example.foo.bar' previewMessageObjectID = 0 } The message object id should be non-zero when editing.","title":"Forms"},{"location":"migration/wcf21/templates/#icons","text":"The old .icon- classes have been removed, you are required to use the official .fa- class names from FontAwesome. This does not affect the generic classes .icon (indicates an icon) and .icon (e.g. .icon16 that sets the dimensions), these are still required and have not been deprecated. Before: 1 < span class = \"icon icon16 icon-list\" > Now: 1 < span class = \"icon icon16 fa-list\" >","title":"Icons"},{"location":"migration/wcf21/templates/#changed-icon-names","text":"Quite a few icon names have been renamed, the official wiki lists the new icon names in FontAwesome 4.","title":"Changed Icon Names"},{"location":"migration/wcf21/templates/#changed-classes","text":".dataList has been replaced and should now read
      (same applies to
        ) .framedIconList has been changed into .userAvatarList","title":"Changed Classes"},{"location":"migration/wcf21/templates/#removed-elements-and-classes","text":"