Skip to content

Editing Metadata

The Mobile Development Kit language introduced for Visual Studio Code lets you edit and validate Mobile Development Kit metadata using features like auto-completion, validation, and navigation. These features are also supported in Mobile Development Kit component development in cross-application scenarios.

Files with the following extension are supported: .action, .app, .global, .page, .js, .ts, .service, .properties, .cim, and .less.

The Mobile Development Kit language for Visual Studio Code offers the following features:

Auto-Completion

  • Language – shows property suggestions while you are typing, if you move the cursor to a blank place inside an object and insert the trigger character ".
  • Automatically shows the list of available values when you select _Type from the property suggestion list. You can also insert and " after the property _Type to trigger a list of available values.
  • Shows different property suggestions based on the value of the property _Type.
  • Shows all the localization keys specified by the property Localization in the Application.app file when you place the cursor inside the string value of a property in a metadata file, then insert $ for the JSON files and the i18n related client API for rule JavaScript files. Also shows the signatures of the eight types of i18n indicators in the completion list.
  • Displays a list of available values for a file reference if you insert the character ", ' or / in .js files and the character " or / in a file reference, for example, "/{ApplicationName}/{TypeFolder}". When you select a file name, the complete path name is shown beside it.
  • Provides a list of ClientAPI methods in rule JavaScript files.
  • Shows a list of platforms where a value is used when you choose a value (which is platform-aware) from the completion list.
  • Supports both simple target paths and dynamic target paths. This applies to both JSON metadata files and JavaScript rule files. Auto-completion supports both segment name and segment parameter. Enter # to see available segment names that are based on what you have entered for the target path. Enter : to see available values are for the segment immediately before the :. No completion items are provided if the target path you have entered is invalid.
  • Supports simple and dynamic target paths for data binding. For more information, check this documentation.
  • Data binding supports both simple type and complex type. If you are binding to a complex type, then drill down to the property of simple type in the format of {property1/property2/property3} where property3 is a simple type.
  • For some OData related actions, the property Properties auto-completes by parsing the content of the XML file of the service specified in the action. For example, the file .data.xml under the same folder as the service data.service.
  • Supports target children's properties:

    • Service – .service file

      Note

      To use the language features on target properties and the OData target path / binding values, make sure the corresponding service OData metadata XML is available, otherwise, there'll be no auto-completion support for OData relevant values at design time.

      • Fetching service OData metadata from the debugger's appRoot:
        • Right-click the service file and choose MDK: Fetch OData Metadata from the context menu.
        • Enter a user name and password that has Administrator rights.
        • Progress is shown at the bottom left of the Visual Studio Code window, and finishes by showing "The service metadata has been updated completely."
        • The fetched XML file is next to the service file.
    • EntitySet – all the available OData EntitySet name values come from the above service OData metadata XML, so this EntitySet property depends on the value in Service field.

      • The completion list includes: Global / Rule, EntitySet names from the OData metadata XML, and predefined ErrorArchive offline EntitySet name.
      • ReadLink – this property depends on both Service and EntitySet fields. The potential value can be one of the following:
        • Global or rule reference
        • TargetPath
        • Predefined OData annotation value, for example, {@odata.readLink}
        • EntitySetName with filter option, for example, SystemStatuses('I0100')
    • QueryOptions – apply only to .json metadata files. All valid symbols such as keywords, built-in functions, and comparison operators are provided according to OData query option syntax. In addition, when a property is needed, the corresponding ones are provided based on the OData service specified in the application. The following options are supported for this property:
      • $select
      • $expand
      • $filter
      • $orderby
      • $top
      • $skip

    Note

    These features are available only when the Service and EntitySet values can be resolved at design time, that is, there's no support available if the EntitySet is a rule.

