Skip to content

Commit

Permalink
[DOCS] Improve installation guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@nhovratov
nhovratov committed Dec 24, 2021
1 parent 720fca8 commit 3abc962
Show file tree
Hide file tree
Showing 3 changed files with 79 additions and 97 deletions.
89 changes: 43 additions & 46 deletions Documentation/Installation/Index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,14 @@ Installation
.. note::
Before you start using mask, you should have set up your :ref:`sitepackage<sitepackage>`.

Add Mask as dependency
======================
Preparations
============

It is important to add Mask as a dependency in your `ext_emconf.php` of your sitepackage. This ensures, Mask is loaded
**before** your Theme extension. Only then, you can override the generated TCA from Mask in your Overrides folder.
It is important to add Mask as a dependency in your `ext_emconf.php` of your
sitepackage. This ensures, Mask is loaded **before** your Theme extension. Only
then, you can override the generated TCA from Mask in your Overrides folder.

::
.. code-block:: php
$EM_CONF[$_EXTKEY] = [
'constraints' => [
Expand All @@ -37,61 +38,57 @@ anymore, when in composer mode.
}
}
.. note::

If you add the dependency after Mask is already installed and activated, you
need to rebuild the loading order by reinstalling your extension.

Install and configure
=====================

Download Mask with composer by running the command `composer require mask/mask` or install via extension manager.
The first thing you have to do is to define the paths to various template directories.
The easiest way to change the paths is to add the snippet below to your `LocalConfiguration.php` in the :php:`EXTENSIONS` section:

::

...
'mask' = [
'loader_identifier' => 'json',
'backend' => 'EXT:sitepackage/Resources/Private/Mask/Backend/Templates/',
'backendlayout_pids' => '0,1',
'content' => 'EXT:sitepackage/Resources/Private/Mask/Frontend/Templates/',
'json' => 'EXT:sitepackage/Configuration/Mask/mask.json',
'content_elements_folder' => 'EXT:sitepackage/Configuration/Mask/ContentElements',
'backend_layouts_folder' => 'EXT:sitepackage/Configuration/Mask/BackendLayouts',
'layouts' => 'EXT:sitepackage/Resources/Private/Mask/Frontend/Layouts/',
'layouts_backend' => 'EXT:sitepackage/Resources/Private/Mask/Backend/Layouts/',
'partials' => 'EXT:sitepackage/Resources/Private/Mask/Frontend/Partials/',
'partials_backend' => 'EXT:sitepackage/Resources/Private/Mask/Backend/Partials/',
'preview' => 'EXT:sitepackage/Resources/Public/Mask/',
],
...

Explanations for the settings can be found :ref:`here <extension-settings>`.
Adjust the paths to your needs and activate the extension. When you visit the Mask backend, you will have the option to
create all missing files and folders defined here.
.. rst-class:: bignums

.. note::
This is also great to have in version control so others will have this already set up when checking out the project.
1. Download Mask with composer by running the command `composer require mask/mask` or install via extension manager.

.. versionadded:: 7.1.0
2. Activate Mask in the extension manager (not needed in TYPO3 v11 composer mode)

If you didn't configure yet anything and visit the Mask module, you are able to
auto-configure the paths. You simply have to provide an extension key of a
**loaded** extension.
3. Mask requires `fluid_styled_content` so go to your static includes in the template module and include it there.

.. figure:: ../Images/Mask7.1/AutoConfiguration.png
:alt: Mask auto-configuration
:class: with-border
:ref:`Read here how to include static templates <t3sitepackage:typo3-backend-typoscript-template>`

Mask warns you about missing configuration
| You can install this core extension in composer mode with the command
| `composer require typo3/cms-fluid-styled-content`
4. Also include the Mask static TypoScript.

5. Navigate to the Mask module and enter your sitepackage extension key for auto-configuration (your extension must be loaded!).

Include TypoScript
==================
6. Start creating your own content elements!

Mask works best with :ref:`fluid_styled_content <fluid-styled-content>` so go to your static includes in the template
module and include it there. **After** that also include the Mask static TypoScript.
Manual configuration
====================

If you don't want to use the default folder structure created by the auto-configuration, you can adjust every path in
the :ref:`extension configuration <extension-settings>` of Mask.

.. tip::

It is great to have the `LocalConfiguration.php` file (where the extension configuration is stored)
in version control so others will have this already set up when checking out the project.

Screenshots
===========

.. figure:: ../Images/AdministratorManual/TypoScriptTemplate.png
:alt: Include TypoScript Template
:class: with-border

Include TypoScript Template

That's it. Now you can start creating your own content elements!
.. versionadded:: 7.1.0

.. figure:: ../Images/Mask7.1/AutoConfiguration.png
:alt: Mask auto-configuration
:class: with-border

Mask warns you about missing configuration
1 change: 1 addition & 0 deletions Documentation/Settings.cfg
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ t3tca = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
t3fsc = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/master/en-us/
cms-rte-ckeditor = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/master/en-us/
t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/

[extlinks]
issue = https://github.com/Gernott/mask/issues/%s | Issue #
86 changes: 35 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,45 @@

