New API - changes in generator.yml structure

[ioleo]

Useing Symfony2 Config Component

I plan to implement useing symfony2 config compoment to validate generator YAML files. This is also a great opportunity to improve our API (and for obvious reasons, we can only do that now, before v2.0-stable).

New API - what needs improvement?

I'd like to start a discussion about the pros and cons of current API. Each of us used Admingenerator for diffrent projects and faced diffrent problems. I'd like to hear your thoughts. To ignite the discussion, I'll throw in a bunch of thoughts.

In my projects I had multiple custom object actions. To not repeat myself and share the configuration between builders, I had them defined in the global params section.

However, there was no easy way to overwrite/customize the list per builder. Eg. if I had:

params:
  object_actions:
    custom1: ~
    custom2: ~
    edit: ~
    show: ~
    delete: ~

But on Show builder, I'd like to display all of them... except show (for obvious reasons). By the same argument, on edit builder, I want to remove the edit action. On Action builder I wanted only custom1 and custom2 (without the default actions edit/show/delete).

Also, in some cases I wanted to simply change the order. Eg. in Show builder: custom2, custom1, while in Edit builder custom1, custom2.

Note: later on, we've implemented a very hacky trick, that if you set your field to null, it will read the global config.. and merge it... why hacky? Well, have a look at that code and tell me it's easy to read :)

Another example - to allow translateing messages from generator files, we've introduced the parameter bag feature, which provides a structured syntax that (if detected) will output a call to translator service with the correct parameters.

However, over time I feel like generator files are "pandora boxes" where you do everything:

• configure basic parameters (like generator used, translation domain, namespace or model)
• configure fields
• configure forms
• add (and translate) labels, help blocks, and other messages
• configure actions
• configure filters

This is OK for a VERY SIMPLE project. But as soon as your project grows in size or complexity, you end up with huge generator files, which are almost unreadable.

I'd like to change that. I'd like to move some things out of the generator file. I think the "generator" file should be only for basic configuration (to generate a "stub") and all those details (like form configuration) should live in seperate PHP classes.

So... the "ideal" generator for me, would only contain some basic parameters, and "switches" that turn on/off certain features. Eg. say you want to generate ONLY the show builder.

This could also improve the cache generation time - if a feature was disabled, certaint blocks of code would be skipped.

[ioleo]

/cc @sescandell @ksn135

I'm still thinking about how it should look like. As soon as I have some solid idea in my head, I'll post it here.

[sescandell]

Hi @loostro

Don't have time to make something more precise for now, so very quickly:

• I agree with you, we need to try to move some things and make YAML files easier to use (if possible)
• Moving to the Config/Processor Component is something we should really do (IMO)
• But, I really thing the strength of this project is to mainly configure everything from YAML files. I don't want this project to be "a clone or heavy thing of Sonata Configuration". There is some thing that should not be in YAML (like form specific configurations, and that's why we introduced by the past the formOptions PHP method). But for some other things, it's working pretty well I think. I agree we should try to make YAML easier to read. I think the main tricky thing for users is the actions part configuration (you need to set it in the global space, then in the builder, then per builder...). So I agree with you, this should be improved. About Filters, like you, I think filters belongs to list builder. For now, if I'm not wrong, there is just one little bug to resolve about that (getting filters not from the list display parameter) and it should be fine... oh well... no... because if you want to customize filters form / options... OK, I'll try to think about that use case too on my side.

I'll be more precise, contribute more on that subject as soon as possible

[ioleo]

I've been thinking about this, and I've come up with an idea. We could split the configuration into several YAML files. Eg.:

• Model-generator.yml general config, switching certain features on/off (eg. "do not generate excel builder")
• Model-actions.yml actions configuration (the "avaliable" actions and their config)
• Model-fields.yml fields/columns configuration

An example of what it could look like:

# Model-generator.yml
generator:          admingenerator.generator.doctrine
model:              Acme\DemoBundle\Entity\Model
namespace_prefix:   Acme
concurrency_lock:   ~
bundle_name:        DemoBundle
i18n_catalog:       Model
pk_requirement:     \d+
builders:
    list: # enables builder with custom features on
        filters:    false
        sorting:    false
        pagination: false
        # this only decides which actions are used and in what order
        # the configuration is defined in "Model-actions.yml"
        generic_actions: [ 'custom1', 'new' ]
        object_actions: [ 'custom1', 'custom2', 'edit', 'show', 'delete' ]
        batch_actions: [ 'custom2', 'delete' ]
    new:      true # enables builder with default features on
    edit:     true
    show:     true
    actions:  true
    excel:    false # disables builder

