Theme Configuration File

The theme configuration file config.php is central to a theme. It contains content type and field definitions which define the "backend" part of a theme which stores content in the database. It consists of two parts: general information about a theme and content type and field configuration.

General information about the theme

Setting Description
#theme-name Name of the theme, for example 'IdeaSpace 360'.
#theme-key The theme key which is used - for example - in event listeners: 'ideaspace-360-photo-sphere-viewer'. It must not contain spaces or any special characters.
#theme-version Example: '1.0'.
#ideaspace-version The minimum required IdeaSpaceVR version to run this theme. Example: '>=1.0.0'.
#theme-description A descriptive text.
#theme-author-name The name of the author.
#theme-author-email The e-mail address of the author.
#theme-homepage The website URL of the theme.
#theme-keywords Keywords, comma separated. Example: 'photo sphere, gaze input navigation, mobile, 360, photography'.
#theme-view The main view template file. Example: 'scene' which translates to scene.blade.php.

Content type and field configuration

This part of the file defines which content the user can enter, upload or configure when a new space is created or edited.

IdeaSpaceVR - Building Basic VR Theme

The theme configuration file (config.php) can define one or many content types. And each content type can define one or many fields. Each field is described by a #type and other parameters. Take a look at Field Type Reference which lists all available fields and types.

Setting Description
#label Label of the content type.
#description The description of the content type.
#max-values How many items of this content type can be created. Possible values are 'infinite' or a number.
#fields Fields configuration. See Field Type Reference.

Example: IdeaSpace 360 theme

return [

  '#theme-name' => 'IdeaSpace 360',
  '#theme-key' => 'ideaspace-360-photo-sphere-viewer',
  '#theme-version' => '1.0',
  '#ideaspace-version' => '>=1.0.0',
  '#theme-description' => 'Photo sphere viewer with navigation menu in VR. Attach text annotations to your photo spheres.',
  '#theme-author-name' => 'IdeaSpaceVR',
  '#theme-author-email' => '[email protected]',
  '#theme-homepage' => 'https://www.ideaspacevr.org/themes',
  '#theme-keywords' => 'photo sphere, gaze input navigation, mobile, 360, photography',
  '#theme-view' => 'scene',

  '#content-types' => [

    'text-notes' => [
      '#label' => 'Text Notes',
      '#description' => 'Manage your text notes which are attached to your photo spheres.',
      '#max-values' => 'infinite',
      '#fields' => [

        'note' => [
          '#label' => 'Text Note',
          '#description' => 'Enter some text.',
          '#help' => 'The text note can be attached to a photo sphere.',
          '#type' => 'textfield',
          '#maxlength' => 140,
          '#contentformat' => 'text',
          '#required' => true,
        ],

      ], /* fields */
    ], /* notes */

    'photo-spheres' => [
      '#label' => 'Photo Spheres',
      '#description' => 'Manage your photo spheres.',
      '#max-values' => 'infinite',
      '#fields' => [

        'title' => [
          '#label' => 'Photo Sphere Title',
          '#description' => 'Enter a title.',
          '#help' => 'Enter a title for this photo sphere (optional). The title is shown after the photo sphere has been loaded.',
          '#type' => 'textfield',
          '#maxlength' => 140,
          '#contentformat' => 'text',
          '#required' => false,
        ],

        'photo-sphere' => [
          '#label' => 'Photo Sphere',
          '#description' => 'Upload a photo sphere image.',
          '#help' => 'Photo sphere image in equirectangular projection format.',
          '#type' => 'photosphere',
          '#required' => true,
          '#file-extension' => ['jpg', 'png'],
        ],

        'attach-text-notes' => [
          '#label' => 'Info Notes',
          '#description' => 'Add some text notes to the photo sphere.',
          '#help' => 'Add some contextual information by attaching text notes to your photo sphere.',
          '#type' => 'position',
          '#maxnumber' => 10,
          '#required' => false,
          '#content-type-reference' => 'text-notes',
          '#field-reference' => 'photo-sphere',
        ],

      ], /* fields */

    ], /* photo-spheres */

  ], /* content types */

];

