#Global Content

Introduction

Global Content is meant to give developers an easy and quick way to add small pieces of content to a site that an administrator can then freely change as they see fit. Of course there are many options for content already like nodes and other entities to fill out a page, but these are usually overkill when just talking about a text in a custom form or similar.

This is what Global Content is for. Very small pieces of content in places where it's usually quite bothersome to embed any other type of content entity.

Usage

For most usecases using a Global Content is as easy as calling the gc() function whenever you need it.

    $build = gc('example-machine-name');

This returns a render array with all the necessary cacheability information and context menus for the Global Content in question. There are also other variants for more specialised uses like gci() which works like gc() except without a context menu in case the extra markup is undesired, but is still a render array. Last we have gcs() which just delivers a rendered string, but cacheability is lost and must be taken care of manually.

There are also Twig functions with the same names...

    <p>{{ gc('example-machine-name') }}</p>

Defining Global Content

When defining new Global Content you need to create a MODULE.globalcontent.yml file or THEME.globalcontent.yml which will include definitions for all the global content needed for that module or theme.

example-machine-name:
  type: textfield
  title: Example title
  description: A Global Content used as an example for documentation.
  category: Example Category
  group: Example group
  subgroup: Example group
  default:
    en: 'English test title'
    da: 'Dansk test titel'
  options:
    translatable: TRUE
    token_types:
      - node

Every definition starts with a unique machine name for the Global Content followed by the following properties:

• type: The type of field for this particular Global Content. You can see a list of types further down includes any options they might have.
• title: The administration interface name for the Global Content. This string is will be translated through t() so write it in english and provide a translation for it for other languages.
• description: (Optional) The administration interface description of the Global Content. This string is also translated through t().
• category: (Optional) The category for administration interface to put the Global Content in. Translated through t(). Defaults to "Miscellaneous".
• group: The group for administration interface to organize it together with other Global Content. If the same group name is used in multiple categories it will create separate groups. Translated through t().
• subgroup: (Optional) An optional further organization of the administration interface within the same group. Translated through t().
• default: (Optional) A default value for the Global Content so it will not be empty upon being created. Should be provided as an array with language codes as index making it possible to provide translations upon creation.
• options: (Optional) A field might need additional information depending upon type. This will be explored in detail under each field type. However two options are more universal:
  • translatable: (Optional) Whether or not the Global Content can be translated. A phone number or e-mail might not need to change between languages and so will only have one version. Sets the language to "Not applicable" and default value should be provided with langcode "zxx". Defaults to TRUE.
  • token_types: (Optional) If the field type supports tokens and token support has been activated, the Global Content will have access to global tokens. If you want to provide access to further token types these need to be specified here as an array. This will also require you to provide extra data for these token types. See more under Advanced Usage.

Field Types

textfield

• Tokens: yes
• Value: string

Provides a simple plain text field for entering short texts containing no markup.

textarea

• Tokens: yes
• Value: string

Same as textfield, but for longer texts and provided with multiple lines for editing.

email

• Tokens: yes
• Value: string

Same as textfield, but with validation for e-mail addresses.

number

• Tokens: no
• Value: integer

Gives a field for entering a number integer with validation and support for mobile number input.

text_format

• Tokens: yes
• Value: string
• Options:
  • format: (Optional) The text format initially used for this field. Defaults to the configured default setting.
  • allowed_formats: (Optional) An option to restrict the allowed text formats for this field. Defaults to the configured default setting.

The field gives access to a Rich Text editor enabling the administrator to use markup for formatting. The default text format and allowed formats can be configured for all text_format fields on the Global Content settings page.

date

• Tokens: no
• Value: DrupalDateTime
• Options:
  • format: (Optional) The date format used to display this field. Defaults to the configured default setting.

This field gives a date picker for selecting a date to be displayed in a selected Drupal date format. The default date format can be configured for all date fields on the Global Content settings page.

datetime

• Tokens: no
• Value: DrupalDateTime
• Options:
  • format: (Optional) The date format used to display this field. Defaults to the configured default setting.

This field gives a date picker for selecting a date and time to be displayed in a selected Drupal date format. The default date format can be configured for all datetime fields on the Global Content settings page.

url

• Tokens: yes
• Value: Url
• Options:
  • internal: (Optional) Whether the url can be an internal url on the site. Defaults to TRUE.
  • external: (Optional) Whether the url can be an external url on the world wide web. Defaults to TRUE.

The field allows the administrator to specify an url, either internal, external or both. If internal urls are allowed it will give suggestions for nodes, but any relative url is allowed.

link

• Tokens: yes
• Value:
  • title: string
  • url: Url
• Options:
  • internal: (Optional) Whether the url can be an internal url on the site. Defaults to TRUE.
  • external: (Optional) Whether the url can be an external url on the world wide web. Defaults to TRUE.

The field allows the administrator to specify an url, either internal, external or both and a title which together creates a link. If internal urls are allowed it will give suggestions for nodes, but any relative url is allowed.

button

• Tokens: yes
• Value:
  • title: string
  • url: Url
• Options:
  • internal: (Optional) Whether the url can be an internal url on the site. Defaults to TRUE.
  • external: (Optional) Whether the url can be an external url on the world wide web. Defaults to TRUE.

The field allows the administrator to specify an url, either internal, external or both and a title which together creates a button. If internal urls are allowed it will give suggestions for nodes, but any relative url is allowed. The field type default to a link with the button class when rendered, but can be configured to use any other class as appropiate to the theme on the site.

entity

• Tokens: no
• Value: Entity[]
• Options:
  • entity_type: (Optional) The type of entity to be selected. Defaults to "node".
  • multiple: (Optional) Whether you can select multiple entities. Defaults to FALSE.
  • target_bundles: (Optional) If you want to restrict the which bundles can be selected for the field. Defaults to all bundles.
  • view_mode: (Optional) Specifies what view mode the entities will be rendered with. Defaults to "full".
  • summary_view_mode: (Optional) Specifies what view mode the entities will be rendered with in the administration interface. Defaults to "teaser".

This field can allow the administrator to select a single or multiple entities of a certain type using an autocomplete field.

media (Separate module)

• Tokens: no
• Value: Media[]
• Options:
  • multiple: (Optional) Whether you can select multiple media entities. Defaults to FALSE.
  • target_bundles: (Optional) If you want to restrict the which media types can be selected for the field. Defaults to all types.
  • view_mode: (Optional) Specifies what view mode the media entities will be rendered with. Defaults to "full".
  • summary_view_mode: (Optional) Specifies what view mode the media entities will be rendered with in the administration interface. Defaults to "media_library".

This field can allow the administrator to select a single or multiple media entities using an autocomplete field. Sadly Drupal Core still does not support using Media Library outside of fields yet.

icon (included in DDS Icons)

• Tokens: no
• Value: Icon ID
• Options:
  • width: (Optional) The width of the icon when displayed. Defaults to 100.
  • height: (Optional) The height of the icon when displayed. Defaults to 100.

This field can allow the administrator to select a single icon using the icon library.

Advanced usage

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

ViewableGlobalContent objects allow you to set the following properties before rendering the Global Content:

• SetOption(key, value): You can set an option otherwise specified in the globalcontent.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 Global Content 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 GlobalContent including tokens and with cache tags for all depending content. Useful for when you use Global Content 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 gc().
• toRenderableInline(): The inline rendering method as a render array. Same as gci().
• toString(): The rendered Global Content but as a string. Same as gcs().
• 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.