slush-source4/template/README.md

Source 4 generator

# Source 4

Note : all referenced Composer/NPM/Bower modules are named by their Github repository names.

## Install environment

```sh
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update
sudo apt install yarn composer
yarn global add gulp@3 slush slush-source4 bower
npx @nodenv/nodenv-installer
nodenv install 10.22.1
sudo apt install php-mbstring php-curl php-intl
rm -rf vendor/pyrsmk/source-4
slush source4
```

## Run the development server

You must install [Docker](https://docs.docker.com/get-docker/) first. When this is done, run:

```sh
gulp serve
```

## Slush ecosystem

Slush manages the creation and the update of your project. Here's the command list :

- `slush source4` : install a new Source 4 project
- `slush source4:update` : update an existing Source 4 project to the latest version of Source 4

## Gulp ecosystem

Gulp will manage your project. Here's the usual command list :

- `gulp` : watch any file for changes
- `gulp css` : compile Sass files and source maps
- `gulp js` : verify, lint and compile scripts
- `gulp images` : compress and resize images
- `gulp favicons` : generate favicons based on a `favicon.png` file
- `gulp deploy` : deploy the site in staging
- `gulp deploy --production` : deploy the site in production

If needed you can add your own Gulp commands for your project in `application/gulp/`.

## The application directories

- `components/` : where all your pages/components should go
- `config/` : all the JSON config files
- `data/` : the application can store some data here
- `favicons/sources/` : the source favicon location (named `favicon.png` with a size of `260x260`)
- `favicons/` : the generated favicons by Gulp
- `gulp/` : all your Gulp submodules
- `images/sources/` : the source images before compression/resize
- `images/` : the resulting images, used in your site
- `langs/` : the JSON i18n files
- `snippets/header/` : snippets of HTML code inserted at the top of the site
- `snippets/footer/` : snippets of HTML code inserted at the bottom of the site
- `uploads/` : the uploads should go here

## Components

A component is a directory placed in `application/components/` and composed of different files :

- `component.js` : the JS code for the component
- `component.php` : usually the controller; can have any other functions/declarations needed by the component
- `component.twig` : the template
- `component.scss` : the Sass file for the component
- `require.json` : the dependencies for the component

Here's an example of a simple controller :

```php
$lumy->get('/', function ($request, $response, $args) {
    $this['initComponent']('application/_index'); // Needed by all page components (see below)
    return $this['render']($response); // Renders the component's Twig template
});
```

Each component has a `require.json` file that automatically imports the referring components. This the case for `php`, `js` and `scss` files but not for `twig` templates, because templates need to include the component where needed and may extend another component too. Here's a `require.json` example :

```json
{
    "extends": "source4/root",
    "dependencies": [
        "application/header",
        "application/main",
        "application/footer"
    ]
}
```

The component names have a namespace, and a name. Source 4 components are named like `source4/name` and application components `application/name`. This typology is used in `require.json` and Twig templates.

There are special components that are pages for your site. These components have an underscore prefixing their names like `application/_name`. All page components will be automatically included by the Source 4 engine with all their dependencies.

Note : generally the first component to extend is `source4/root`.

## PHP ecosystem

The following Composer modules are available :

- `pyrsmk/lumy3` : which extends the Slim framework with the Chernozem container
- `pyrsmk/funktions` : some useful functions, like `debug()`
- `pyrsmk/mail` : used for by the mailing service (see below)
- `pyrsmk/session` : the Session service
- `twig/twig` : the Twig template engine
- `pyrsmk/translator` : used for managing translations; it automatically register itself in Twig with the function `translate('key')`
- `slimphp/slim-csrf` : a CSRF plugin for Slim, managed in `site.json` configuration file
- `league/commonmark` : a Markdown parser

If needed, you can add new modules via Composer at the root of your project. This modules will be kept when updating Source 4.

If you want to add a PHP library for a single component, you can add the source files into the component itself and requiring it inside the `component.php` file.

Some additional functions are available from `Lumy3` :

- `$lumy['json_decode']` : load a JSON file by its path
- `$lumy['loadConfig']` : load a configuration file by its name

## Twig ecosystem

Here's the exhaustive list of additional available variables :

- `config` : an array of all the loaded configuration files
- `env.mode` : reflect the defined APP_ENV variable (`development`, `staging` or `production`)
- `env.method` : the current request method
- `env.scheme` : the current HTTP scheme
- `env.host` : the current host
- `env.port` : the current port
- `env.basepath` : the base path
- `env.locale` : the current used locale
- `page` : the component name for the current page

Some additional functions are available too :

- `translate('key)` : translate a string, based on registered lang files
- `dump(variable)` : available in development mode for debugging

Here's the available blocks from `source4/root` :

- `title` : the title of the page
- `meta` : meta markups if needed (like `description`)
- `body` : the body of the page

## Sass ecosystem

The following Sass modules are available :

- `mojotech/jeet` : a grid system
- `modularscale/modularscale-sass` : modular scales for Sass
- `pyrsmk/vertical-rhythmic` : vertical rhythms for Sass
- `hail2u/normalize.scss` : the Sass version of Normalize.css

If you want to add a CSS/SCSS library for a single component, you can add the source files into the component itself and requiring with the `@import` directive inside the `component.scss` file.

Some additional mixins are available :

- `@include hide();` : hide an element visually
- `@include image-replacement();` : replace text in the element by a background image set by hand
- `@include selection { ... }` : apply styles to selection
- `@include placeholder($color)` : apply a color for placeholder
- `@include print();` : add base styles for printing

## JavaScript ecosystem

The following NPM modules are available :

- `scottjehl/picturefill` : a responsive tool for images
- `pyrsmk/quark` : a micro JS framework
- `pyrsmk/quarky` : a plugin to extend the JS framework
- `pyrsmk/toast` : a JS/CSS resource loader
- `pyrsmk/w` : a responsive set of tools

If needed, you can add new modules via NPM at the root of your project. This modules will be kept when updating Source 4.

If you want to add a JS library for a single component, you can add the source files into the component itself and requiring it via `toast` inside the `component.js` file.

Here's the exhaustive list of additional available variables in the JS environment :

- `env.dev` : true if the site is in development mode
- `env.method` : the current request method
- `env.scheme` : the current HTTP scheme
- `env.host` : the current host
- `env.port` : the current port
- `env.basepath` : the base path
- `env.locale` : the current used locale

## Configuration files

- deploy.json : define the deployment authentication; supported adapters : `rsync`
- favicons.json : favicons metadata file generated from [RealFaviconGenerator](https://realfavicongenerator.net/)
- livereload.json : define the server for LiveReload
- mail.json : define mail addresses (`contact` is the client mail address)
- responsive.json : contains the parameters for `gulp-responsive`
- site.json : define base variables for the site (`name` is used in the `title` tag)
- tinypng.json : define the TinyPNG's service API key for compressing images

## The mailing service

Source 4 is shipped with a mailing service. You can send e-mails from JavaScript environment (per example), by doing a POST request to `/mail`.

E-mails are sent based on a Twig template, so you can send either text or html e-mails.

The `/mail` resource accepts several POST arguments :

- `from` : the sender, usually a hidden input
- `to` : the recipient
- `subject` : the subject
- `body` : the text template path, hidden input, optional
- `html` : the html template path, hidden input, optional
- `required` : an array of hidden inputs defining what fields are required
- `data` : an associative array of additional data, will be passed to the template for rendering

## sitemap.xml

A `robots.txt` is automatically generated to reference a `/sitemap.xml` resource. But you must define this resource by yourself by creating a component that displays a template extending `source4/sitemap`. This parent template accepts an `entries` variable which is an array of entries. Each entry must be an object with the following properties :

- `loc`
- `changefreq` (optional)
- `priority` (optional)
- `lastmod` (optional)

Further informations of the Sitemap protocol can be found [here](https://www.sitemaps.org/fr/protocol.html).

But here's an example :

```php
$lumy->get('/sitemap.xml', function($request, $response, $args) use($lumy) {
    $lumy['render']('source4/sitemap', array('entries' => array(
        array(
            'loc' => '/',
            'changefreq' => 'monthly'
        )
    )));
});
```