<commit_before># CMS Blocks

Blocks are elements used in the CMS Module to display and configure data. Blocks are dropped into the placeholders of a [CMS Layout](app-cmslayouts.md). An example of a Block could be a paragraph tag where the user can add the content. LUYA CMS Module is shipped with some default Blocks, but you can create your own elements.

## Create a new Block

> use `./vendor/bin/luya cms/block/create` console command to generate a Block.

You can add Blocks to your application or to a module. In either case, the folder where the blocks are stored must be named as **blocks**. Additionaly blocks should have the suffix `Block`. 

For example, we create a Block `TextTransformBlock` and store it in `app/blocks` or `app/modules/yourmodule/blocks`.

> In 1.0.0-beta8 the new *PHP BLOCKS* was introduced. This allows you to use PHP Views instead of TWIG Templates. In order to use The new PHPBlocks you can extend the block from {{\luya\cms\base\PhpBlock}}. PhpBlocks does automatically requires a view file and the `twigAdmin()` is replaced by `admin()` method.

This is what the `TextTransformBlock` could looke like in your code:

```php
<?php
namespace app\blocks;

class TextTransformBlock extends \luya\cms\base\PhpBlock
{
    public function icon()
    {
        return 'extension'; // https://design.google.com/icons/
    }
    
    public function name()
    {
        return 'Transformed Text';
    }
    
    public function config()
    {
        return [
            'vars' => [
                ['var' => 'mytext', 'label' => 'The Text', 'type' => 'zaa-text'],
            ],
        ];
    }

    public function extraVars()
    {
        return [
            'textTransformed' => strtoupper($this->getVarValue('mytext')),
        ];
    }

    public function admin()
    {
        return 'Administrations View: {{ vars.mytext }}';
    }
}
```

As we have switched to PHPBlock by default (in beta8) you now have to create also a view file, which is located in the view folder of your application: `app/views/blocks/`. The view itself must have the same name as the class name of your block: `TextTransformBlock.php`. 

In the example above, the view file should looke like this:

```php
<?php
/**
 * @var $this \luya\cms\base\PhpBlockView
 */
?>

<?php if ($this->varValue('mytext')): ?>
    <h1><?= $this->extraValue('textTransformed'); ?></h1>
<?php endif; ?>
```

In order to retrieve values from configurations (`$this->[METHOD]`):

|Type|Method
|----|------
|var|{{luya\cms\base\PhpBlockView::varValue}}
|cfg|{{luya\cms\base\PhpBlockView::cfgValue}}
|extra|{{luya\cms\base\PhpBlockView::extraValue}}
|placeholder|{{luya\cms\base\PhpBlockView::placeholderValue}}

Check the {{\luya\cms\base\PhpBlockView}} for full method reference to use inside the php block view.

#### Register and import

After creating a Block, you have to *Import* it into your application. The reason behind the import process is to avoid rely on database structure and to work with php files you can also check into version controller system. Run the [Import Command](luya-console.md):

```sh
./vendor/bin/luya import
```
<commit_msg>Update app-blocks.md<commit_after># CMS Blocks

Blocks are elements used in the CMS Module to display and configure data. Blocks are dropped into the placeholders of a [CMS Layout](app-cmslayouts.md). An example of a Block could be a paragraph tag where the user can add the content. LUYA CMS Module is shipped with some default Blocks, but you can create your own elements.

## Create a new Block

> use `./vendor/bin/luya cms/block/create` console command to generate a Block.

You can add Blocks to your application or to a module. In either case, the folder where the blocks are stored must be named as **blocks**. Additionaly blocks should have the suffix `Block`. 

For example, we create a Block `TextTransformBlock` and store it in `app/blocks` or `app/modules/yourmodule/blocks`.

> In 1.0.0-beta8 the new *PHP BLOCKS* was introduced. This allows you to use PHP Views instead of TWIG Templates. In order to use The new PHPBlocks you can extend the block from {{\luya\cms\base\PhpBlock}}. PhpBlocks does automatically requires a view file and the `twigAdmin()` is replaced by `admin()` method.

This is what the `TextTransformBlock` could looke like in your code:

```php
<?php
namespace app\blocks;

class TextTransformBlock extends \luya\cms\base\PhpBlock
{
    public function icon()
    {
        return 'extension'; // https://design.google.com/icons/
    }
    
    public function name()
    {
        return 'Transformed Text';
    }
    
    public function config()
    {
        return [
            'vars' => [
                ['var' => 'mytext', 'label' => 'The Text', 'type' => 'zaa-text'],
            ],
        ];
    }

    public function extraVars()
    {
        return [
            'textTransformed' => strtoupper($this->getVarValue('mytext')),
        ];
    }

    public function admin()
    {
        return 'Administrations View: {{ vars.mytext }}';
    }
}
```

As we have switched to PHPBlock by default (in beta8) you now have to create also a view file, which is located in the view folder of your application: `app/views/blocks/`. The view itself must have the same name as the class name of your block: `TextTransformBlock.php`. 

In the example above, the view file should looke like this:

```php
<?php
/* @var $this \luya\cms\base\PhpBlockView */
?>

<?php if ($this->varValue('mytext')): ?>
    <h1><?= $this->extraValue('textTransformed'); ?></h1>
<?php endif; ?>
```

In order to retrieve values from configurations (`$this->[METHOD]`):

|Type|Method
|----|------
|var|{{luya\cms\base\PhpBlockView::varValue}}
|cfg|{{luya\cms\base\PhpBlockView::cfgValue}}
|extra|{{luya\cms\base\PhpBlockView::extraValue}}
|placeholder|{{luya\cms\base\PhpBlockView::placeholderValue}}

Check the {{\luya\cms\base\PhpBlockView}} for full method reference to use inside the php block view.

#### Register and import

After creating a Block, you have to *Import* it into your application. The reason behind the import process is to avoid rely on database structure and to work with php files you can also check into version controller system. Run the [Import Command](luya-console.md):

```sh
./vendor/bin/luya import
```

{'fraction_non_alphanumeric': 0.11686249603048587, 'fraction_numerical': 0.0022229279136233727, 'mean_word_length': 3.4018169112508736, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 37, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, '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': '1844153', 'n_tokens_mistral': 1901, 'n_tokens_neox': 1806, 'n_words': 739}