# Mask

Create your own content elements and page templates. Easy to use, even without programming skills, because of the
comfortable drag and drop user interface. All content is stored in structured database tables.
Mask is a content element builder that generates TypoScript, TSconfig and TCA on
the fly. You can build your own custom content elements in a user-friendly
backend module via drag and drop. Your configuration is stored in json files,
which can be shared across projects.

Mask provides different ield types, that you can use to
customize your content elements. Depending on the type there are different
options available. Field types are grouped roughly into input, repeating and
structural fields. With these given tools, you can cover almost all typical
requirements for your projects. And if not, Mask can be extended
via TCA overrides or DataProcessors.

## What does it do?
## Quickstart

Mask is a TYPO3 extension for creating content elements and extending page templates. It’s possible to add new fields
to any element. Fields can have several types, for example: text, file, relations, rich text, ...
1. Add Mask as a dependency in your `ext_emconf.php` and/or `composer.json` of your sitepackage.
2. Download Mask with composer by running the command `composer require mask/mask` or install via extension manager.
3. Activate Mask in the extension manager (not needed in TYPO3 v11 composer mode).
4. Mask requires `fluid_styled_content` so go to your static includes in the template module and include it there.
5. Also include the Mask static TypoScript.
6. Navigate to the Mask module and enter your sitepackage extension key for auto-configuration (your extension must be loaded!).
7. Start creating your own content elements!

## Quickstart
## Manual configuration

Download Mask with composer by running the command `composer require mask/mask` or install via extension manager.
It is important to add Mask as a dependency in your `ext_emconf.php` and/or `composer.json`, so you can override the
generated TCA. Before you start using Mask, you must define various paths. Add the snippet below to your
`LocalConfiguration.php` in the `EXTENSIONS` section:

```
'mask' => [
'loader_identifier' => 'json',
'backend' => 'EXT:sitepackage/Resources/Private/Mask/Backend/Templates/',
'backendlayout_pids' => '0,1',
'content' => 'EXT:sitepackage/Resources/Private/Mask/Frontend/Templates/',
'json' => 'EXT:sitepackage/Configuration/Mask/mask.json',
'content_elements_folder' => 'EXT:sitepackage/Configuration/Mask/ContentElements',
'backend_layouts_folder' => 'EXT:sitepackage/Configuration/Mask/BackendLayouts',
'layouts' => 'EXT:sitepackage/Resources/Private/Mask/Frontend/Layouts/',
'layouts_backend' => 'EXT:sitepackage/Resources/Private/Mask/Backend/Layouts/',
'partials' => 'EXT:sitepackage/Resources/Private/Mask/Frontend/Partials/',
'partials_backend' => 'EXT:sitepackage/Resources/Private/Mask/Backend/Partials/',
'preview' => 'EXT:sitepackage/Resources/Public/Mask/',
],
```

Adjust the paths to your sitepackage extension and activate Mask. When you visit the Mask backend, you will have the
option to create all missing files and folders defined here. This is also great to have in version control so others
will have this already set up when checking out.

Alternatively, leave the configuration empty and visit the Mask module. There
will be an Auto-Configuration form, that will generate all the above
configuration for you automatically, if you provide a key of a loaded extension.

Mask requires `fluid_styled_content` so go to your static includes in the template module and include it there.
**After** that also include the Mask static TypoScript.

That's it. Now you can start creating your own content elements!
If you don't want to use the default folder structure created by the auto-configuration, you can adjust every path in
the extension configuration of Mask.

## Advantages of Mask

* Mask stores the content in columns in database tables – not as XML (Flexform)
* Mask reuses existing database fields to conserve the database
* Mask works only with existing features of the TYPO3 core: backend layouts, Fluid, TypoScript
* Silent TCA migrations allow for easy TYPO3 upgrades to new major versions
* Mask allows repeating content with IRRE technology
* Mask supports multi-language projects
* Mask supports workspaces and versioning
* The Mask backend is a single page application based on VueJS for even more comfort

Read a detailed explanation for each advantage and why to use Mask over other alternatives in the [official documentation](https://docs.typo3.org/p/mask/mask/main/en-us/Introduction/Index.html).

## Mask versions

Expand All @@ -62,17 +57,6 @@ That's it. Now you can start creating your own content elements!
| v2 | v7 | 2016-05-10 | discontinued | |
| v1 | v6, v7 | 2015-08-12 | discontinued | |

## Advantages of Mask

* Mask stores the content in columns in database tables – not as XML (Flexform)
* Mask reuses existing database fields to conserve the database
* Mask works only with existing features of the TYPO3 core: backend layouts, Fluid, TypoScript
* Silent TCA migrations allow for easy TYPO3 upgrades to new major versions
* Mask allows repeating content with IRRE technology
* Mask supports multi-language projects
* Mask supports workspaces and versioning
* The Mask backend is a single page application based on VueJS for even more comfort

## Need help?

* Read how to install, configure and use mask in the [official documentation](https://docs.typo3.org/p/mask/mask/master/en-us/)
Expand Down

0 comments on commit 3abc962

Please sign in to comment.