diff --git a/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst b/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst index d6524ed3ba..00113450bf 100644 --- a/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst +++ b/Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst @@ -116,7 +116,7 @@ a multi-site installation and want to alter the appearance of content elements in the wizard or remove certain content elements this can be done via :ref:` page TSconfig `. This is commonly done on a per site basis so you can use the :ref:`Site set page TSconfig provider ` -in your :ref:`site package `. +in your :ref:`site package `. You can use the settings of :ref:`newContentElement.wizardItems `. diff --git a/Documentation/ApiOverview/ContentElements/Index.rst b/Documentation/ApiOverview/ContentElements/Index.rst index 2c09588e08..3dc81f4cb3 100644 --- a/Documentation/ApiOverview/ContentElements/Index.rst +++ b/Documentation/ApiOverview/ContentElements/Index.rst @@ -104,7 +104,7 @@ Or it can have a custom type supplied by an extension such as `carousel` provided by the :composer:`bk2k/bootstrap-package` extension. You can :ref:`add custom content elements ` -to your extension or :ref:`site package `. +to your extension or :ref:`site package `. It is also possible to use an extension such as :composer:`contentblocks/content-blocks`, :composer:`mask/mask`, or :composer:`t3/dce` to add custom content elements to diff --git a/Documentation/ApiOverview/Fluid/Introduction.rst b/Documentation/ApiOverview/Fluid/Introduction.rst index d0c53888f4..cc66eb0454 100644 --- a/Documentation/ApiOverview/Fluid/Introduction.rst +++ b/Documentation/ApiOverview/Fluid/Introduction.rst @@ -207,7 +207,7 @@ import can be done in the template or the partial. Example: Using Fluid to create a theme ====================================== -This example was taken from the `example extension `__ +This example was taken from the `example extension `__ for :ref:`t3sitepackage:start` and reduced to a very basic example. The site package tutorial walks you through the creation of a site package diff --git a/Documentation/ExtensionArchitecture/HowTo/ExtendExtbaseModel/Index.rst b/Documentation/ExtensionArchitecture/HowTo/ExtendExtbaseModel/Index.rst index 1f8d97247f..68e9f775d5 100644 --- a/Documentation/ExtensionArchitecture/HowTo/ExtendExtbaseModel/Index.rst +++ b/Documentation/ExtensionArchitecture/HowTo/ExtendExtbaseModel/Index.rst @@ -33,7 +33,7 @@ Follow these steps: to the extension's documentation on how to display additional fields. #. :ref:`Extend the original model ` - in your custom extension or :ref:`sitepackage `. + in your custom extension or :ref:`sitepackage `. #. :ref:`Register your extended model ` with the according database table in diff --git a/Documentation/ExtensionArchitecture/Index.rst b/Documentation/ExtensionArchitecture/Index.rst index 6257d00455..a595213ee9 100644 --- a/Documentation/ExtensionArchitecture/Index.rst +++ b/Documentation/ExtensionArchitecture/Index.rst @@ -30,6 +30,11 @@ Extension development extensions and sitepackages that were automatically generated or that you downloaded as an example. + .. card:: :ref:`Site package ` + + A site package is a custom TYPO3 extension that contains files regarding the + theme of a site. + .. card:: :ref:`Howto ` @@ -57,13 +62,14 @@ Extension development Contains tutorials on extension development in TYPO3. -.. toctree:: - :hidden: - :titlesonly: - - Concepts/Index - FileStructure/Index - HowTo/Index - Extbase/Index - BestPractises/Index - Tutorials/Index +.. toctree:: + :hidden: + :titlesonly: + + Concepts/Index + FileStructure/Index + SitePackage/Index + HowTo/Index + Extbase/Index + BestPractises/Index + Tutorials/Index diff --git a/Documentation/ExtensionArchitecture/SitePackage/Index.rst b/Documentation/ExtensionArchitecture/SitePackage/Index.rst new file mode 100644 index 0000000000..d54f291dad --- /dev/null +++ b/Documentation/ExtensionArchitecture/SitePackage/Index.rst @@ -0,0 +1,44 @@ +.. include:: /Includes.rst.txt +.. _site-package: + +============ +Site package +============ + +A site package is a custom TYPO3 extension that contains files regarding the +theme of a site. + +.. toctree:: + :caption: Subpages + :glob: + :titlesonly: + + * + +.. contents:: + :caption: Table of content + +.. _site-package-tutorial: + +Site package tutorial +===================== + +The :ref:`site package tutorial ` teaches you step by step +how to create a custom site package from scratch. You can download the +example site package created in this tutorial from GitHub and try it out: +https://github.com/TYPO3-Documentation/site_package/tree/main + +.. _extension-sitepackage-builder: + +Site package builder +==================== + +You can use the https://www.sitepackagebuilder.com/ to generate a site package +for you. This is a quick way to generate a custom site package based on +:composer:`typo3/cms-fluid-styled-content` or :composer:`bk2k/bootstrap-package`. + +There are however some down sides: + +* At the time of writing it is impossible to create a site package for TYPO3 v13. +* A large number of unnecessary, mostly empty files are being generated. +* Depending on your prior knowledge you use code that you might not fully understand. diff --git a/Documentation/ExtensionArchitecture/SitePackage/Introduction.rst b/Documentation/ExtensionArchitecture/SitePackage/Introduction.rst new file mode 100644 index 0000000000..002affcd7f --- /dev/null +++ b/Documentation/ExtensionArchitecture/SitePackage/Introduction.rst @@ -0,0 +1,108 @@ +:navigation-title: Introduction +.. include:: /Includes.rst.txt +.. _site-package-introduction: + +===================================== +Introduction into using site packages +===================================== + +.. _site-package-benefits: + +Site package benefits +===================== + +Developing a website can be approached in different ways. Standard +websites usually consist of HTML documents which contain text and reference +image files, video files, styles, etc. Because it is an enterprise content +management system, TYPO3 features a clean separation between design, content and +functionality and allows developers/integrators to add simple or +sophisticated functionality easily. + +.. _site-package-encapsulation: + +Encapsulation +------------- + +Using extensions is a powerful way to get the most out of TYPO3. Extensions +can be installed, uninstalled and replaced. They can extend the core TYPO3 +system with further functions and features. An extension typically +consists of PHP files, and can also contain design templates (HTML, +CSS, JavaScript files, etc.) and global configuration settings. The visual +appearance of a website does not necessarily require any PHP code. However, the +site package extension described in this tutorial contains exactly two PHP files +(plus a handful of HTML/CSS and configuration files) and is an *extension* to +TYPO3. The PHP code can be copied from this tutorial if the reader does not +have any programming knowledge. + +.. _site-package-version-controll: + +Version control +--------------- + +In building the site package as an extension, all relevant files are stored in +one place and changes can easily be tracked in a version control system +such as Git. The site package approach is not the only way of creating TYPO3 +websites but it is flexible and professional and not overly complicated. + +.. _site-package-di: + +Dependency management +--------------------- + +TYPO3 extensions allow dependencies to other extensions and/or the TYPO3 version +to be defined. This is called "Dependency Management" and makes deployment easy +and fail-safe. Most TYPO3 sites are dependent on a number of extensions. Some +examples are "News" or "Powermail". A site package extension which contains +global configuration settings for these extensions will define the dependencies +for you. When the site package extension is installed in an +empty TYPO3 instance, all dependent extensions are automatically downloaded from +the `TYPO3 Extension Repository `__ and installed. + +.. _site-package-separation: + +Clean separation from the userspace +----------------------------------- + +In a TYPO3 installation that doesn't use extensions, template files are often +stored in the :file:`fileadmin/` directory. Files in +this directory are indexed by TYPO3's :ref:`File Abstraction Layer (FAL) ` resulting in +possibly irrelevant records in the database. To avoid this the :file:`fileadmin/` +area should be seen as a "userspace" which is only available for editors to +use. Even if access permissions restrict editors from accessing or manipulating +files in :file:`fileadmin/`, site configuration components should +still not be stored in the userspace. + +.. _site-package-security: + +Security +-------- + +Files in :file:`fileadmin/` are typically meant to be publicly accessible by +convention. To avoid disclosing sensitive system information (see the +:ref:`TYPO3 Security Guide ` for further details), +configuration files should not be stored in :file:`fileadmin/`. + +.. _site-package-deployment: + +Deployment +---------- + +TYPO3 follows the *convention over configuration* +paradigm. If files and directories in the site-package +extension use the naming convention, they are loaded automatically as +soon as the extension is installed/activated. This means the +extension can be easily deployed using Composer. +Deployment can be automated by system administrators. + +.. _site-package-distributable: + +Distributable +------------- + +By virtue of the motto "TYPO3 inspires people to share!", the site package +extension can be shared with the community via the official `TYPO3 +Extension Repository `__ and/or in a publicly +accessible version control system such as `GitHub `__. + +Last, but not least, configuration settings in the site package can +be overwritten using TypoScript setup and constants. diff --git a/Documentation/ExtensionArchitecture/Tutorials/Kickstart/Index.rst b/Documentation/ExtensionArchitecture/Tutorials/Kickstart/Index.rst index ac2f2a37c4..9064f8e61d 100644 --- a/Documentation/ExtensionArchitecture/Tutorials/Kickstart/Index.rst +++ b/Documentation/ExtensionArchitecture/Tutorials/Kickstart/Index.rst @@ -7,7 +7,7 @@ .. _extension-kickstart: ====================== -Kickstart an Extension +Kickstart an extension ====================== There are different options to kickstart an extension. Here are some @@ -22,31 +22,39 @@ tutorials for common options: .. card:: Create an extension from scratch - * Create a directory with the extension name - * Create the :ref:`files-composer-json` file - * Create the :ref:`ext_emconf-php` file for legacy installations and extensions to be uploaded to TER + * Create a directory with the extension name + * Create the :ref:`files-composer-json` file + * Create the :ref:`ext_emconf-php` file for legacy installations and extensions to be uploaded to TER + + .. card:: :ref:`Use b13/make to create an extension ` + + Install :composer:`b13/make` as dev dependency and use it to quickly + create a new extension. It can also support you in creating console + commands, backend controllers, middlewares, and event handlers. It + creates no unnecessary files as opposed to some of the other automatic + extension generators. .. card:: :ref:`Kickstart a TYPO3 extension with "Make" ` - "Make" can be used to quickly create an extension with a few - basic commands on the console. "Make" can also be used to - kickstart functionality like console command (CLI), backend - controllers and event listeners. It does not offer to kickstart - a sitepackage or an Extbase extension. + "Make" can be used to quickly create an extension with a few + basic commands on the console. "Make" can also be used to + kickstart functionality like console command (CLI), backend + controllers and event listeners. It does not offer to kickstart + a site package or an Extbase extension. - .. card:: :ref:`Sitepackage Builder ` + .. card:: :ref:`Site package builder ` - The `Sitepackage Builder `__ - can be used to conveniently create an extension containing the - sitepackage (theme) of a site. It can also be used to kickstart - an arbitrary extension by removing unneeded files. + The `Site package builder `__ + can be used to conveniently create an extension containing the + site package (theme) of a site. It can also be used to kickstart + an arbitrary extension by removing unneeded files. .. card:: :doc:`Extension Builder ` - The Extension Builder helps you to develop a TYPO3 extension - based on the domain-driven MVC framework :ref:`Extbase ` - and the templating engine :ref:`Fluid `. - + The Extension Builder, :composer:`friendsoftypo3/extension-builder` + helps you to develop a TYPO3 extension + based on the domain-driven MVC framework :ref:`Extbase ` + and the templating engine :ref:`Fluid `. .. toctree:: :titlesonly: diff --git a/Documentation/ExtensionArchitecture/Tutorials/Kickstart/SitepackageBuilder/Index.rst b/Documentation/ExtensionArchitecture/Tutorials/Kickstart/SitepackageBuilder/Index.rst deleted file mode 100644 index 2d56ff9b28..0000000000 --- a/Documentation/ExtensionArchitecture/Tutorials/Kickstart/SitepackageBuilder/Index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: - Extension Kickstart; Sitepackage Builder -.. _extension-sitepackage-builder: - -=================== -Sitepackage Builder -=================== - -The main incentive of the `Sitepackage Builder `__ -is a quick and easy way to create a new sitepackage, what would be called -"theme" in other CMS, for your project. See the -:ref:`Sitepackage Tutorial ` for details on sitepackages.