Validation

  • If a required property for an object is missing, the PROBLEMS view shows warning messages. These messages also appear in the editor when you hover over the green tilde under the starting brace of the object.
  • If the value of the property _Type for a Mobile Development Kit object is incorrect, the PROBLEMS view shows warning messages. These messages also appear in the editor when you hover over the green tilde under the incorrect value.
  • If a property type is incorrect, for example, if a number value has been assigned to a property of the string type, the PROBLEMS view shows warning messages. These messages also appear in the editor when you hover over the green tilde under the incorrect value.
  • If there is an error in the JSON format, for example, a missing double quote, colon or brace, the PROBLEMS view shows warning messages. These messages also appear in the editor when you hover over the red tilde after the missing character.
  • The Mobile Development Kit language validates the schema of a file specified by a file reference: If the schema validation fails, an error message appears in the PROBLEMS view. If the schema validation is successful, the Mobile Development Kit extension checks whether the specified file exists. If it does not, an error message appears in the PROBLEMS view.
  • If a value is platform-aware, for example. the value FixedSpace of SystemItem for an ActionBar, the PROBLEMS view shows warning messages. These messages also appear as tooltips in the editor when you hover over the green tilde following the platform-aware value.
  • Auto-completion for a target path only applies to JSON metadata files. An error message is shown in the PROBLEMS panel if a target path is invalid. This may happen due to a wrong segment name, a missing parameter, an invalid parameter, or a wrong combination of segments.
  • To support target path, validation is provided for the _Name value, which covers two types of _Name types in metadata:

    • UI element names
      • Page name checking:
        • Empty value: mark as error
        • Invalid syntax check: mark as error (if it has a space in the name)
        • Unique check in one application scope: mark as warning, instead of error, as there are some duplicated names in the real cases (not treated at runtime if not in the same navigation stack)
      • Control name checking
        • Empty check: mark as error
        • Invalid syntax check: mark as error (if it has space in the name)
        • Unique check in one page scope: mark as error
    • ActionResult name checking:

      • Empty check: mark as error
      • Invalid syntax check: mark as error (if it has space in the name)
      • No unique check

      Note

      Other language features, such as code completion, go to definition, and so on, are not applicable for _Name scenarios, so they are not available for _Name values.

  • Supports target children's properties:

    • Service – .service file

      Note

      To have the language features on Target properties and the OData target path / binding values, the corresponding service OData metadata XML should be available, otherwise, no validation support for OData relevant values in design time.

      • Fetching service OData metadata from the debugger's appRoot
        • Right-click the service file and choose MDK: Fetch OData Metadata from the context menu.
        • Enter a user name and password that is assigned Administrator rights.
        • The progress is displayed on the left bottom of Visual Studio Code. If the process completes, it shows a message "The service metadata has been updated completely."
        • The fetched XML file is next to the service file.
    • EntitySet – all the available OData EntitySet name values come from above service OData metadata XML, so this EntitySet property depends on the value in Service field.

      • The EntitySet value is checked against the potential completion items as documented in the auto-completion section
    • ReadLink – the ReadLink property depends on both Service and EntitySet fields. Potential values can be any of the following:

      • Global or rule reference
      • TargetPath
      • Predefined OData annotation value, for example {@odata.readLink}
      • EntitySetName with filter option, for example SystemStatuses('I0100')
    • QueryOptions – They apply only to .json metadata files. The validation is a two-step process. First it checks whether the value complies with OData query option specification. If the value does not comply, the position where the error occurs is underlined and an error message for it is shown in the PROBLEMS panel. If yes, it enters the second step to validate all the properties used. If any invalid property is found, the whole value is underlined and an error message for it is shown in the PROBLEMS panel. If there is more than one invalid property, the same count of error messages are shown in the PROBLEMS panel.

      • $select
      • $expand
      • $filter
      • $orderby
      • $top
      • $skip

    Note

    These features are available only when Service and EntitySet values could be resolved in design time, for example, no support if the EntitySet is a rule.

Status Bar for Platform-Specific Validation

A status bar for indicating platform-specific validation is present at the bottom of the workspace. It includes the following types:

  • iOS & Android & Web
  • iOS & Android (default)
  • iOS
  • Android
  • Web
  • None

The Visual Studio Code extension uses these statuses to validate the values of the platform-specific properties.

For example, the property SystemItem in an ActionBar is platform-specific. If you set the status bar to iOS, the value FlexibleSpace of SystemItem, which is used only on iOS platforms, passes the validation process successfully. However, if you change the status bar to Android, a warning message appears.

You can change the value of the status bar by clicking on it.

If a document is open in the editor at the time you click the status bar, a validation of the application which includes the active document is triggered.

The Mobile Development Kit extension provides a convenient method for file navigation.

To open a referenced file, place the cursor within the value the reference and select Go to Definition from the context menu.

To see the content of the file specified by the file reference in the editor, select Peek Definition from the context menu.

File Creation

The Mobile Development Kit extension lets you create files easily, even after you have created file references.

If a file specified by a file reference doesn't exist, a light-bulb icon appears at the beginning of the line where you place the cursor within the value of the file reference. Click the icon and follow the instructions to create a file.

Extracting the Selected String Value to a Rule File

When you open and activate a JavaScript file, following files will be automatically generated in the root folder:

  • { MDK application root }/jsconfig.json
  • { MDK application root }/.typings/IClientAPI.d.ts

Note

Since these files are generated to support the ClientAPI auto-completion method, you need not merge them into the git repository.

There are various code actions that you can perform on the rule, global, or localization file.

  1. When you place the cursor within a string value in a JSON file, a light-bulb icon appears at the beginning of the line.
  2. Click the icon then select MDK: Extract to Rule.
  3. Follow the instructions to create a rule file and open it.
    • If the value is text only, the return value of the generated rule file is the same as the value of the string in which you placed your cursor before the extraction.
    • If the value is in i18n expression format, such as $(L, xxx), the return value is the corresponding i18n related client API method, such as localizeText('xxx').
  4. When you return to the previous JSON file, the string value is replaced with a file reference that points to the generated rule file.

This action is valid if the following conditions are met:

  • If the selected string is a pure text value (text that does not begin with '/', '$', '#', '{' and 'res://') or if the text is in i18n expression format
  • If the files are .json files with the following extensions: action, global, page, service, app, and so on
  • If there is no diagnostic error for the selected string value
  • If the selected string value is a file reference of a rule according to its schema definition

Extracting the Selected String Value to a Global File

This action is similar to that for the rule file except it doesn't support extracting the text in the i18n expression format.

Extracting the Selected String Value to the Default Internationalization File

This action is applicable only to text values and extracts the selected value to a new property value (not a new file) in the default i18n file, which is specified in the Localization property of the Application.app file.

Features in Cross-Application Scenarios

All the features like auto-completion, validation, code action and navigation are also supported in Mobile Development Kit component development in cross-application scenarios.

However, the language features remain unavailable until the cross application file reference is resolved.

You can trigger the code action by placing your cursor within a cross application file reference and clicking the light bulb icon that appears in the left margin.

If more than one application specified by the referenced application name exists in the workspace or if there is one application but it has not been used to resolve, the code action message Resolve the application reference is displayed. Click the message to resolve the code action, before you proceed.


Last update: November 14, 2022