Skip to content

Commit ed54ff9

Browse files
s2bs2b
committed
[TASK] Improved documentation structure
1 parent 8110565 commit ed54ff9

File tree

2 files changed

+56
-64
lines changed

2 files changed

+56
-64
lines changed

Diff for: ‎Documentation/UpdateNotes.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Fluid Components: Updating from 1.x
2+
3+
There is only one breaking change: It isn't possible anymore to use Fluid variables in default values
4+
for component parameters. This will **NOT WORK ANYMORE**:
5+
6+
```xml
7+
<fc:param name="firstName" type="string" optional="1" default="{settings.defaultFirstName}" />
8+
```
9+
10+
As this was a pretty esoteric feature, you shouldn't have any problems when updating to 2.x!

Diff for: ‎README.md

+46-64
Original file line numberDiff line numberDiff line change
@@ -2,44 +2,14 @@
22

33
This TYPO3 extensions puts frontend developers in a position to create encapsulated components
44
in pure Fluid. By defining a clear interface (API) for the integration, frontend developers can
5-
implement components independent of backend developers. The goal is to create presentational
6-
components which have no side effects and aren't responsible for data acquisition. The sole
7-
concern of a presentational component should be how things look.
5+
implement components independent of backend developers. The goal is to create highly reusable
6+
presentational components which have no side effects and aren't responsible for data acquisition.
87

