Commit | Line | Data |
---|---|---|
e3747bbc | 1 | # Apps for WoltLab Suite |
ccff11c1 AE |
2 | |
3 | ## Introduction | |
4 | ||
5 | Apps are among the most powerful components in WoltLab Suite. Unlike plugins | |
6 | that extend an existing functionality and pages, apps have their own frontend | |
7 | with a dedicated namespace, database table prefixes and template locations. | |
8 | ||
9 | However, apps are meant to be a logical (and to some extent physical) separation | |
10 | from other parts of the framework, including other installed apps. They offer | |
11 | an additional layer of isolation and enable you to re-use class and template | |
12 | names that are already in use by the Core itself. | |
13 | ||
14 | If you've come here, thinking about the question if your next package should be | |
15 | an app instead of a regular plugin, the result is almost always: _No._ | |
16 | ||
17 | ## Differences to Plugins | |
18 | ||
19 | Apps do offer a couple of unique features that are not available to plugins and | |
20 | there are valid reasons to use one instead of a plugin, but they also increase | |
21 | both the code and system complexity. There is a performance penalty for each | |
22 | installed app, regardless if it is actively used in a request or not, simplying | |
23 | being there forces the Core to include it in many places, for example, class | |
24 | resolution or even simple tasks such as constructing a link. | |
25 | ||
26 | ### Unique Namespace | |
27 | ||
28 | Each app has its own unique namespace that is entirely separated from the Core | |
29 | and any other installed apps. The namespace is derived from the last part of the | |
30 | package identifier, for example, `com.example.foo` will yield the namespace `foo`. | |
31 | ||
32 | The namespace is always relative to the installation directory of the app, it | |
33 | doesn't matter if the app is installed on `example.com/foo/` or in `example.com/bar/`, | |
34 | the namespace will always resolve to the right directory. | |
35 | ||
36 | This app namespace is also used for ACP templates, frontend templates and files: | |
37 | ||
38 | ```xml | |
39 | <!-- somewhere in the package.xml --> | |
40 | <instructions type="file" application="foo" /> | |
41 | ``` | |
42 | ||
43 | ### Unique Database Table Prefix | |
44 | ||
45 | All database tables make use of a generic prefix that is derived from one of the | |
46 | installed apps, including `wcf` which resolves to the Core itself. Following the | |
47 | aforementioned example, the new prefix `fooN_` will be automatically registered | |
48 | and recognized in any generated statement. | |
49 | ||
50 | Any `DatabaseObject` that uses the app's namespace is automatically assumed to | |
51 | use the app's database prefix. For instance, `foo\data\bar\Bar` is implicitly | |
52 | mapped to the database table `fooN_bar`. | |
53 | ||
54 | The app prefix is recognized in SQL-PIPs and statements that reference one of | |
55 | its database tables are automatically rewritten to use the Core's instance number. | |
56 | ||
57 | ### Separate Domain and Path Configuration | |
58 | ||
59 | Any controller that is provided by a plugin is served from the configured domain | |
60 | and path of the corresponding app, such as plugins for the Core are always | |
61 | served from the Core's directory. Apps are different and use their own domain | |
62 | and/or path to present their content, additionally, this allows the app to re-use | |
63 | a controller name that is already provided by the Core or any other app itself. | |
64 | ||
65 | ## Creating an App | |
66 | ||
9003992d | 67 | !!! danger "This is a non-reversible operation! Once a package has been installed, its type cannot be changed without uninstalling and reinstalling the entire package, an app will always be an app and vice versa." |
ccff11c1 AE |
68 | |
69 | ### `package.xml` | |
70 | ||
71 | The `package.xml` supports two additional elements in the `<packageinformation>` | |
72 | block that are unique to applications. | |
73 | ||
74 | #### `<isapplication>1</isapplication>` | |
75 | ||
76 | This element is responsible to flag a package as an app. | |
77 | ||
78 | #### `<applicationdirectory>example</applicationdirectory>` | |
79 | ||
80 | Sets the suggested name of the application directory when installing it, the | |
81 | path result in `<path-to-the-core>/example/`. If you leave this element out, | |
82 | the app identifier (`com.example.foo -> foo`) will be used instead. | |
83 | ||
84 | ### Minimum Required Files | |
85 | ||
086a42fa | 86 | An example project with the [source code can be found on GitHub]({jinja{ config.repo_url }}tree/{jinja{ config.edit_uri.split("/")[1] }}/snippets/tutorial/basic-app/), |
ccff11c1 | 87 | it includes everything that is required for a basic app. |