Chunk/Snippet properties

[pk-informatics]

Hi,

Howto define chunk properties within the chunk docblock?

Kind regards, pk

[fireproofsocks]

Properties are not currently supported in the DocBlock -- this would require creating seed data that references the related data (see https://github.com/craftsmancoding/repoman/wiki/Sample-Objects as an example of how related data is referenced). I haven't put that together yet, so I've marked this both as a feature request and a documentation issue. It would be nice to reference the properties directly in the DocBlock, but it may be cleaner to require a seed file (similar to how TVs are referenced by Templates).

I haven't looked into property sets much in my own coding, and I'm starting to see why -- the architecture around this feels awkward. I think I found a glitch in the GUI too (in 2.3.2). Essentially the properties are ad-hoc key/value pairs added to the element's "properties" column (a text field), e.g. something using the format:

[
  {
    "name": "sampletextarea",
    "desc": "",
    "xtype": "textarea",
    "options": [],
    "value": "Whoa Nellie Yo!",
    "lexicon": "",
    "overridden": false,
    "desc_trans": "",
    "area": "OTher Area",
    "area_trans": "OTher Area",
    "menu": null
  },
  {
    "name": "sampletext",
    "desc": "text field",
    "xtype": "textfield",
    "options": [],
    "value": "Gnus?",
    "lexicon": "",
    "overridden": false,
    "desc_trans": "text field",
    "area": "Test Area",
    "area_trans": "Test Area",
    "menu": null
  }
]

Tables involved are:

• modx_property_set
• modx_element_property_sets

I think the modx_property_set.properties field is supposed to contain the serialized data defining the property set (but it seems to be failing). The modx_element_property_sets table joins to all element tables switched by the element_class column, e.g. join Chunk 123 with property set "ProductionDefaults" or some such.

To support a DocBlock reference here, the following would be required:

1. Add some valid seed data for a modPropertySet object specifying keys for name, category, description, and an array of properties.
2. Update the build logic to pack in modPropertySet into a category
3. Update DocBlock parsing so you can reference a property set by name, e.g. @PropertySet -- but I'm unclear as to this would work if you wanted to override some of the inherited properties and leave others alone.

I think, however, that this is pushing the DocBlock syntax too far -- when we want to attach something as detailed as a property set, perhaps it's best to add the Chunk/Snippet/Plugin as seed data?

However... a nicer implementation here would be easy support for any exported property sets?

[pk-informatics]

Thank you for the info - but how the chunk and its properties get connectet if i'll try it over db seeds?

[pk-informatics]

even with http://forums.modx.com/thread/94986/chunk-property-sets-in-transport-chunks-php i have not really an idea howto use it with repoman...

[fireproofsocks]

Knowing how a transport package does this is not terribly useful, unfortunately. It's all a matter of knowing the class relations inside of MODX -- you gotta get really really familiar with that any time you seed data -- that's why I added the graph function as one of repoman's core functions. But the architecture is weird here. I don't think I can test this until the GUI bugs are resolved.

Setting properties on a chunk would behave exactly like setting any other property with seed data. Something like

// file: model/seeds/modChunk.php
return array(
   'name' => 'myChunk',
   'description' => 'Yada',
   'snippet' => 'This is my chunk content',
   // ... etc... other properties here, see the database or the modx.mysql.schema.xml
   'properties' =>     array(
      array(
        "name" => "sampletextarea",
        "desc" => "",
        "xtype" => "textarea",
        "options" => [],
        "value" => "Whoa Nellie Yo!",
        "lexicon" => "",
        "overridden" => false,
        "desc_trans" => "",
        "area" => "OTher Area",
        "area_trans" => "OTher Area",
        "menu" => null
      ),
      array(
        "name" => "sampletext",
        "desc" => "text field",
        "xtype" => "textfield",
        "options" => [],
        "value" => "Gnus?",
        "lexicon" => "",
        "overridden" => false,
        "desc_trans" => "text field",
        "area" => "Test Area",
        "area_trans" => "Test Area",
        "menu" => null
      )
    )
)

That's untested, but since this is all built on repeating patterns, it should work so long as you know the object relations. It looks like a similar object could be created for the modPropertySet object.

I'll add an example to the docs once I work out the specifics here, but the way that MODX has implemented property sets here appears somewhat convoluted, so I don't know how or if repoman can smoothe this over.

[fireproofsocks]

Ok, after studying this I finally implemented a solution: properties will be defined in-line in the DocBlock comments using the @param declaration. In order to accomplish this, I extended the DocBlock syntax a bit further to cover default values and options. This solution is relatively straight-forward for the developer and it will lead to better code documentation, so I think it is a win-win.

To implement properties, simply declare @param in your DocBlock, e.g. :

@param textfield $tpl Choose a chunk. default=MyChunk
@param list $choose A dropdown default=int options={"str":"String","int":"Integer"}

The "default" bit defines the value of the property (i.e. the default value). The "options" can be used to specify an JSON hash (or a JSON array) in the format "value":"text".

I will add a tutorial demonstrating this.

525e288..4c78aa2 master -> master