From: WoltLab GmbH Date: Fri, 28 Oct 2022 14:43:54 +0000 (+0000) Subject: Deployed ea6e91cf to 6.0 with MkDocs 1.4.1 and mike 1.1.2 X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=d33c02dbc266143cdb6a205d6db5c6c4f9d4329f;p=GitHub%2FWoltLab%2Fwoltlab.github.io.git Deployed ea6e91cf to 6.0 with MkDocs 1.4.1 and mike 1.1.2 --- diff --git a/6.0/migration/wsc54/php/index.html b/6.0/migration/wsc54/php/index.html index 6513e5dc..caaa3f14 100644 --- a/6.0/migration/wsc54/php/index.html +++ b/6.0/migration/wsc54/php/index.html @@ -3271,9 +3271,9 @@ No interface has to be implemented in this case.

final class ValueDumpListener { - public function __invoke(ValueAvailable $event) + public function __invoke(ValueAvailable $event): void { - var_dump($event->getValue()); + \var_dump($event->getValue()); } } @@ -3424,7 +3424,7 @@ See the dedicated migration guide for deta Last update: - 2022-10-17 + 2022-10-28 diff --git a/6.0/search/search_index.json b/6.0/search/search_index.json index 1ece6a8c..bd158f40 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/components_confirmation/","text":"Confirmation - JavaScript API # The purpose of confirmation dialogs is to prevent misclicks and to inform the user of potential consequences of their action. A confirmation dialog should always ask a concise question that includes a reference to the object the action is performed upon. You can exclude extra information or form elements in confirmation dialogs, but these should be kept as compact as possible. Example # 1 2 3 4 5 6 const result = await confirmationFactory () . custom ( \"Do you want a cookie?\" ) . withoutMessage (); if ( result ) { // User has confirmed the dialog. } Confirmation dialogs are a special type that use the role=\"alertdialog\" attribute and will always include a cancel button. The dialog itself will be limited to a width of 500px, the title can wrap into multiple lines and there will be no \u201cX\u201d button to close the dialog. When to Use # Over the past few years the term \u201cConfirmation Fatique\u201d has emerged that describes the issue of having too many confirmation dialogs even there is no real need for them. A confirmation dialog should only be displayed when the action requires further inputs, for example, a soft delete that requires a reason, or when the action is destructive. Proper Wording # The confirmation question should hint the severity of the action, in particular whether or not it is destructive. Destructive actions are those that cannot be undone and either cause a permanent mutation or that cause data loss. All questions should be phrased in one or two ways depending on the action. Destructive action: Are you sure you want to delete \u201cExample Object\u201d? (German) Wollen Sie \u201eBeispiel-Objekt\u201c wirklich l\u00f6schen? All other actions: Do you want to move \u201cExample Object\u201d to the trash bin? (German) M\u00f6chten Sie \u201eBeispiel-Objekt\u201c in den Papierkorb verschieben? Available Presets # WoltLab Suite 6.0 currently ships with three presets for common confirmation dialogs. All three presets require the title of the related object as part of the question asked to the user. Soft Delete # Soft deleting objects with an optional input field for a reason: 1 2 3 4 5 6 7 8 9 10 11 const askForReason = true ; const { result , reason } = await confirmationFactory (). softDelete ( theObjectName , askForReason ); if ( result ) { console . log ( \"The user has requested a soft delete, the following reason was provided:\" , reason ); } The reason will always be a string, but with a length of zero if the result is false or if no reason was requested. You can simply omit the value if you do not use the reason. 1 2 3 4 5 6 7 8 const askForReason = false ; const { result } = await confirmationFactory (). softDelete ( theObjectName , askForReason ); if ( result ) { console . log ( \"The user has requested a soft delete.\" ); } Restore # Restore a previously soft deleted object: 1 2 3 4 const result = await confirmationFactory (). restore ( theObjectName ); if ( result ) { console . log ( \"The user has requested to restore the object.\" ); } Delete # Permanently delete an object, will inform the user that the action cannot be undone: 1 2 3 4 const result = await confirmationFactory (). delete ( theObjectName ); if ( result ) { console . log ( \"The user has requested to delete the object.\" ); }","title":"Confirmation"},{"location":"javascript/components_confirmation/#confirmation-javascript-api","text":"The purpose of confirmation dialogs is to prevent misclicks and to inform the user of potential consequences of their action. A confirmation dialog should always ask a concise question that includes a reference to the object the action is performed upon. You can exclude extra information or form elements in confirmation dialogs, but these should be kept as compact as possible.","title":"Confirmation - JavaScript API"},{"location":"javascript/components_confirmation/#example","text":"1 2 3 4 5 6 const result = await confirmationFactory () . custom ( \"Do you want a cookie?\" ) . withoutMessage (); if ( result ) { // User has confirmed the dialog. } Confirmation dialogs are a special type that use the role=\"alertdialog\" attribute and will always include a cancel button. The dialog itself will be limited to a width of 500px, the title can wrap into multiple lines and there will be no \u201cX\u201d button to close the dialog.","title":"Example"},{"location":"javascript/components_confirmation/#when-to-use","text":"Over the past few years the term \u201cConfirmation Fatique\u201d has emerged that describes the issue of having too many confirmation dialogs even there is no real need for them. A confirmation dialog should only be displayed when the action requires further inputs, for example, a soft delete that requires a reason, or when the action is destructive.","title":"When to Use"},{"location":"javascript/components_confirmation/#proper-wording","text":"The confirmation question should hint the severity of the action, in particular whether or not it is destructive. Destructive actions are those that cannot be undone and either cause a permanent mutation or that cause data loss. All questions should be phrased in one or two ways depending on the action. Destructive action: Are you sure you want to delete \u201cExample Object\u201d? (German) Wollen Sie \u201eBeispiel-Objekt\u201c wirklich l\u00f6schen? All other actions: Do you want to move \u201cExample Object\u201d to the trash bin? (German) M\u00f6chten Sie \u201eBeispiel-Objekt\u201c in den Papierkorb verschieben?","title":"Proper Wording"},{"location":"javascript/components_confirmation/#available-presets","text":"WoltLab Suite 6.0 currently ships with three presets for common confirmation dialogs. All three presets require the title of the related object as part of the question asked to the user.","title":"Available Presets"},{"location":"javascript/components_confirmation/#soft-delete","text":"Soft deleting objects with an optional input field for a reason: 1 2 3 4 5 6 7 8 9 10 11 const askForReason = true ; const { result , reason } = await confirmationFactory (). softDelete ( theObjectName , askForReason ); if ( result ) { console . log ( \"The user has requested a soft delete, the following reason was provided:\" , reason ); } The reason will always be a string, but with a length of zero if the result is false or if no reason was requested. You can simply omit the value if you do not use the reason. 1 2 3 4 5 6 7 8 const askForReason = false ; const { result } = await confirmationFactory (). softDelete ( theObjectName , askForReason ); if ( result ) { console . log ( \"The user has requested a soft delete.\" ); }","title":"Soft Delete"},{"location":"javascript/components_confirmation/#restore","text":"Restore a previously soft deleted object: 1 2 3 4 const result = await confirmationFactory (). restore ( theObjectName ); if ( result ) { console . log ( \"The user has requested to restore the object.\" ); }","title":"Restore"},{"location":"javascript/components_confirmation/#delete","text":"Permanently delete an object, will inform the user that the action cannot be undone: 1 2 3 4 const result = await confirmationFactory (). delete ( theObjectName ); if ( result ) { console . log ( \"The user has requested to delete the object.\" ); }","title":"Delete"},{"location":"javascript/components_dialog/","text":"Dialogs - JavaScript API # Modal dialogs are a powerful tool to draw the viewer\u2019s attention to an important message, question or form. Dialogs naturally interrupt the workflow and prevent the navigation to other sections by making other elements on the page inert. WoltLab Suite 6.0 ships with four different types of dialogs. Quickstart # There are four different types of dialogs that each fulfill their own specialized role and that provide built-in features to make the development much easier. Please see the following list to make a quick decision of what kind of dialog you need. Is this some kind of error message? Use an alert dialog. Are you asking the user to confirm an action? Use a confirmation dialog . Does the dialog contain form inputs that the user must fill in? Use a prompt dialog. Do you want to present information to the user without requiring any action? Use a dialog without controls. Dialogs Without Controls # Dialogs may contain just an explanation or extra information that should be presented to the viewer without requiring any further interaction. The dialog can be closed via the \u201cX\u201d button or by clicking the modal backdrop. 1 2 const dialog = dialogFactory (). fromHtml ( \"

