Provide documentation on setting field values programmatically

[MoritzLost]

I'm working on a migration script right now where I need to create linkfield values programmatically. The README is lacking instructions on how to set values programmatically (in PHP), which fields are supported, how to switch link types, etc. By trial and error as well as inspecting the HTML code for the field I found that this seems to work:

$entry->setFieldValue('my_typed_link_field', [
    'type' => 'url',
    'cpForm' => [
        'url' => [
            'linkedUrl' => 'https://example.com'
        ],
    ],
    'customText' => 'Link text for example.com',
];

Is this the best way to set the value? Is there a simpler approach? Also, the nested array with cpForm as a key is kind of ... awkward to use. Not sure if I'm doing it wrong.

Anyway, adding a section to the README that explains how to set values programmatically would be really helpful!

[sebastian-lenz]

Hi @MoritzLost! Well, that's not the most common use case and it did not come up until now. I assume you are using version 1 of the plugin cause if I remember correctly the cpForm subsection as removed. You should be able to set the link field values like you can see it in the test cases:

$entry->setFieldValue('my_typed_link_field', [
  'ariaLabel'   => 'my aria label',
  'customText'  => 'my custom text',
  'title'       => 'my title',
  'type'        => 'url',
  'value'       => 'http://www.google.de',
]);

Or for entry links:

$entry->setFieldValue('my_typed_link_field', [
  'type'        => 'entry',
  'value'       => 102,
]);

You can find a list of all supported properties right here.

[MoritzLost]

Hi @sebastian-lenz, thanks a lot for the reply!
I'm using the beta of version 2 (Composer: "sebastianlenz/linkfield": "^2.0-beta"), the cpForm still appears in the source code of the editor interface, at least in my test installation. But your example works well for me, the thing I was missing was that the URL is passed using the value key.

Something like the example code you linked to would be handy to have in the README. I didn't find that since I was looking in the master branch. I guess it's not there anymore since you moved that to the ForeignField class in your utility library? In this case I'd really recommend you include just your code example above in the README. Just by looking through the source code I had a hard time finding which attributes where supported, especially given the additional level of abstraction with the ForeignField class.

Anyway, thanks for the support!

[sebastian-lenz]

Ah, please be cautious, the sample I've given was for version 1 of the plugin. The test case ist still present in the master branch. So for version 2 the name was changed to linkedUrl:
https://github.com/sebastian-lenz/craft-linkfield/blob/master/tests/BasicTest.php#L128

$entry->setFieldValue('my_typed_link_field', [
  'ariaLabel'   => 'my aria label',
  'customText'  => 'my custom text',
  'title'       => 'my title',
  'type'        => 'url',
  'linkedUrl'   => 'http://www.google.de',
]);

Or linkedId:
https://github.com/sebastian-lenz/craft-linkfield/blob/master/tests/BasicTest.php#L94

$entry->setFieldValue('my_typed_link_field', [
  'type'        => 'entry',
  'linkedId'    => 102,
]);

The available properties have changed as v2 introduced dedicated link models, there is no longer a central list of properties, instead you have to look at the model classes to find out which properties are supported.

• https://github.com/sebastian-lenz/craft-linkfield/blob/master/src/models/Link.php
• https://github.com/sebastian-lenz/craft-linkfield/blob/master/src/models/element/ElementLink.php
• https://github.com/sebastian-lenz/craft-linkfield/blob/master/src/models/input/InputLink.php

[nstCactus]

I would love it if you could include this in the README.md, or at least of link to your previous comment!

[nstCactus]

Also note that when programatically creating a value for a linkfield that has the Enable element url and title cache setting enabled, it's a good idea to call \lenz\linkfield\listeners\CacheListener::onClearCache() and wait for queue jobs to have run, otherwise links pointing to entries might not render.

[sanderpotjer]

@nstCactus thanks for that cache tip, exactly the issue I was facing :-)

+1 for adding this to the docs!