<commit_before># SilverStripe Elemental

[![Build Status](http://img.shields.io/travis/dnadesign/silverstripe-elemental.svg?style=flat)](https://travis-ci.org/dnadesign/silverstripe-elemental)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/dnadesign/silverstripe-elemental/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/dnadesign/silverstripe-elemental/?branch=master)
[![codecov](https://codecov.io/gh/dnadesign/silverstripe-elemental/branch/master/graph/badge.svg)](https://codecov.io/gh/dnadesign/silverstripe-elemental)
[![SilverStripe supported module](https://img.shields.io/badge/silverstripe-supported-0071C4.svg)](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)
[![Version](http://img.shields.io/packagist/v/dnadesign/silverstripe-elemental.svg?style=flat)](https://packagist.org/packages/dnadesign/silverstripe-elemental)
[![License](http://img.shields.io/packagist/l/dnadesign/silverstripe-elemental.svg?style=flat)](LICENSE.md)

## Introduction

This module extends a page type to swap the content area for a list of manageable elements to compose a page out
of rather than a single text field. Features supported:

* Versioning of elements
* Ability to add, remove supported elements per page

The module provides basic markup for each of the elements but you will likely need to provide your own styles. Replace
the `$Content` variable with `$ElementalArea` in your page templates, and rely on the markup of the individual elements.

For a more detailed overview of using this module, please see [the User help guides](docs/en/index.md).

## Requirements

* SilverStripe CMS ^4.2
* Versioned Admin ^1.0
* GridFieldExtensions ^3.1

For a SilverStripe 3.x compatible version of this module, please see the [1 branch, or 1.x release line](https://github.com/dnadesign/silverstripe-elemental/tree/1#readme).

## Installation

```
composer require dnadesign/silverstripe-elemental 4.x-dev
```

The following YAML config will enable elements on every `Page` object,
replacing the standard `Content` rich text field.

**mysite/\_config/elements.yml**

```yaml
Page:
  extensions:
    - DNADesign\Elemental\Extensions\ElementalPageExtension
```

In your page type layout template use `$ElementalArea` to render the elements to the page.

## Getting more elements

Note that this module comes by default with the base element and a "Content" element. If you need more, take
a look at some other modules:

## SilverStripe supported content block modules

To learn more about [SilverStripe supported](https://www.silverstripe.org/software/addons/supported-modules-definition/) content block types see, [Creating new blocks](/docs/en/edit_content.md).

* [dnadesign/silverstripe-elemental](https://github.com/dnadesign/silverstripe-elemental): Text content (built-in)
* [silverstripe/silverstripe-elemental-fileblock](https://github.com/silverstripe/silverstripe-elemental-fileblock): File and image block
* [silverstripe/silverstripe-elemental-bannerblock](https://github.com/silverstripe/silverstripe-elemental-bannerblock): Banner with call-to-action and content
* [dnadesign/silverstripe-elemental-userforms](https://github.com/dnadesign/silverstripe-elemental-userforms): Embed a [user defined form](https://github.com/silverstripe/silverstripe-userforms)

## Examples of community built content block modules (not a comprehensive list)

* [dnadesign/silverstripe-elemental-list](https://github.com/dnadesign/silverstripe-elemental-list): Container for elements (allows layouts)
* [dnadesign/silverstripe-elemental-virtual](https://github.com/dnadesign/silverstripe-elemental-virtual): Reuse elements across pages
* [dynamic/silverstripe-elemental-customer-service](https://github.com/dynamic/silverstripe-elemental-customer-service): Contact information
* [dynamic/silverstripe-elemental-accordion](https://github.com/dynamic/silverstripe-elemental-accordion): Expand/collapse content areas
* [dynamic/silverstripe-elemental-flexslider](https://github.com/dynamic/silverstripe-elemental-flexslider): Slideshows with flexible elements
* [dynamic/silverstripe-elemental-blog](https://github.com/dynamic/silverstripe-elemental-blog): Recent blog posts
* [dynamic/silverstripe-elemental-sponsors](https://github.com/dynamic/silverstripe-elemental-sponsors): Sponsor logos
* [dynamic/silverstripe-elemental-testimonials](https://github.com/dynamic/silverstripe-elemental-testimonials): Customer testimonials and quotes
* [nyeholt/silverstripe-ozzymental](https://github.com/nyeholt/silverstripe-ozzymental): oEmbed items (video, etc)
* [dynamic/silverstripe-elemental-countdown](https://github.com/dynamic/silverstripe-elemental-countdown): Countdown to a specific date/time

## Helpful modules

These modules can extend functionality, and make elemental
more compatible with other approaches in SilverStripe:

* [dnadesign/silverstripe-elemental-subsites](https://github.com/dnadesign/silverstripe-elemental-subsites): Compatibility with the [silverstripe/subsites](https://github.com/silverstripe/silverstripe-subsites) module
* [dnadesign/silverstripe-elemental-skeletons](https://github.com/dnadesign/silverstripe-elemental-skeletons): Creates a template of elements which can be created for a page in the CMS

## Configuration

### Limit to specific page type

If you want to use elements alongside traditional page types,
you can define an "empty" page type and assign the extension only to this type.

**mysite/src/MyElementPage.php**

```php
<?php
class MyElementPage extends Page
{
}
```

**mysite/\_config/elements.yml**

```yaml
MyElementPage:
  extensions:
    - DNADesign\Elemental\Extensions\ElementalPageExtension
```

### Customize HTML and markup

The basic element area is rendered into the `DNADesign/Elemental/Models/ElementalArea.ss` template. This loops over
each of the element controller instances. Each controller instance will render `$ElementHolder` which represents
the element contained within a holder `div`. The wrapper div is the `ElementHolder.ss` template.

To customise the ElementEditor in the CMS you will need to use the SilverStripe JS Injector to apply transformations
to the necessary React components. [See here](https://docs.silverstripe.org/en/4/developer_guides/customising_the_admin_interface/how_tos/customise_react_components/)
for more information.

### Limit allowed elements

You may wish to only enable certain elements for the CMS authors to choose from rather than the full set. This can be
done according to various page types:

```yaml
Page:
  allowed_elements:
    - DNADesign\Elemental\Models\ElementContent
```

Likewise, you can exclude certain elements from being used.

```yaml
Page:
  disallowed_elements:
    - YourCompany\YourModule\Elements\ElementContact
```

### Sharing elements between pages

By default the page to element relationship is a "has one", meaning you cannot share elements between pages. If this
functionality is desired, you could take a look at the [silverstripe-elemental-virtual](https://github.com/dnadesign/silverstripe-elemental-virtual)
module which helps to achieve this.

### Defining your own elements

An element is as simple as a PHP class which extends `DNADesign\Elemental\Models\BaseElement`, and a template to go
with it (unless you want it to use the default template). After you add the class, ensure you have rebuilt your
database and reload the CMS.

```php
<?php

use DNADesign\Elemental\Models\BaseElement;

class MyElement extends BaseElement
{
    private static $singular_name = 'my element';

    private static $plural_name = 'my elements';

    private static $description = 'What my custom element does';

	public function getCMSFields()
    {
        $fields = parent::getCMSFields();

        // ...

        return $fields;
    }

    public function getType()
    {
        return 'My Element';
    }
}
```

#### In-line Editing

By default elements can be edited in the CMS using an inline form where all your elements appear together. For elements 
that are more complex you can disable the in-line edit form by setting `private static $inline_editable = false` in your
element class. A `GridFieldDetailForm` will be used to edit blocks that are not in-line editable.

### Defining your own HTML

`MyElement` will be rendered into a `MyElement.ss` template with the `ElementHolder.ss` wrapper. Changing the holder
template can be done via YAML, or by using a `$controller_template` on your subclass.

```php
private static $controller_template = 'MyElementHolder';
```

To customise existing block templates such as `Content` and `Form` templates, copy the relevant files from
`vendor/dnadesign/silverstripe-elemental/templates` to your theme. When doing this, ensure you match the folder
structure (PHP class namespace) to ensure that your new template version takes priority.

**Note:** The default set of elements follow the [BEM (Block Element Modifier])(http://getbem.com/) class naming
convention, which allows developers to style individual parts of the DOM without unnecessarily nested CSS. Where
possible, we encourage you to follow this naming system.


#### Position Helpers

In your `BaseElement` template you can use the following variables for additional
logic or styling helpers. They behave in the same way traditional `SS_Viewer`
methods work either returning a `Boolean`, `String` or a `Int`
<commit_msg>Update readme to reflect new requirements and developer notes<commit_after># SilverStripe Elemental

[![Build Status](http://img.shields.io/travis/dnadesign/silverstripe-elemental.svg?style=flat)](https://travis-ci.org/dnadesign/silverstripe-elemental)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/dnadesign/silverstripe-elemental/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/dnadesign/silverstripe-elemental/?branch=master)
[![codecov](https://codecov.io/gh/dnadesign/silverstripe-elemental/branch/master/graph/badge.svg)](https://codecov.io/gh/dnadesign/silverstripe-elemental)
[![SilverStripe supported module](https://img.shields.io/badge/silverstripe-supported-0071C4.svg)](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)
[![Version](http://img.shields.io/packagist/v/dnadesign/silverstripe-elemental.svg?style=flat)](https://packagist.org/packages/dnadesign/silverstripe-elemental)
[![License](http://img.shields.io/packagist/l/dnadesign/silverstripe-elemental.svg?style=flat)](LICENSE.md)

## Introduction

This module extends a page type to swap the content area for a list of manageable elements to compose a page out
of rather than a single text field. Features supported:

* Versioning of elements
* Ability to add, remove supported elements per _elemental area_

The module provides basic markup for each of the elements but you will likely need to provide your own styles. Replace
the `$Content` variable with `$ElementalArea` in your page templates, and rely on the markup of the individual elements.

For a more detailed overview of using this module, please see [the User help guides](docs/en/index.md).

## Requirements

* SilverStripe CMS ^4.3
* Versioned Admin ^1.0
* GridFieldExtensions ^3.1

For a SilverStripe 4.1 or 4.2 compatible version of this module, please see the [2.x or 3.x release line](https://github.com/dnadesign/silverstripe-elemental/tree/3#readme).

For a SilverStripe 3.x compatible version of this module, please see the [1 branch, or 1.x release line](https://github.com/dnadesign/silverstripe-elemental/tree/1#readme).

## Installation

```
composer require dnadesign/silverstripe-elemental ^4
```

The following YAML config will enable elements on every `Page` object,
replacing the standard `Content` rich text field.

**mysite/\_config/elements.yml**

```yaml
Page:
  extensions:
    - DNADesign\Elemental\Extensions\ElementalPageExtension
```

In your page type layout template use `$ElementalArea` to render the elements to the page (in place of `$Content`).

## Getting more elements

Note that this module comes by default with the base element and a "Content" element. If you need more, take
a look at some other modules:

## SilverStripe supported content block modules

To learn more about [SilverStripe supported](https://www.silverstripe.org/software/addons/supported-modules-definition/) content block types see, [Creating new blocks](/docs/en/edit_content.md).

* [dnadesign/silverstripe-elemental](https://github.com/dnadesign/silverstripe-elemental): Text content (built-in)
* [silverstripe/silverstripe-elemental-fileblock](https://github.com/silverstripe/silverstripe-elemental-fileblock): File and image block
* [silverstripe/silverstripe-elemental-bannerblock](https://github.com/silverstripe/silverstripe-elemental-bannerblock): Banner with call-to-action and content
* [dnadesign/silverstripe-elemental-userforms](https://github.com/dnadesign/silverstripe-elemental-userforms): Embed a [user defined form](https://github.com/silverstripe/silverstripe-userforms)

## Examples of community built content block modules (not a comprehensive list - may not be updated for Elemental 4 yet)

* [dnadesign/silverstripe-elemental-list](https://github.com/dnadesign/silverstripe-elemental-list): Container for elements (allows layouts)
* [dnadesign/silverstripe-elemental-virtual](https://github.com/dnadesign/silverstripe-elemental-virtual): Reuse elements across pages
* [dynamic/silverstripe-elemental-customer-service](https://github.com/dynamic/silverstripe-elemental-customer-service): Contact information
* [dynamic/silverstripe-elemental-accordion](https://github.com/dynamic/silverstripe-elemental-accordion): Expand/collapse content areas
* [dynamic/silverstripe-elemental-flexslider](https://github.com/dynamic/silverstripe-elemental-flexslider): Slideshows with flexible elements
* [dynamic/silverstripe-elemental-blog](https://github.com/dynamic/silverstripe-elemental-blog): Recent blog posts
* [dynamic/silverstripe-elemental-sponsors](https://github.com/dynamic/silverstripe-elemental-sponsors): Sponsor logos
* [dynamic/silverstripe-elemental-testimonials](https://github.com/dynamic/silverstripe-elemental-testimonials): Customer testimonials and quotes
* [dynamic/silverstripe-elemental-countdown](https://github.com/dynamic/silverstripe-elemental-countdown): Countdown to a specific date/time

## Helpful modules

These modules can extend functionality, and make elemental
more compatible with other approaches in SilverStripe:

* [dnadesign/silverstripe-elemental-subsites](https://github.com/dnadesign/silverstripe-elemental-subsites): Compatibility with the [silverstripe/subsites](https://github.com/silverstripe/silverstripe-subsites) module
* [dnadesign/silverstripe-elemental-skeletons](https://github.com/dnadesign/silverstripe-elemental-skeletons): Creates a template of elements which can be created for a page in the CMS

## Configuration

### Limit to specific page type

If you want to use elements alongside traditional page types,
you can define an "empty" page type and assign the extension only to this type.

**mysite/src/MyElementPage.php**

```php
<?php
class MyElementPage extends Page
{
}
```

**mysite/\_config/elements.yml**

```yaml
MyElementPage:
  extensions:
    - DNADesign\Elemental\Extensions\ElementalPageExtension
```

### Customize HTML and markup

The basic element area is rendered into the `DNADesign/Elemental/Models/ElementalArea.ss` template. This loops over
each of the element controller instances. Each controller instance will render `$ElementHolder` which represents
the element contained within a holder `div`. The wrapper div is the `ElementHolder.ss` template.

To customise the ElementEditor in the CMS you will need to use the SilverStripe JS Injector to apply transformations
to the necessary React components. [See here](https://docs.silverstripe.org/en/4/developer_guides/customising_the_admin_interface/how_tos/customise_react_components/)
for more information.

### Limit allowed elements

You may wish to only enable certain elements for the CMS authors to choose from rather than the full set. This can be
done according to various page types:

```yaml
Page:
  allowed_elements:
    - DNADesign\Elemental\Models\ElementContent
```

Likewise, you can exclude certain elements from being used.

```yaml
Page:
  disallowed_elements:
    - YourCompany\YourModule\Elements\ElementContact
```

### Sharing elements between pages

By default the page to element relationship is a "has one", meaning you cannot share elements between pages. If this
functionality is desired, you could take a look at the [silverstripe-elemental-virtual](https://github.com/dnadesign/silverstripe-elemental-virtual)
module which helps to achieve this.

### Defining your own elements

An element is as simple as a PHP class which extends `DNADesign\Elemental\Models\BaseElement`, and a template to go
with it (unless you want it to use the default template). After you add the class, ensure you have rebuilt your
database and reload the CMS.

```php
<?php

use DNADesign\Elemental\Models\BaseElement;

class MyElement extends BaseElement
{
    private static $singular_name = 'my element';

    private static $plural_name = 'my elements';

    private static $description = 'What my custom element does';

	public function getCMSFields()
    {
        $fields = parent::getCMSFields();

        // ...

        return $fields;
    }

    public function getType()
    {
        return 'My Element';
    }
}
```

#### In-line Editing

By default elements can be edited in the CMS using an inline form where all your elements appear together. For elements 
that are more complex you can disable the in-line edit form by setting `private static $inline_editable = false` in your
element class. A `GridFieldDetailForm` will be used to edit blocks that are not in-line editable. The default is that all elements are in-line editable.

### Defining your own HTML

`MyElement` will be rendered into a `MyElement.ss` template with the `ElementHolder.ss` wrapper. Changing the holder
template can be done via YAML, or by using a `$controller_template` on your subclass.

```php
private static $controller_template = 'MyElementHolder';
```

To customise existing block templates such as `Content` and `Form` templates, copy the relevant files from
`vendor/dnadesign/silverstripe-elemental/templates` to your theme. When doing this, ensure you match the folder
structure (PHP class namespace) to ensure that your new template version takes priority.

**Note:** The default set of elements follow the [BEM (Block Element Modifier])(http://getbem.com/) class naming
convention, which allows developers to style individual parts of the DOM without unnecessarily nested CSS. Where
possible, we encourage you to follow this naming system.


#### Position Helpers

In your `BaseElement` template you can use the following variables for additional
logic or styling helpers. They behave in the same way traditional `SS_Viewer`
methods work either returning a `Boolean`, `String` or a `Int`

{'fraction_non_alphanumeric': 0.09807107663277073, 'fraction_numerical': 0.0022014886256421008, 'mean_word_length': 5.288398154251813, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 3, 'https://': 60, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1106015', 'n_tokens_mistral': 5653, 'n_tokens_neox': 5422, 'n_words': 1744}