Hello World

\" ). withoutControls (); dialog . show ( \"Greetings from my dialog\" ); When to Use # The short answer is: Don\u2019t. Dialogs without controls are an anti-pattern because they only contain content that does not require the modal appearance of a dialog. More often than not dialogs are used for this kind of content because they are easy to use without thinking about better ways to present the content. If possible these dialogs should be avoided and the content is presented in a more suitable way, for example, as a flyout or by showing content on an existing or new page. Alerts # Alerts are designed to inform the user of something important that requires no further action by the user. Typical examples for alerts are error messages or warnings. An alert will only provide a single button to acknowledge the dialog and must not contain interactive content. The dialog itself will be limited to a width of 500px, the title can wrap into multiple lines and there will be no \u201cX\u201d button to close the dialog. 1 2 3 4 const dialog = dialogFactory () . fromHtml ( \"

ERROR: Something went wrong!

\" ) . asAlert (); dialog . show ( \"Server Error\" ); You can customize the label of the primary button to better explain what will happen next. This can be useful for alerts that will have a side-effect when closing the dialog, such as redirect to a different page. 1 2 3 4 5 6 7 8 9 10 11 const dialog = dialogFactory () . fromHtml ( \"

Something went wrong, we cannot find your shopping cart.

\" ) . asAlert ({ primary : \"Back to the Store Page\" , }); dialog . addEventListener ( \"primary\" , () => { window . location . href = \"https://example.com/shop/\" ; }); dialog . show ( \"The shopping cart is missing\" ); The primary event is triggered both by clicking on the primary button and by clicks on the modal backdrop. When to Use # Alerts are a special type of dialog that use the role=\"alert\" attribute to signal its importance to assistive tools. Use alerts sparingly when there is no other way to communicate that something did not work as expected. Alerts should not be used for cases where you expect an error to happen. For example, a form control that expectes an input to fall within a restricted range should show an inline error message instead of raising an alert. Confirmation # Confirmation dialogs are supported through a separate factory function that provides a set of presets as well as a generic API. Please see the separate documentation for confirmation dialogs to learn more. Prompts # The most common type of dialogs are prompts that are similar to confirmation dialogs, but without the restrictions and with a regular title. These dialogs can be used universally and provide a submit and cancel button by default. In addition they offer an \u201cextra\u201d button that is placed to the left of the default buttons are can be used to offer a single additional action. A possible use case for an \u201cextra\u201d button would be a dialog that includes an instance of the WYSIWYG editor, the extra button could be used to trigger a message preview. Code Example # 1 2 3 4 5 6 7 8 9 10 11 12 < button id = \"showMyDialog\" > Show the dialog < template id = \"myDialog\" > < dl > < dt > < label for = \"myInput\" > Title < dd > < input type = \"text\" name = \"myInput\" id = \"myInput\" value = \"\" required /> 1 2 3 4 5 6 7 8 9 document . getElementById ( \"showMyDialog\" ) ! . addEventListener ( \"click\" , () => { const dialog = dialogFactory (). fromId ( \"myDialog\" ). asPrompt (); dialog . addEventListener ( \"primary\" , () => { const myInput = document . getElementById ( \"myInput\" ); console . log ( \"Provided title:\" , myInput . value . trim ()); }); }); Custom Buttons # The asPrompt() call permits some level of customization of the form control buttons. Customizing the Primary Button # The primary option is used to change the default label of the primary button. 1 2 3 4 5 dialogFactory () . fromId ( \"myDialog\" ) . asPrompt ({ primary : Language.get ( \"wcf.dialog.button.primary\" ), }); Adding an Extra Button # The extra button has no default label, enabling it requires you to provide a readable name. 1 2 3 4 5 6 7 8 9 10 11 const dialog = dialogFactory () . fromId ( \"myDialog\" ) . asPrompt ({ extra : Language.get ( \"my.extra.button.name\" ), }); dialog . addEventListener ( \"extra\" , () => { // The extra button does nothing on its own. If you want // to close the button after performing an action you\u2019ll // need to call `dialog.close()` yourself. }); Interacting with dialogs # Dialogs are represented by the element that exposes a set of properties and methods to interact with it. Opening and Closing Dialogs # You can open a dialog through the .show() method that expects the title of the dialog as the only argument. Check the .open property to determine if the dialog is currently open. Programmatically closing a dialog is possibly through .close() . Accessing the Content # All contents of a dialog exists within a child element that can be accessed through the content property. 1 2 3 4 5 6 7 // Add some text to the dialog. const p = document . createElement ( \"p\" ); p . textContent = \"Hello World\" ; dialog . content . append ( p ); // Find a text input inside the dialog. const input = dialog . content . querySelector ( 'input[type=\"text\"]' ); Disabling the Submit Button of a Dialog # You can prevent the dialog submission until a condition is met, allowing you to dynamically enable or disable the button at will. 1 2 3 4 5 6 7 dialog . incomplete = false ; const checkbox = dialog . content . querySelector ( 'input[type=\"checkbox\"]' ) ! ; checkbox . addEventListener ( \"change\" , () => { // Block the dialog submission unless the checkbox is checked. dialog . incomplete = ! checkbox . checked ; }); Managing an Instance of a Dialog # The old API for dialogs implicitly kept track of the instance by binding it to the this parameter as seen in calls like UiDialog.open(this); . The new implementation requires to you to keep track of the dialog on your own. 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 class MyComponent { # dialog? : WoltlabCoreDialogElement ; constructor () { const button = document . querySelector ( \".myButton\" ) as HTMLButtonElement ; button . addEventListener ( \"click\" , () => { this . # showGreeting ( button . dataset . name ); }); } # showGreeting ( name : string | undefined ) : void { const dialog = this . # getDialog (); const p = dialog . content . querySelector ( \"p\" ) ! ; if ( name === undefined ) { p . textContent = \"Hello World\" ; } else { p . textContent = `Hello ${ name } ` ; } dialog . show ( \"Greetings!\" ); } # getDialog () : WoltlabCoreDialogElement { if ( this . # dialog === undefined ) { this . # dialog = dialogFactory () . fromHtml ( \"

