Best practice for extensions' files

Archive Discuss Topics
1
  • Target groups: Integrators & Extension developers

The result of this discussion should be to find one common best practice for paths used to integrate extensions. This makes it easier for every integrator and especially for beginners.

Variants

Currently, there are 2 major options where templates for extensions are located.

Let’s imagine a site package with the extension key “site_demo” and 2 extensions: powermail, news.

Variant 1

Each extension has its own directory:

EXT:site_demo/Resources/Private/Extensions/
	powermail/
		Templates/
			Form/Form.html
			...
		Partials
			Form/Field/Input.html
			...
		Layouts
			...
	news
		Templates/
			News/List.html
			...
		Partials
			Detail/MediaContainer.html
			...
		Layouts
			...
	powermail

Advantages:

  • It is easy to copy & paste the integration from one installation to another because there is just one directory.

Variant 2

The templates, partials and layouts are grouped together.

EXT:site_demo/Resources/Private/
	Templates
		powermail
			Form/Form.html
			...
		news
			News/List.html
			...
	Partials
		powermail
			Form/Field/Input.html
			...
		news
			Detail/MediaContainer.html
			...
	Layouts
		news
			...
		powermail
			...

Advantages:

Not to be discussed

The following paths are not to be discussed yet:

  • Location of templates/partials/layouts of content elements
  • Location of templates/partials/layouts of pages
  • Reusing same partials in multiple extensions, pages & content elements

:heart: Your opinion :wave:

Please share your opinion!

Possible Future

Having one best practice would allow us to auto setup the paths for all plugins. This would mean that if the site package extension is known to TYPO3 (e.g. registering it in the site config, see b13/bolt as an example)

Some background information

I taught TYPO3 extension development in the last semester at FH OÖ and many students had troubles with the various paths during extension development and integration.

It took a long time to understand which paths can be fully changed (EXT:site_demo/Resources/Private/Extension/news) and which parts need to stay the same (Templates/News/List.html).

For version 10

With the feature Site settings as TypoScript constants and in TSconfig any configuration can be defined in the site settings

settings:
  paths:
    templates: EXT:site_extension/Resources/Private/

Extensions as EXT:news just need to be shipped with a code like this

plugin.tx_news.view {
	templateRootPaths.2 = {$settings.paths.templates}Extension/news/Templates/
	partialRootPaths.2 = {$settings.paths.templates}Extension/news/Partials/
	layoutRootPaths.2 = {$settings.paths.templates}Extension/news/Layouts/
}
2

Variant 1 seems the better option to me.

3

V1 please the possibility to have an consistent copy makes live so much easier.

The main reason for V2 is that it does more fit the patternlab approach. But copying is more sophisticated as we do not follow the „subpackage“ architecture.

4

Variant 1.
And I’ll reach the 20 chars minimum.

5

Thanks for bringing this up! I never thought really about using an other variant than 2 but your proposed variant 1 seems to be much easier.
I will start to integrate Benji’s Sitepackagebuilder to get.typo3.org on the next team sprint on August the 15th so it’s the right moment to change to a new variant.
Also for the bootstrap_package it will be possible to change to a new variant with the next major release but this I have to discuss with Benji ofc.

6

V1!
Copy the extension directory / remove unused files / ready :slight_smile:
And after an extension update you can compare (with your IDE) your directory to the extension directory to find changed/new files.

7

V1 - better overview. Easier to add/remove extenstiont(-templates)

8

v1 in my opinion - all related files under one hierarchy

9

For me, it’s v1, too.

10

:+1: Variant 1 is more convenient.

11

Variant 1.

  • the ‘extension-group’ is far stronger than the ‘what-kind-of-file-group’
  • you can see directly, which extensions have individual files
12

Thanks for bringing this up.

We settled for variant 1 in our team as this easens cloning and refactoring a lot.

It also helps with the scope (work on all private templates of one extension, not all partials of all extensions… or all layouts of all extensions).

13

Variant 1. It seems the most portable.

14

variant 1.

While changing Templates/Partials/Layouts, you are focussed on one extension. So you have one folder with its three subfolders.

Imagine an instance with many extensions and variant 2: you would have many (closed) folders below Templates, Partials and Layouts. Work would not be focussed on the necessary folders

15

Variant 1 Portability an maintainability for the win!

16

So I prefer variant 1, I have no problem working with variant 2 as it is logical too. You only should avoid mixing both styles.

the pathes in variant 2 are shorter than in variant 1:

EXT:site_demo/Resources/Private/Extensions/powermail/Templates/Form/Form.html
EXT:site_demo/Resources/Private/Templates/powermail/Form/Form.html

and you still can use the constants with variant 2:

plugin.tx_news.view {
	templateRootPaths.2 = {$settings.paths.templates}Templates/news/
	partialRootPaths.2 = {$settings.paths.templates}Partials/news/
    layoutRootPaths.2 = {$settings.paths.templates}Layouts/news/
}

one point for variant 1: you can use the same structure for additional files, which are stored in the site-extension and which are used only in combination with an extension:

EXT:site_demo/
    Configuration/
        Extensions/
            news/
                Typoscript/
                    constants.typoscript
                    setup.typoscript
   Resources/
       Public/
           Extensions/
               news/
                   JavaScript/
                       addendum.js
                   CSS/
                       addendum.css

(I know that you can use the extension name as a part of the name of one single file, this is meant as an example how to reuse the same structure in other parts of a site extension)

17

V1. But not because it is easier to “copy & paste the integration from one installation to another” since that’s not what happens I hope. I’d rather rollout a second instance based on the same repository.

I prefer V1 to V2 because it would be easier to remove all templates belonging to a single extension if it gets removed from the installation.

18

Variant 1 is the more practical way of working. Variant 2 seems to be more consistent with other folders within the Private folder (like translations etc). No strong preference for one of both TBH although I totally agree on having a best practice for this!

19

Variant 1 makes more sense and is cleaner.

20

Variant 1. We were using variations of Variant 1 and 2 since TYPO3 7.6, and Variant 1 emerged in our Team as the more flexible and concise approach. As well, it makes the single-responisibility approach much clearer and easier to follow. Variant 1 had as well fewer side effects, and exceptions are much easier to follow and document.