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 theApplication.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 thei18n
related client API for rule JavaScript files. Also shows the signatures of the eight types ofi18n
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}
whereproperty3
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 servicedata.service
. -
Supports target children's properties:
-
Service –
.service
fileNote
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.
- Right-click the service file and choose
- Fetching service OData metadata from the debugger's
-
EntitySet
– all the available ODataEntitySet
name values come from the above service OData metadata XML, so thisEntitySet
property depends on the value in Service field.- The completion list includes: Global / Rule,
EntitySet
names from the OData metadata XML, and predefinedErrorArchive
offlineEntitySet
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')
- The completion list includes: Global / Rule,
- 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 theEntitySet
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, thePROBLEMS
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 thePROBLEMS
view. - If a value is platform-aware, for example. the value
FixedSpace
ofSystemItem
for anActionBar
, thePROBLEMS
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 oferror
, 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
- Page name checking:
-
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.
- UI element names
-
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.
- Right-click the service file and choose
- Fetching service OData metadata from the debugger's
-
EntitySet
– all the available ODataEntitySet
name values come from above service OData metadata XML, so thisEntitySet
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
- The
-
ReadLink – the
ReadLink
property depends on both Service andEntitySet
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 exampleSystemStatuses('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 thePROBLEMS
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 thePROBLEMS
panel. If there is more than one invalid property, the same count of error messages are shown in thePROBLEMS
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 theEntitySet
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.
Navigation¶
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.
- When you place the cursor within a string value in a JSON file, a light-bulb icon appears at the beginning of the line.
- Click the icon then select
MDK: Extract to Rule
. - 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 correspondingi18n
related client API method, such aslocalizeText('xxx')
.
- 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.