Hello from MyComponent

\" ) . withoutControls (); } return this . # dialog ; } } Event Access # You can bind event listeners to specialized events to get notified of events and to modify its behavior. afterClose # This event cannot be canceled. Fires when the dialog has closed. 1 2 3 dialog . addEventListener ( \"afterClose\" , () => { // Dialog was closed. }); close # Fires when the dialog is about to close. 1 2 3 4 5 dialog . addEventListener ( \"close\" , ( event ) => { if ( someCondition ) { event . preventDefault (); } }); cancel # Fires only when there is a \u201cCancel\u201d button and the user has either pressed that button or clicked on the modal backdrop. The dialog will close if the event is not canceled. 1 2 3 4 5 dialog . addEventListener ( \"cancel\" , ( event ) => { if ( someCondition ) { event . preventDefault (); } }); extra # This event cannot be canceled. Fires when an extra button is present and the button was clicked by the user. This event does nothing on its own and is supported for dialogs of type \u201cPrompt\u201d only. 1 2 3 dialog . addEventListener ( \"extra\" , () => { // The extra button was clicked. }); primary # This event cannot be canceled. Fires only when there is a primary action button and the user has either pressed that button or submitted the form through keyboard controls. 1 2 3 4 5 6 dialog . addEventListener ( \"primary\" , () => { // The primary action button was clicked or the // form was submitted through keyboard controls. // // The `validate` event has completed successfully. }); validate # Fires only when there is a form and the user has pressed the primary action button or submitted the form through keyboard controls. Canceling this event is interpreted as a form validation failure. 1 2 3 4 5 6 7 8 9 10 const input = document . createElement ( \"input\" ); dialog . content . append ( input ); dialog . addEventListener ( \"validate\" , ( event ) => { if ( input . value . trim () === \"\" ) { event . preventDefault (); // Display an inline error message. } });","title":"Dialog"},{"location":"javascript/components_dialog/#dialogs-javascript-api","text":"Modal dialogs are a powerful tool to draw the viewer\u2019s attention to an important message, question or form. Dialogs naturally interrupt the workflow and prevent the navigation to other sections by making other elements on the page inert. WoltLab Suite 6.0 ships with four different types of dialogs.","title":"Dialogs - JavaScript API"},{"location":"javascript/components_dialog/#quickstart","text":"There are four different types of dialogs that each fulfill their own specialized role and that provide built-in features to make the development much easier. Please see the following list to make a quick decision of what kind of dialog you need. Is this some kind of error message? Use an alert dialog. Are you asking the user to confirm an action? Use a confirmation dialog . Does the dialog contain form inputs that the user must fill in? Use a prompt dialog. Do you want to present information to the user without requiring any action? Use a dialog without controls.","title":"Quickstart"},{"location":"javascript/components_dialog/#dialogs-without-controls","text":"Dialogs may contain just an explanation or extra information that should be presented to the viewer without requiring any further interaction. The dialog can be closed via the \u201cX\u201d button or by clicking the modal backdrop. 1 2 const dialog = dialogFactory (). fromHtml ( \"

Hello World

\" ). withoutControls (); dialog . show ( \"Greetings from my dialog\" );","title":"Dialogs Without Controls"},{"location":"javascript/components_dialog/#when-to-use","text":"The short answer is: Don\u2019t. Dialogs without controls are an anti-pattern because they only contain content that does not require the modal appearance of a dialog. More often than not dialogs are used for this kind of content because they are easy to use without thinking about better ways to present the content. If possible these dialogs should be avoided and the content is presented in a more suitable way, for example, as a flyout or by showing content on an existing or new page.","title":"When to Use"},{"location":"javascript/components_dialog/#alerts","text":"Alerts are designed to inform the user of something important that requires no further action by the user. Typical examples for alerts are error messages or warnings. An alert will only provide a single button to acknowledge the dialog and must not contain interactive content. The dialog itself will be limited to a width of 500px, the title can wrap into multiple lines and there will be no \u201cX\u201d button to close the dialog. 1 2 3 4 const dialog = dialogFactory () . fromHtml ( \"

ERROR: Something went wrong!

\" ) . asAlert (); dialog . show ( \"Server Error\" ); You can customize the label of the primary button to better explain what will happen next. This can be useful for alerts that will have a side-effect when closing the dialog, such as redirect to a different page. 1 2 3 4 5 6 7 8 9 10 11 const dialog = dialogFactory () . fromHtml ( \"

Something went wrong, we cannot find your shopping cart.

\" ) . asAlert ({ primary : \"Back to the Store Page\" , }); dialog . addEventListener ( \"primary\" , () => { window . location . href = \"https://example.com/shop/\" ; }); dialog . show ( \"The shopping cart is missing\" ); The primary event is triggered both by clicking on the primary button and by clicks on the modal backdrop.","title":"Alerts"},{"location":"javascript/components_dialog/#when-to-use_1","text":"Alerts are a special type of dialog that use the role=\"alert\" attribute to signal its importance to assistive tools. Use alerts sparingly when there is no other way to communicate that something did not work as expected. Alerts should not be used for cases where you expect an error to happen. For example, a form control that expectes an input to fall within a restricted range should show an inline error message instead of raising an alert.","title":"When to Use"},{"location":"javascript/components_dialog/#confirmation","text":"Confirmation dialogs are supported through a separate factory function that provides a set of presets as well as a generic API. Please see the separate documentation for confirmation dialogs to learn more.","title":"Confirmation"},{"location":"javascript/components_dialog/#prompts","text":"The most common type of dialogs are prompts that are similar to confirmation dialogs, but without the restrictions and with a regular title. These dialogs can be used universally and provide a submit and cancel button by default. In addition they offer an \u201cextra\u201d button that is placed to the left of the default buttons are can be used to offer a single additional action. A possible use case for an \u201cextra\u201d button would be a dialog that includes an instance of the WYSIWYG editor, the extra button could be used to trigger a message preview.","title":"Prompts"},{"location":"javascript/components_dialog/#code-example","text":"1 2 3 4 5 6 7 8 9 10 11 12 < button id = \"showMyDialog\" > Show the dialog < template id = \"myDialog\" > < dl > < dt > < label for = \"myInput\" > Title < dd > < input type = \"text\" name = \"myInput\" id = \"myInput\" value = \"\" required /> 1 2 3 4 5 6 7 8 9 document . getElementById ( \"showMyDialog\" ) ! . addEventListener ( \"click\" , () => { const dialog = dialogFactory (). fromId ( \"myDialog\" ). asPrompt (); dialog . addEventListener ( \"primary\" , () => { const myInput = document . getElementById ( \"myInput\" ); console . log ( \"Provided title:\" , myInput . value . trim ()); }); });","title":"Code Example"},{"location":"javascript/components_dialog/#custom-buttons","text":"The asPrompt() call permits some level of customization of the form control buttons.","title":"Custom Buttons"},{"location":"javascript/components_dialog/#customizing-the-primary-button","text":"The primary option is used to change the default label of the primary button. 1 2 3 4 5 dialogFactory () . fromId ( \"myDialog\" ) . asPrompt ({ primary : Language.get ( \"wcf.dialog.button.primary\" ), });","title":"Customizing the Primary Button"},{"location":"javascript/components_dialog/#adding-an-extra-button","text":"The extra button has no default label, enabling it requires you to provide a readable name. 1 2 3 4 5 6 7 8 9 10 11 const dialog = dialogFactory () . fromId ( \"myDialog\" ) . asPrompt ({ extra : Language.get ( \"my.extra.button.name\" ), }); dialog . addEventListener ( \"extra\" , () => { // The extra button does nothing on its own. If you want // to close the button after performing an action you\u2019ll // need to call `dialog.close()` yourself. });","title":"Adding an Extra Button"},{"location":"javascript/components_dialog/#interacting-with-dialogs","text":"Dialogs are represented by the element that exposes a set of properties and methods to interact with it.","title":"Interacting with dialogs"},{"location":"javascript/components_dialog/#opening-and-closing-dialogs","text":"You can open a dialog through the .show() method that expects the title of the dialog as the only argument. Check the .open property to determine if the dialog is currently open. Programmatically closing a dialog is possibly through .close() .","title":"Opening and Closing Dialogs"},{"location":"javascript/components_dialog/#accessing-the-content","text":"All contents of a dialog exists within a child element that can be accessed through the content property. 1 2 3 4 5 6 7 // Add some text to the dialog. const p = document . createElement ( \"p\" ); p . textContent = \"Hello World\" ; dialog . content . append ( p ); // Find a text input inside the dialog. const input = dialog . content . querySelector ( 'input[type=\"text\"]' );","title":"Accessing the Content"},{"location":"javascript/components_dialog/#disabling-the-submit-button-of-a-dialog","text":"You can prevent the dialog submission until a condition is met, allowing you to dynamically enable or disable the button at will. 1 2 3 4 5 6 7 dialog . incomplete = false ; const checkbox = dialog . content . querySelector ( 'input[type=\"checkbox\"]' ) ! ; checkbox . addEventListener ( \"change\" , () => { // Block the dialog submission unless the checkbox is checked. dialog . incomplete = ! checkbox . checked ; });","title":"Disabling the Submit Button of a Dialog"},{"location":"javascript/components_dialog/#managing-an-instance-of-a-dialog","text":"The old API for dialogs implicitly kept track of the instance by binding it to the this parameter as seen in calls like UiDialog.open(this); . The new implementation requires to you to keep track of the dialog on your own. 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 class MyComponent { # dialog? : WoltlabCoreDialogElement ; constructor () { const button = document . querySelector ( \".myButton\" ) as HTMLButtonElement ; button . addEventListener ( \"click\" , () => { this . # showGreeting ( button . dataset . name ); }); } # showGreeting ( name : string | undefined ) : void { const dialog = this . # getDialog (); const p = dialog . content . querySelector ( \"p\" ) ! ; if ( name === undefined ) { p . textContent = \"Hello World\" ; } else { p . textContent = `Hello ${ name } ` ; } dialog . show ( \"Greetings!\" ); } # getDialog () : WoltlabCoreDialogElement { if ( this . # dialog === undefined ) { this . # dialog = dialogFactory () . fromHtml ( \"

Hello from MyComponent

\" ) . withoutControls (); } return this . # dialog ; } }","title":"Managing an Instance of a Dialog"},{"location":"javascript/components_dialog/#event-access","text":"You can bind event listeners to specialized events to get notified of events and to modify its behavior.","title":"Event Access"},{"location":"javascript/components_dialog/#afterclose","text":"This event cannot be canceled. Fires when the dialog has closed. 1 2 3 dialog . addEventListener ( \"afterClose\" , () => { // Dialog was closed. });","title":"afterClose"},{"location":"javascript/components_dialog/#close","text":"Fires when the dialog is about to close. 1 2 3 4 5 dialog . addEventListener ( \"close\" , ( event ) => { if ( someCondition ) { event . preventDefault (); } });","title":"close"},{"location":"javascript/components_dialog/#cancel","text":"Fires only when there is a \u201cCancel\u201d button and the user has either pressed that button or clicked on the modal backdrop. The dialog will close if the event is not canceled. 1 2 3 4 5 dialog . addEventListener ( \"cancel\" , ( event ) => { if ( someCondition ) { event . preventDefault (); } });","title":"cancel"},{"location":"javascript/components_dialog/#extra","text":"This event cannot be canceled. Fires when an extra button is present and the button was clicked by the user. This event does nothing on its own and is supported for dialogs of type \u201cPrompt\u201d only. 1 2 3 dialog . addEventListener ( \"extra\" , () => { // The extra button was clicked. });","title":"extra"},{"location":"javascript/components_dialog/#primary","text":"This event cannot be canceled. Fires only when there is a primary action button and the user has either pressed that button or submitted the form through keyboard controls. 1 2 3 4 5 6 dialog . addEventListener ( \"primary\" , () => { // The primary action button was clicked or the // form was submitted through keyboard controls. // // The `validate` event has completed successfully. });","title":"primary"},{"location":"javascript/components_dialog/#validate","text":"Fires only when there is a form and the user has pressed the primary action button or submitted the form through keyboard controls. Canceling this event is interpreted as a form validation failure. 1 2 3 4 5 6 7 8 9 10 const input = document . createElement ( \"input\" ); dialog . content . append ( input ); dialog . addEventListener ( \"validate\" , ( event ) => { if ( input . value . trim () === \"\" ) { event . preventDefault (); // Display an inline error message. } });","title":"validate"},{"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":"