Skip to content

Commit 9cb60c2

Browse files
csabareanucsabareanu
authored
[FEATURE] Create a Site Set and Configure a Backend Layout With Two Columns (#29)
1 parent 392c01e commit 9cb60c2

File tree

7 files changed

+604
-0
lines changed

7 files changed

+604
-0
lines changed

‎Documentation/10GettingStarted/20BasicConfiguration/40UsingSiteSets/CreateASiteSet.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Create a Site Set with Editable Settings and Custom CSS
2+
3+
<!-- #TYPO3v13 #Beginner #Backend #Configuration @csabareanu -->
4+
5+
TYPO3's Site Sets are reusable packages of site configuration that streamline multi-site management. It replaces older methods and allows you to bundle and apply settings across multiple sites or projects.
6+
7+
## Learning objective
8+
9+
In this guide, you will build a practical, working site set named `my-vendor/base` inside your site package (`EXT:sitepackage`). The site set will:
10+
11+
* Add a default meta description and site contact info (editable in backend)
12+
* Add a simple backend configuration
13+
* Render them in a simple Fluid template
14+
* Load a custom CSS file to style the title
15+
16+
## Prerequisites
17+
18+
### Tools and technology
19+
20+
* A computer with a local TYPO3 installation and a site package extension as described in [Create a Site Package](CreateASitePackage.md).
21+
* An IDE or plain text editor.
22+
23+
### Knowledge and skills
24+
25+
* {Conceptual knowledge}
26+
* {Prior learning}
27+
28+
## Create the Site Set folder and manifest
29+
30+
Every site set is defined inside a manifest that defines its name and dependencies.
31+
32+
1. Inside your extension, create a folder called `base` inside of your extension's site sets folder: `EXT:sitepackage/Configuration/Sets`
33+
2. Inside the `base` folder, create a plain text file called `config.yaml`.
34+
3. Copy the following YAML into the `config.yaml` file:
35+
36+
``` yaml
37+
name: 'my-vendor/base'
38+
label: 'Base Site Set'
39+
dependencies: []
40+
optionalDependencies: []
41+
hidden: false
42+
```
43+
44+
> [!TIP]
45+
> The meaning of the configuration properties is explained in the [Site Set Definition](https://docs.typo3.org/permalink/t3coreapi:site-sets-definition) section of the TYPO3 documentation.
46+
47+
4. Save the file.
48+
49+
## Add editable site settings
50+
51+
We will now define custom site settings. These can be edited and customized for each site in the *Sites* module in the TYPO3 backend.
52+
53+
1. Inside the `base` folder, create a file called `settings.yaml`. This file will contain the custom setting properties.
54+
2. Copy the following YAML into the `settings.yaml` file:
55+
56+
``` yaml
57+
settings:
58+
site:
59+
meta:
60+
description: 'Default meta description from settings.yaml'
61+
contact:
62+
email: '[email protected]'
63+
```
64+
65+
> [!TIP]
66+
> Read more about [Custom Site Settings](https://docs.typo3.org/permalink/t3coreapi:sitehandling-settings) in the TYPO3 documentation.
67+
68+
3. Save the file.
69+
4. Inside the `base` folder, create another file, this time called `settings.definitions.yaml`. This file defines how the custom settings in the `settings.yaml` file should be displayed in the backend.
70+
5. Copy the following YAML into the `settings.definitions.yaml` file:
71+
72+
``` yaml
73+
settings:
74+
site.meta.description:
75+
type: string
76+
label: 'Base Settings: Meta Description'
77+
default: 'Default meta description from definitions'
78+
site.contact.email:
79+
type: string
80+
label: 'Base Settings: Contact Email'
81+
default: '[email protected]'
82+
```
83+
84+
> [!TIP]
85+
> Read more about [Site Settings Definitions](https://docs.typo3.org/permalink/t3coreapi:site-settings-definition) in the TYPO3 documentation.
86+
87+
6. Save the file.
88+
89+
## Add TypoScript for page rendering
90+
91+
Site sets can also contain TypoScript configurations. In this case we will define page rendering and include a CSS file.
92+
93+
1. Inside the `base` folder, create a file called `setup.typoscript`.
94+
2. Copy the following TypoScript into the `setup.typoscript` file:
95+
96+
``` TypoScript
97+
page = PAGE
98+
page.10 = FLUIDTEMPLATE
99+
page.10 {
100+
templateName = Default
101+
templateRootPaths.10 = EXT:sitepackage/Resources/Private/Templates/
102+
partialRootPaths.10 = EXT:sitepackage/Resources/Private/Partials/
103+
layoutRootPaths.10 = EXT:sitepackage/Resources/Private/Layouts/
104+
105+
dataProcessing {
106+
10 = TYPO3\CMS\Frontend\DataProcessing\SiteProcessor
107+
}
108+
}
109+
110+
# Include custom CSS
111+
page.includeCSS.base = EXT:sitepackage/Resources/Public/Css/base.css
112+
```
113+
114+
3. Save the file.
115+
116+
> [!TIP]
117+
> Read more about [TypoScript](https://docs.typo3.org/permalink/t3coreapi:typoscript) in the TYPO3 documentation.
118+
119+
## Add backend configuration
120+
121+
Site sets can also reconfigure the TYPO3 backend. In this case we will change the header of the *Common* section of the [New Content Element Wizard](https://docs.typo3.org/permalink/t3coreapi:content-element-wizard) by modifying the [Page TSConfig configuration options](https://docs.typo3.org/permalink/t3tsref:pagetoplevelobjects).
122+
123+
1. Inside the `base` folder, create a file called `page.tsconfig`.
124+
2. Copy the following TypoScript into the `page.tsconfig` file:
125+
126+
``` TypoScript
127+
mod.wizards.newContentElement.wizardItems.common.header = Common Elements (Site Set active)
128+
```
129+
130+
3. Save the file.
131+
132+
## Add a CSS file
133+
134+
Site sets can also include frontend resources, like images and CSS files. Previously, we defined TypoScript that included a CSS file. Now we will create this file inside the site package's *Resources* folder.
135+
136+
1. Inside your site package extension, create these three folders inside each other: `Resources/Public/Css`. (Don't worry if the folders already exist.)
137+
2. Inside the `Css` folder, create a plain text file called `base.css`.
138+
3. Copy the following CSS into the `base.css` file:
139+
140+
``` css
141+
/* Base Site Set Styles */
142+
h1 {
143+
color: darkred;
144+
font-weight: 700;
145+
}
146+
```
147+
148+
4. Save the file.
149+
150+
## Create a simple Fluid template to test the settings
151+
152+
Site sets can also include Fluid templates. In this case we will create a simple template that displays the custom site settings we have defined. This is thanks to the `SiteProcessor` we defined in our TypoScript. It allows us to access the settings at `site.settings` in the fluid template.
153+
154+
1. Inside the site package extension, create the folders `Resources/Private/Templates/Default` inside each other. (Don't worry if the folders already exist.)
155+
2. Inside the `Default` folder, create an HTML file called `Default.html`.
156+
3. Copy the following HTML into the `Default.html` file:
157+
158+
```
159+
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers">
160+
<body>
161+
<h1>Site Settings Test</h1>
162+
163+
<p><strong>Meta Description:</strong> {site.settings.site.meta.description}</p>
164+
<p><strong>Contact Email:</strong> {site.settings.site.contact.email}</p>
165+
166+
</body>
167+
</html>
168+
```
169+
170+
4. Save the file.
171+
172+
> [!TIP]
173+
> Read more about [Fluid](https://docs.typo3.org/permalink/t3coreapi:fluid) and the [SiteProcessor](https://docs.typo3.org/permalink/t3tsref:siteprocessor) in the TYPO3 documentation.
174+
175+
## Register the Site Set in your site configuration
176+
177+
1. Open your site configuration file. It is located in `config/sites/<your-site>/config.yaml`, where `<your-site>` is your site’s identifier.
178+
2. Add the following line to the `dependencies` section:
179+
180+
``` yaml
181+
dependencies:
182+
- my-vendor/base
183+
```
184+
185+
3. Save the file.
186+
187+
## Clear caches and verify
188+
189+
1. Clear caches as described in [Clearing the Frontend Cache in the TYPO3 Backend](ClearingFrontendCacheInTypo3Backend.md).
190+
2. Open **Backend → Site → Settings** module. You’ll see your *Base Settings: Meta Description* and *Contact Email* fields.
191+
3. Change the value of the fields.
192+
4. Save the settings.
193+
5. Visit your site’s frontend. You should see.
194+
195+
```
196+
Site Settings Test
197+
Meta Description: (your value from step 3)
198+
Contact Email: (your value from step 3)
199+
```
200+
201+
6. Confirm that the H1 title appears in *dark red*. This confirms that the CSS file is loaded.
202+
7. Go back to the TYPO3 backend.
203+
8. Create a new content element to bring up the New Content Element Wizard. Check the wizard’s Common section and confirm that the title has changed to "Common Elements (Site Set active)." This confirms that the Page TSConfig configuration is loaded.
204+
205+
![A screenshot of TYPO3’s New Content Element Wizard with the Common Elements (Site Set active) section selected. Content element icons are visible: Header Only, Regular Text Element, Text & Images, Images Only, and Text & Media, each with icons and brief descriptions.](Images/implementSiteSets/NewContentElementWizardChangedSectionTitle.png)
206+
207+
## Summary
208+
209+
You now have a complete Site Set that provides:
210+
211+
* Editable custom site settings (in **Backend → Sites → Settings**)
212+
* Custom TypoScript that loads a custom Fluid template and CSS file.
213+
* A working Fluid template that displays site settings.
214+
* Automatically included CSS styling.
215+
216+
This Site Set can now be reused across any project — just add `- my-vendor/base` to the `dependencies:` section of another site’s `config.yaml`.
217+
218+
Next steps
219+
220+
Now that you have created your site set, you might like to:
221+
222+
* Explore the [Site Set Reference](https://docs.typo3.org/permalink/t3coreapi:site-sets) to learn more about all the available options.
223+
* [Include CSS through the Fluid Template](AddCSSAndJavaScriptToAFluidTemplate.md) instead of through TypoScript.
224+
225+
## Resources
226+
227+
* [Site Sets Reference](https://docs.typo3.org/permalink/t3coreapi:site-sets)
228+
* [Custom Site Settings](https://docs.typo3.org/permalink/t3coreapi:sitehandling-settings)
229+
* [Site Settings Definitions](https://docs.typo3.org/permalink/t3coreapi:site-settings-definition)
230+
* [TypoScript](https://docs.typo3.org/permalink/t3coreapi:typoscript)
231+
* [Fluid](https://docs.typo3.org/permalink/t3coreapi:fluid)
232+
* [SiteProcessor](https://docs.typo3.org/permalink/t3tsref:siteprocessor)

‎Documentation/10GettingStarted/20BasicConfiguration/40UsingSiteSets/Images/ImplementSiteSets/NewContentElementWizardChangedSectionTitle.png‎

27.2 KB
Loading

‎Documentation/20BuildingWebsites/10ContentManagement/30ConfigureTheBackendLayout/ConfigureABackendLayoutWithTwoColumns.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Configure a Backend Layout With Two Columns
2+
3+
<!-- #TYPO3v13 #Intermediary #Backend #BackendLayout @csabareanu -->
4+
5+
A *Backend Layout* controls how rows and columns of content elements are displayed in TYPO3’s **Page** module, letting editors place their content in designated areas. Though they don't affect frontend rendering directly, backend layouts usually correspond to specific frontend web page layouts.
6+
7+
## Learning Objective
8+
9+
In this step-by-step guide you will create a custom Backend Layout with two columns in an existing Site Package and apply it to all subpages of a specific starting page. The columns will be named:
10+
11+
* “Left” (colPos = 0)
12+
* “Right” (colPos = 2)
13+
14+
They will be displayed as two vertical columns in the **Page → Columns** view in the TYPO3 Backend.
15+
16+
## Prerequisites
17+
18+
### Tools and technology
19+
20+
* A computer with a local [Composer-based TYPO3 installation](https://docs.typo3.org/permalink/t3coreapi:installation-composer) where you have admin access.
21+
* Your TYPO3 installation must have an active Site Package as explained in [Create a Site Package](CreateASitePackage.md). This guide assumes your sitepackage is called `sitepackage`.
22+
* Your site package must include a site set as explained in [Create a Site Set](CreateASiteSet.md).
23+
24+
### Knowledge and skills
25+
26+
* [Using the Page Tree](https://docs.typo3.org/permalink/t3start:page-tree)
27+
* [Modifying the page properties](ModifyingThePageProperties.md)
28+
* [Adding Page TSconfig to a Site Package](AddingPageTSConfigToASitePackage.md).
29+
* Basic understanding of `colPos` property for content columns
30+
31+
## Define the Backend Layout in Page TSconfig
32+
33+
You will store Backend Layout definitions in your Site Set’s Page TSconfig.
34+
35+
1. Open or create the file `EXT:sitepackage/Configuration/Sets/base/page.tsconfig`.
36+
2. Open the file in an IDE or plain text editor.
37+
3. Add the following code snippet to the file:
38+
39+
```typoscript
40+
# --------------------------------------------------------
41+
# Backend Layout: Two Columns
42+
# --------------------------------------------------------
43+
mod.web_layout.BackendLayouts.two_columns {
44+
title = Site Layout: Two Columns
45+
config {
46+
backend_layout {
47+
colCount = 2
48+
rowCount = 1
49+
50+
rows {
51+
1 {
52+
columns {
53+
1 {
54+
name = Left
55+
colPos = 0
56+
}
57+
2 {
58+
name = Right
59+
colPos = 2
60+
}
61+
}
62+
}
63+
}
64+
}
65+
}
66+
}
67+
```
68+
69+
This code snippet defines a Backend Layout with ID "two_columns", containing one row with two columns “Left” and “Right”.
70+
71+
4. Save the file.
72+
5. Clear all caches to apply the changes, as explained in [Clearing All Caches Using the Clear Cache Menu](ClearingAllCachesUsingTheClearCacheMenu.md).
73+
74+
Your page layout is now availabe in the page properties of all pages in your site.
75+
76+
## Select the backend layout for a single page
77+
78+
1. In the TYPO3 Backend, go to the Page module.
79+
2. Choose a page with subpages on your site, for example, the root page.
80+
3. Access the page properties, as explained in [Modifying the page properties](ModifyingThePageProperties.md).
81+
4. In the page properties, select the *Appearance* tab.
82+
5. From the *Backend Layout (this page only)* dropdown menu, select the "Site Layout: Two Columns" option. ![A dropdown menu labeled Backend Layout is open, showing options: None and Site Layout: Two Columns. The page is currently using the Default backend layout inherited from a parent page.](Images/ConfigureABackendLayoutWithTwoColumns/SelectBackendLayoutForSinglePage.png)
83+
6. Save and close the page properties.
84+
7. In the page tree, click on the page title to reload the layout. You should now be able to add content elements to two columns labeled “Left” and “Right”.
85+
86+
You can click on subpages to confirm that the layout is not applied to them.
87+
88+
## Inherit the Backend Layout to All Subpages
89+
90+
Often, you want an entire section of the site to use the same layout automatically.
91+
92+
1. Access the page properties for the page you chose previously, as explained in [Modifying the page properties](ModifyingThePageProperties.md).
93+
2. In the page properties, select the *Appearance* tab.
94+
3. From the *Backend Layout (subpages of this page)* dropdown menu, select the "Site Layout: Two Columns" option. ![A dropdown menu labeled Backend Layout (subpages of this page) is open, showing options: None, Site Layout: Two Columns (selected), Default, and Subpage.](Images/ConfigureABackendLayoutWithTwoColumns/SelectBackendLayoutForSubpages.png)
95+
4. Save and close the page properties.
96+
5. In the page tree, click on subpages to the page you chose and verify that all subpages of the page now use the layout you selected.
97+
98+
> [!TIP]
99+
> When you edit the page properties of a subpage, you will see that the name of the inherited layout is mentioned below the label of the *Backend Layout (this page only)*. Choosing a different layout from the dropdown menu will override the inherited layout. ![A screenshot of a field label and description stating: Backend Layout (this page only) This page is currently using backend layout Site layout: Two Columns, inherited from a parent page.](Images/ConfigureABackendLayoutWithTwoColumns/InheritedLayoutInformation.png)
100+
101+
## Summary
102+
103+
You have now created a custom Backend Layout with two columns and applied it to a single page and all subpages of that page.
104+
105+
## Next steps
106+
107+
* Render the layout in the frontend as explained in [Create a Two-Column Layout With Fluid](CreateATwoColumnLayoutWithFluid.md)
108+
109+
## Resources
110+
111+
* [Backend Layout](https://docs.typo3.org/permalink/t3coreapi:be-layout)

‎Documentation/20BuildingWebsites/10ContentManagement/30ConfigureTheBackendLayout/Images/ConfigureABackendLayoutWithTwoColumns/InheritedLayoutInformation.png‎

4.88 KB
Loading

‎Documentation/20BuildingWebsites/10ContentManagement/30ConfigureTheBackendLayout/Images/ConfigureABackendLayoutWithTwoColumns/SelectBackendLayoutForSinglePage.png‎

8.39 KB
Loading

‎Documentation/20BuildingWebsites/10ContentManagement/30ConfigureTheBackendLayout/Images/ConfigureABackendLayoutWithTwoColumns/SelectBackendLayoutForSubpages.png‎

8.45 KB
Loading

0 commit comments

Comments
 (0)