-
Notifications
You must be signed in to change notification settings - Fork 76
Add the "folder structure" chapter and modify the "extension" chapter #370
Changes from 7 commits
566c77d
a9915a6
8cf434a
7bc9f0f
8353374
ad9a563
1e1d577
3166442
9002003
e3ca998
0dfb4a8
7b553cd
005ab39
d9ce714
0bad3a3
c066a7c
9e6acc3
81518cf
ac6ac54
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,58 +1,108 @@ | ||
## Extensions | ||
|
||
Extensions are an essential part of Contao, because they allow you to add extra | ||
functionality. There are more than 1,400 extensions available in the Contao | ||
Extension Repository, which you can browse directly in the back end. | ||
Communication with the repository server is done via SOAP, so you need to enable | ||
the PHP SOAP extension to use the service (if not enabled by default). | ||
functionality. There are more than 1,800 extensions available in the Contao | ||
[Extension Repository][1]. | ||
|
||
Contao 4 is built on top of the Symfony framework and takes advantage of its | ||
functionalities but also of its terminology. In a Symfony project, an extension | ||
is named a bundle. | ||
|
||
### Extension catalog | ||
If a bundle and a Contao extension have the same purpose, they are nevertheless | ||
not developed in the same way and the installation procedure is different for | ||
each of them. | ||
|
||
The "extension catalog" module allows you to browse the extension list and to | ||
install extensions at the push of a button. Use the filter and sorting options | ||
to find a particular extension and click the info icon or extension title to | ||
open the details page and install the module. | ||
> **Warning** Even if a Contao extension can be installed, this does not mean | ||
that it is compatible with Contao 4. The extension you want to use must take | ||
into account the prerequisites of the version 4. | ||
|
||
![](images/extension-list.jpg) | ||
|
||
The details page contains a description of the extension and important | ||
information regarding system requirements, versions and dependencies from other | ||
modules. Click the "Install" button to download and install the extension. | ||
### Installing a Contao extension | ||
|
||
![](images/extension-details.jpg) | ||
With Contao 4.0, an extension can be installed with Composer or manually. | ||
|
||
Contao will automatically download and install the extension and update the | ||
database if necessary. | ||
|
||
![](images/extension-install.jpg) | ||
#### With Composer | ||
|
||
An extension that can be installed via Composer can be found through its main | ||
repository [Packagist][2]. A name of an extension is divided into two parts. | ||
The first part is the name of the project owner and the second the extension | ||
name. For example: `companyName/extensionName`. | ||
|
||
### Extension manager | ||
Dependencies (in our case an extension) are described in a file named | ||
`composer.json` which is located in the root folder of your Contao installation. | ||
|
||
The "extension manager" module allows you to update and uninstall extensions. It | ||
automatically checks for updates and notifies you if a new version is available. | ||
Many extensions also include links to an online manual and/or forum thread where | ||
you can get support. | ||
This is the first step you need to do. Open the `composer.json` file and add the | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The whole chapter can probably be simplified a lot. One should simply run There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thank you, it's easier that way. Modified in e3ca998 |
||
new dependency in the `require` key. | ||
|
||
![](images/extension-manager.jpg) | ||
```json | ||
"require": { | ||
"companyName/extensionName": "~1.0", | ||
}, | ||
``` | ||
|
||
To uninstall an extension, simply click the uninstall icon and follow the | ||
instructions. The extension manager will remove all files and folders and update | ||
the database if necessary. Note that this action cannot be undone and the tables | ||
cannot be restored! | ||
You must also enter the version you want to use. The `~` [operator][3] means you | ||
want the latest version of `1.*`. | ||
|
||
![](images/extension-uninstall.jpg) | ||
Run the command `php composer.phar update companyName/extensionName` in your | ||
command-line interface to start the installation. | ||
|
||
After the installation, you can clear the cache with the following command: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In a Contao 4 standard edition, this is automatically done by Composer (using the scripts defined in your root |
||
`php app/console cache:clear -e=prod`. | ||
|
||
### Manual installation | ||
|
||
In case the PHP SOAP extension is not available on your server, you can also | ||
install Contao extensions manually. Find the respective module in the [extension | ||
list][1] and download the .zip archive of the latest release. Then unzip the | ||
files and copy them to your local or remote Contao directory. Finally, check the | ||
database with the [Contao install tool][2]. | ||
#### Manually | ||
|
||
Find the extension you want to install in the [Extension Repository][1] and | ||
download the .zip archive of the latest release. Then unzip the files and copy | ||
them to the `system/modules` folder. If the extension has public files, you must | ||
generate a [symbolic link][4] with the command `app/console contao:symlinks` in | ||
your command-line interface. Then you must register your extension in | ||
`app/AppKernel.php` so that it can be taken into account by the system (see | ||
below). Finally, check the database with the [Contao install tool][5]. | ||
|
||
|
||
##### AppKernel.php | ||
|
||
Instantiate the `ContaoModuleBundle` class. The first parameter is the name of | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe we can reuse the examples from http://symfony.com/doc/current/cookbook/bundles/best_practices.html#installation-instructions for how to adjust the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's done in 7b553cd |
||
your extension. | ||
|
||
```php | ||
new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()), | ||
``` | ||
|
||
**Example**: | ||
|
||
```php | ||
// app/AppKernel.php | ||
|
||
public function registerBundles() | ||
{ | ||
$bundles = [ | ||
new Symfony\Bundle\FrameworkBundle\FrameworkBundle(), | ||
new Contao\CoreBundle\ContaoCoreBundle(), | ||
new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()), | ||
]; | ||
|
||
// ... | ||
|
||
return $bundles; | ||
} | ||
``` | ||
|
||
After the installation, you can clear the cache with the following command: | ||
`php app/console cache:clear -e=prod`. | ||
|
||
|
||
## Extension catalog | ||
|
||
Prior to Contao 4, it was possible to install an extension automatically from | ||
the back end. This feature is under development and will be offered in a future | ||
release. | ||
|
||
|
||
[1]: https://contao.org/en/extension-list.html | ||
[2]: ../01-installation/installing-contao.md#the-contao-install-tool | ||
[2]: https://packagist.org | ||
[3]: https://getcomposer.org/doc/articles/versions.md#tilde | ||
[4]: ../01-installation/installing-contao.md#symbolic-link | ||
[5]: ../01-installation/installing-contao.md#the-contao-install-tool |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
project owner is usually called vendor
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I kept "project owner" in parentheses because everyone does not necessarily know this term.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Like me for example ;-)