There are two content types defined: text-notes and photo-spheres. Text notes can be attached to photo spheres. The field attach-text-notes (part of content type photo-spheres) defines that items of the content type text-notes can be positioned and attached to photo spheres.

Take a look at Content Types and Field Types which lists all available fields and types.

Internationalization (i18n) of a theme

Theme labels, description and help texts defined in the theme config.php file or any text in a theme template can be translated into other languages.

First, let's focus how to internationalize the config.php file.

The first step is to put all text in external language files inside the lang directory of the theme and we just use a unique key for each text in the config.php file. Each of these keys reference a text inside a language file. We have one language file per language, for example one for english, one for german or french.

If you switch the language for your IdeaSpaceVR installation (in Settings), the theme translations are shown according to the selected language when creating or editing a space.

lang directory structure

lang/en/
lang/de/
lang/fr/
etc.

Each language has its own directory within the lang directory. And each language has its own language files, for example:

lang/en/my_texts.php or

lang/de/my_texts.php

Key example

Keys reference texts in language files.

my_texts.text_notes

The first part of the key (my_texts) is the file name of the language file (in lang/en/my_texts.php). The second part of the key (text_notes) is the variable name in the language file.

This is a config.php example using language keys:

return [

  '#theme-name' => 'IdeaSpace 360',
  '#theme-key' => 'ideaspace-360-photo-sphere-viewer',
  '#theme-version' => '1.0',
  '#ideaspace-version' => '>=1.0.0',
  '#theme-description' => 'Photo sphere viewer with navigation menu in VR. Attach text annotations to your photo spheres.',
  '#theme-author-name' => 'IdeaSpaceVR',
  '#theme-author-email' => '[email protected]',
  '#theme-homepage' => 'https://www.ideaspacevr.org/themes',
  '#theme-keywords' => 'photo sphere, gaze input navigation, mobile, 360, photography',
  '#theme-view' => 'scene',

  '#content-types' => [

    'text-notes' => [
      '#label' => 'my_texts.text_notes',
      '#description' => 'my_texts.text_notes_description',
      '#max-values' => 'infinite',
      '#fields' => [

        'note' => [
          '#label' => 'my_texts.text_note',
          '#description' => 'my_texts.enter_some_text',
          '#help' => 'my_texts.text_note_help',
          '#type' => 'textfield',
          '#maxlength' => 140,
          '#contentformat' => 'text',
          '#required' => true,
        ],

      ], /* fields */

    ], /* notes */

    ] /* content types */

];

Let's look into the lang/en/my_texts.php language file:

<?php

return [

    'text_notes' => 'Text Notes',
    'text_notes_description' => 'Manage your text notes which are attached to your photo spheres.',
    'text_note' => 'Text Note',
    'enter_some_text' => 'Enter some text.',
    'text_note_help' => 'The text note can be attached to a photo sphere.',

];

That's where the texts are referenced.

If we wanted to have a german translation we would add a lang/de/my_texts.php file:

<?php

return [

  'text_notes' => 'Text Notizen',
  'text_notes_description' => 'Organisiere deine Text Notizen fuer deine 360 Grad Fotos.',
  'text_note' => 'Text Notiz',
  'enter_some_text' => 'Schreibe einen Text.',
  'text_note_help' => 'Die Text Notiz kann an einem 360 Grad Foto plaziert werden.',

];

Internationalization of text in theme template files

For example views/index.blade.php or views/scene.blade.php.

Inside your template file you can use the following code to internationalize your text.

Example:

{{ trans('image-gallery::description.intro_instruction') }}

image-gallery is the #theme-key from the config.php file and the reference of the text is description.intro_instruction (from lang/description.php with the key intro_instruction).