Advanced usage

Should the need for more advanced usage of Atoms be required then it's recommended to use the AtomsViewBuilder service. Using this service you get access to ViewableAtom objects via the get() method and these are much more adjustable than simply using atom().

As a shortcut you can use atom_view() to get a ViewableAtom without having to get the AtomsViewBuilder service.

ViewableAtom objects allow you to set the following properties before rendering the Atom:

• SetOption(key, value): You can set an option otherwise specified in the atoms.yml file. Maybe in certain situations you want to change things.

• SetOptions(values): Same as the above but using an associative array with all options for the Atom at once.

• SetTokenData(data): If more than just the globally available tokens must be accessible, the appropriate data must be delivered with this method.

It also gives you access to lots of information useful rendering or other usage:

• getCacheableMetadata(): The CacheableMetadata needed to render this Atom including tokens and with cache tags for all depending content. Useful for when you use Atom as a string and need to add it's cacheability yourself.

• getLangcode(): Sometimes a translation is not available for a requested language. This method returns the langcode found to fit the best.

And lastly you have several options for rendering or other output:

• toRenderable(): The standard rendering method as a render array. Same as atom().

• toString(): The rendered Atom but as a string. Same as atom_str().

• toValue(key = ""): Maybe you just want the value of the field and not any rendered version. The type of value returned depends on the field type as seen above.