9-
## Authors & Sponsors
10-
11-
* Simon Praetorius - [email protected]
12-
* [All contributors](https://github.com/sitegeist/fluid-components/graphs/contributors)
13-
14-
*The development and the public-releases of this package is generously sponsored
15-
by my employer https://sitegeist.de.*
16-
17-
## Installation
18-
19-
This TYPO3 extension is available via packagist:
20-
21-
```composer require sitegeist/fluid-components```
22-
23-
Alternatively, you can install the extension from TER:
24-
25-
[TER: fluid_components](https://typo3.org/extensions/repository/view/fluid_components)
26-
27-
After that, proceed with [Getting Started](#getting-started)
28-
29-
## Updating from 1.x
30-
31-
There is only one breaking change: It isn't possible anymore to use Fluid variables in default values
32-
for component parameters. This will **NOT WORK ANYMORE**:
33-
34-
```xml
35-
<fc:param name="firstName" type="string" optional="1" default="{settings.defaultFirstName}" />
36-
```
37-
38-
As this was a pretty esoteric feature, you shouldn't have any problems when updating to 2.x!
8+
⬇️ **[TL;DR? Get started right away](#getting-started)** ⬇️
399

4010
## What does it do?
4111

42-
Fluid templates usually consist of three parts:
12+
[Fluid](https://github.com/typo3/fluid) templates usually consist of three ingredients:
4313

4414
* **Templates**,
4515
* **Layouts**, which structure and wrap the markup defined in the template, and
@@ -64,17 +34,17 @@ the component. You don't need to know what the component does internally to be a
6434

6535
## How do components look like?
6636

67-
The following component implements a simple teaser element:
37+
The following component implements a simple teaser card element:
6838

69-
*Components/Teaser/Teaser.html*
39+
*Components/TeaserCard/TeaserCard.html*
7040

7141
```xml
7242
<fc:component>
7343
<fc:param name="title" type="string" />
7444
<fc:param name="description" type="string" />
7545
<fc:param name="link" type="Typolink" />
7646
<fc:param name="icon" type="string" optional="1" />
77-
<fc:param name="theme" type="string" optional="1">light</fc:param>
47+
<fc:param name="theme" type="string" optional="1" default="light" />
7848

7949
<fc:renderer>
8050
<a href="{link}" class="{component.class} {component.class}-{theme}">
@@ -89,11 +59,11 @@ The following component implements a simple teaser element:
8959
</fc:component>
9060
```
9161

92-
Use the following code in your template to render a teaser about TYPO3:
62+
Use the following code in your template to render a teaser card about TYPO3:
9363

9464
```xml
9565
{namespace my=VENDOR\MyExtension\Components}
96-
<my:teaser
66+
<my:teaserCard
9767
title="TYPO3"
9868
description="The professional, flexible Content Management System"
9969
link="https://typo3.org"
@@ -104,29 +74,23 @@ Use the following code in your template to render a teaser about TYPO3:
10474
The result is the following HTML:
10575

10676
```xml
107-
<a href="https://typo3.org" class="smsExampleTeaser smsExampleTeaser-light">
108-
<h3 class="smsExampleTeaser_title">TYPO3</h3>
109-
<p class="smsExampleTeaser_description">The professional, flexible Content Management System</p>
77+
<a href="https://typo3.org" class="smsExampleTeaserCard smsExampleTeaserCard-light">
78+
<h3 class="smsExampleTeaserCard_title">TYPO3</h3>
79+
<p class="smsExampleTeaserCard_description">The professional, flexible Content Management System</p>
11080

111-
<i class="icon icon-typo3 smsExampleTeaser_icon"></i>
81+
<i class="icon icon-typo3 smsExampleTeaserCard_icon"></i>
11282
</a>
11383
```
11484
*(improved indentation for better readability)*
11585

116-
## Why should I use components?
117-
118-
* Components encourage **markup reusage and refactoring**. Only the component knows about its implementation
119-
details. As long as the interface stays compatible, the implementation can change.
120-
* Components can be a tool to **enforce design guidelines**. If the component's implementation respects the
121-
guidelines, they are respected everywhere the component is used. A helpful tool to accomplish that is the corresponding
122-
living styleguide: [Fluid Styleguide](https://github.com/sitegeist/fluid-styleguide).
123-
* Components **formalize and improve communication**. Frontend developers and integrators agree on a clearly
124-
defined interface instead of debating implementation details.
125-
* Components **reduce dependencies**. Frontend developers can work independent of integrators and backend developers.
126-
12786
## Getting Started
12887

129-
1. [Install the extension](#installation)
88+
1. Install the extension either [from TER](https://typo3.org/extensions/repository/view/fluid_components)
89+
or [via composer](https://packagist.org/packages/sitegeist/fluid-components):
90+
91+
```
92+
composer require sitegeist/fluid-components
93+
```
13094

13195
2. Define the component namespace in your *ext_localconf.php*:
13296

@@ -140,25 +104,43 @@ defined interface instead of debating implementation details.
140104
3. Create your first component in *EXT:my_extension/Resources/Private/Components/* by creating a directory
141105
*MyComponent* containing a file *MyComponent.html*
142106

143-
4. Define your component according to [How do components look like?](#how-do-components-look-like) as well as
144-
the [ViewHelper Reference](Documentation/ViewHelperReference.md).
107+
4. Define and apply your component according to [How do components look like?](#how-do-components-look-like). The [Extended Documentation](#extended-documentation)
108+
can be helpful as well.
145109

146-
5. Render your component by including the namespace and calling the component by its name:
110+
5. Check out [Fluid Styleguide](https://github.com/sitegeist/fluid-styleguide), a living styleguide for Fluid Components, and [Fluid Components Linter](https://github.com/sitegeist/fluid-components-linter) to improve the quality and reusability of your components.
147111

148-
```xml
149-
{namespace my=VENDOR\MyExtension\Components}
150-
<my:myComponent someParameter="someValue" />
151-
```
112+
If you have any questions, need support or want to discuss components in TYPO3, feel free to join [#ext-fluid_components](https://typo3.slack.com/archives/ext-fluid_components).
152113

153-
6. Check out [Fluid Styleguide](https://github.com/sitegeist/fluid-styleguide), a living styleguide for Fluid Components, and [Fluid Components Linter](https://github.com/sitegeist/fluid-components-linter) to improve the quality and reusability of your components.
114+
## Why should I use components?
154115

155-
If you have any questions, need support or want to discuss components in TYPO3, feel free to join [#ext-fluid_components](https://typo3.slack.com/archives/ext-fluid_components).
116+
* Components encourage **markup reusage and refactoring**. Only the component knows about its implementation
117+
details. As long as the interface stays compatible, the implementation can change.
118+
* Components can be a tool to **enforce design guidelines**. If the component's implementation respects the
119+
guidelines, they are respected everywhere the component is used. A helpful tool to accomplish that is the corresponding
120+
living styleguide: [Fluid Styleguide](https://github.com/sitegeist/fluid-styleguide).
121+
* Components **formalize and improve communication**. Frontend developers and integrators agree on a clearly
122+
defined interface instead of debating implementation details.
123+
* Components **reduce dependencies**. Frontend developers can work independent of integrators and backend developers.
156124

157125
## Extended Documentation
158126

127+
Feature References
128+
159129
* [ViewHelper Reference](Documentation/ViewHelperReference.md)
160130
* [Included Data Structures](Documentation/DataStructures.md)
161131
* [Component Prefixers](Documentation/ComponentPrefixers.md)
162132
* [Component Settings](Documentation/ComponentSettings.md)
133+
134+
How-To's
135+
163136
* [Usage with Forms](Documentation/Forms.md)
164137
* [Add auto-completion in your IDE](Documentation/AutoCompletion.md)
138+
* [Updating from 1.x](Documentation/UpdateNotes.md)
139+
140+
## Authors & Sponsors
141+
142+
* Simon Praetorius - [email protected]
143+
* [All contributors](https://github.com/sitegeist/fluid-components/graphs/contributors)
144+
145+
*The development and the public-releases of this package is generously sponsored
146+
by my employer https://sitegeist.de.*

0 commit comments

Comments
 (0)