# Instalation guide for SGalinski.TypoScriptReferenceFrontend Flow package

There are two guides in this file. 
First one explains the steps to integrate this package with Forger project. 
And the other explains how to install the package in new Flow project.

## Install SGalinski.TypoScriptReferenceFrontend to Forge project

### Prerequisite

First, you need a flow project with Forger package installed in it. 
To do so, follow these instructions:

    https://github.com/wmdbsystems/WMDB.Forger

### Install

    cd Packages/Application
    git clone git@gitlab.sgalinski.de:typo3/TypoScript-Forger.git SGalinski.TypoScriptReferenceFrontend
    cd SGalinski.TypoScriptReferenceFrontend

### Supply the necessary routes

Edit Routes.yaml of main project (`ProjectName/Configuration/Routes.yaml`)

It is important to include SGalinski.TypoScriptReferenceFrontend subRoutes before WMDB.ForgerSubroutes to avoid
route conflicts. 
The prefix `ts` in uriPattern: `ts/<SGalinski.TypoScriptReferenceFrontend>` has purpose to avoid the conflict.

This complete Routes.yaml:

    -
      name: 'TypoScriptReferenceFrontend'
      uriPattern: 'ts/<SGalinski.TypoScriptReferenceFrontend>'
      subRoutes:
        SGalinski.TypoScriptReferenceFrontend:
          package: SGalinski.TypoScriptReferenceFrontend
    
    -
      name: 'Forger'
      uriPattern: '<WMDB.ForgerSubroutes>'
      subRoutes:
        WMDB.ForgerSubroutes:
          package: WMDB.Forger
    
    ##
    # Flow subroutes
    #
    
    -
      name: 'Flow'
      uriPattern: '<FlowSubroutes>'
      defaults:
        '@format': 'html'
      subRoutes:
        FlowSubroutes:
          package: TYPO3.Flow

### Configure view

To be able to use menu from `WMDB.Forger` package, view configuration in main project is needed.

In main project, add next lines to `ProjectName/Configuration/Views.yaml`:

    -
      options:
        layoutRootPaths:
          'WMDB.Forger/Layouts': 'resource://WMDB.Forger/Private/Layouts'
        partialRootPaths:
          'WMDB.Forger/Partials': 'resource://WMDB.Forger/Private/Partials'
          'SGalinski.TypoScriptReferenceFrontend/Partials': 'resource://SGalinski.TypoScriptReferenceFrontend/Private/Partials'
    #    templateRootPaths:
    #      'WMDB.Forger/Templates': 'resource://WMDB.Forger/Private/Templates'
    #      'SGalinski.TypoScriptReferenceFrontend/Templates': 'resource://SGalinski.TypoScriptReferenceFrontend/Private/Templates'

(if `Views.yaml` doesn't exist, create it)

### Install backend

This package is front end part of grater entity. 
All the data which is used by this package is provided by RESTful web service:

    https://gitlab.sgalinski.de/typo3/TypoScript-Backend
    
If the web service is not installed, follow it's readme to do so.

### Access the package via browser

This is access address:

    your.domain/ts/tsref
    
### Add TypoScript reference link to Forger menu

This code:

    <li><f:link.action package="SGalinski.TypoScriptReferenceFrontend" controller="tsref" action="index"><i class="fa fa-fw fa-file-text-o"></i> TypoScript reference</f:link.action></li>
    
Needs to be added to the Forger file:

    Packages/Application/WMDB.Forger/Resources/Private/Partials/Menu.html
    
under `Utility` menu. It should be at line 28.


================================================================


## Install SGalinski.TypoScriptReferenceFrontend to new project

### Prerequisite

SGalinski.TypoScriptReferenceFrontend is Flow package, so you need first a flow project.

    composer create-project --dev --keep-vcs typo3/flow-base-distribution ProjectName
    
You can use any project name you wish. If you already have Flow project, you can skip this step.

### Install

    cd Packages/Application
    git clone git@gitlab.sgalinski.de:typo3/TypoScript-Forger.git SGalinski.TypoScriptReferenceFrontend
    cd SGalinski.TypoScriptReferenceFrontend

### Supply the necessary routes

Edit Routes.yaml of your project (`ProjectName/Configuration/Routes.yaml`)

    -
      name: 'TypoScriptReferenceFrontend'
      uriPattern: '<SGalinski.TypoScriptReferenceFrontend>'
      subRoutes:
        SGalinski.TypoScriptReferenceFrontend:
          package: SGalinski.TypoScriptReferenceFrontend
    
    ##
    # Flow subroutes
    #
    
    -
      name: 'Flow'
      uriPattern: '<FlowSubroutes>'
      defaults:
        '@format': 'html'
      subRoutes:
        FlowSubroutes:
          package: TYPO3.Flow

Uri prefix can be added if needed, e.g.: `uriPattern: 'ts/<SGalinski.TypoScriptReferenceFrontend>'`.

### Configure view

To be able to integrate `SGalinski.TypoScriptReferenceFrontend` package with other packages 
(for example to use existing layout with menu from other package), view configuration in main project is needed.

Here is example of view configuration for integration with `WMDB.Forger` package.

`ProjectName/Configuration/Views.yaml`:

    -
      options:
        layoutRootPaths:
          'WMDB.Forger/Layouts': 'resource://WMDB.Forger/Private/Layouts'
        partialRootPaths:
          'WMDB.Forger/Partials': 'resource://WMDB.Forger/Private/Partials'
          'SGalinski.TypoScriptReferenceFrontend/Partials': 'resource://SGalinski.TypoScriptReferenceFrontend/Private/Partials'
    #    templateRootPaths:
    #      'WMDB.Forger/Templates': 'resource://WMDB.Forger/Private/Templates'
    #      'SGalinski.TypoScriptReferenceFrontend/Templates': 'resource://SGalinski.TypoScriptReferenceFrontend/Private/Templates'

### Install backend

This project is front end part of grater entity. 
All the data which is used by this package is provided by RESTful web service:

    https://gitlab.sgalinski.de/typo3/TypoScript-Backend
    
If the web service is not installed, follow it's readme to do so.

### Access the package via browser

This is access address:

    your.domain/tsref
    
### Fluid link to access the package

Put this link in a menu:

    <f:link.action package="SGalinski.TypoScriptReferenceFrontend" controller="tsref" action="index"><i class="fa fa-fw fa-file-text-o"></i> TypoScript reference</f:link.action>