# Model-actions.yml
generic:
    new: ~ # use the default configuration
    custom1:
        route: custom1genericRoute
        # etc...
object:
    custom1:
        inject_custom_defaults: true # use default custom action configuration for actions builder...
        label: "Custom 1 object action" # ... except the "label", which is explicitly set
    custom2: 
        inject_custom_defaults: true
    edit: ~ # use the default configuration
    show: ~ # use the default configuration
    delete: ~ # use the default configuration
batch_actions:
    custom2:
        inject_custom_defaults: true # use default custom action configuration for actions builder
    delete: ~ # use the default configuration

# Model-fields.yml
fields:
    createdAt:
        label: "Created at"
        dbType: datetime
        formType: s2a_datetime_picker
        filterType: s2a_datetime_picker
    name:
        label: "Name"
        dbType: text
        formType: text
        filterType: text
   # etc

What do you think?

[ksn135]

Just my $0,02...
IMHO, we should re-think _routing configuration_, may be make it more comfortable to developer. Let me explain myself. In legacy symfony 1.4 to to create new custom action someone needs to specify action name, label and may be optional icon. You don't need to specify route and route parameters (of course you CAN if you want to), new custom action in sf1.4 automatically generate route with parameter. May be we need something similar to this legacy behaviour? For example, automatically add routes for all custom actions via RoutingLoader class ?
When you add new custom action, then s2a automatically create route:

        'custom' => array(
                    'pattern'      => '/action/{pk}/custom',
                    'defaults'     => array(), 
                    'requirements' => array('pk' => '\d+'),
                ),

[ksn135]

And for me separation of ONE *-generator.yml per module to SEVERAL files is pure evil... )
Just imagine, I have now about 20 entities and 20 *-generator.yml files in one bundle.
When this quantity will become about 60 files... It's really too much...
We should think about move some configuration items (fields? action?) in ONE place, may be one(three?) global file(s?) with reasonable defaults ?

[ksn135]

Ought! What's about ability to include one YAML file from another ?
If someone (like @loostro) wants to have separated YAML config files then he should use some kind of include directive. And opposite if someone (like me) wants to use one big flat YAML config file per module – no problem, too.

[calvera]

I agree with @ksn135 that one file per entity is better than three... frankly speaking I like yaml files like they are 😃

dumb idea: did you think about using annotations? The cons are that admin annotations are not separated from non-admin and too much work for implementation...

[ioleo]

Another idea:

• add support for Model-generator.php files (which must have getConfig() method returning an array)
• deprecate (but not remove!) Model-generator.yml config
• add "convert YAML config to PHP config" command

The cacheWarmer finds:

• all -generator.yml files
• all -generator.php files
• it reads the params.model (eg. Acme\DemoBundle\Entity\Post)
• if it finds both PHP and YAML config for the same model, it will use PHP config
• for PHP config -> it will inject container service and run getConfig
• for YAML config -> it will use Yaml::parse to get the config
• then the config is validated useing Symfony2 config component
• the API (config structure) does not change

This would have various benefits:

• the API does not change
• there is only one config file (PHP or YAML) per Model
• it's fully backwards compatible (the YAML config is still supported)
• for advanced configurations (where you want to merge/unset elements of global config or you need some service like Translator, or Routeing) you can convert your YAML to PHP config, then "customize it"
• if the PHP config proves to be better, we can deprecate YAML config (and remove it in future versions)
• smoother transition from legacy bundle to new-unstable bundle

What do you think?

[ioleo]

Example ModelGenerator.php:

<?php

namespace Acme\DemoBundle\Resources\config;
// actually we should probably put it in a diffrent directory...

use Symfony\Component\DependencyInjection\ContainerAware;

class ModelGenerator extends ContainerAware
{
    const MODEL = 'Acme\DemoBundle\Entity\Model';

    public function getConfig()
    {
        return array(
            'generator'        => 'admingenerator.generator.doctrine',
            'model'            => self::MODEL,
            'namespace_prefix' => 'Acme',
            'bundle_name'      => 'DemoBundle',
            'concurrency_lock' => null,
            'i18n_catalog'     => 'Model',
            'pk_requirement'   => '\d+',
            'builders'         => array(
                'list' => array( /* list config */ )
                // other builders...
            )
        );
    }
}

The power of useing PHP is obvious.. you can define getObjectActions method.. and then, for list use "object_actions" => $this->getObjectActions(), while for edit you can use:

<?php

public function getObjectActionsForEdit()
{
    $objectActions = $this->getObjectActions();
    unset($objectActions['delete']);
    return $objectActions;
}