[Huawei Developers] Sherlock F:
Card abilities are intelligent cards which are displayed on the Huawei Assintant Page and show relevant information about your service to the users, that provides a great user experience, even out of your app. If a users subscribes to your Card Ability, an intelligent Card will be added to the Huawei Assistant page, waitng for the user to start an action. You can use the mutiple areas of the card or adding buttons to trigger different acctions in your app or Quick App.

In previous posts I've told you about how to perform the account binding and trigger events for Card Abilities. Now, lets talk about How to develop a Card Ability.

Previous requirements

An Enterprise Developer Account

Huawei QuickApp IDE

Huawei Ability Test Tool (Find it on AppGallery)

ADB

Notes:

Currently, only the Enterprise Account has access to the Ability Gallery Console. Members of a Team account won't be able to configure abilities, even if are added to the team by the Enterprise account.

You don´t need an Enterprise account to develop cards, but you will need it to release them.

Starting the Card project

Card Abilities use the Quick App technology, if you are familiar with Quick App development or Front End development, you will find the card development process so easy.

Open the Huawei Quick App IDE

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019024031.77259320916930748416351947882250:50511029021624:2800:407788DF6DEBE083C9AB0BCC18DDC0D2840B90CC4B66758049E48154CEC38022.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019024031.77259320916930748416351947882250:50511029021624:2800:407788DF6DEBE083C9AB0BCC18DDC0D2840B90CC4B66758049E48154CEC38022.png[/IMG]

Go to, File > New Project > New JS Widget Project

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019024259.91788282348855976312853257600674:50511029021624:2800:9800058CCC0D1688AC97C62B06B439B69BF1EDBA986E2B0E232D0DDAACDF47CF.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019024259.91788282348855976312853257600674:50511029021624:2800:9800058CCC0D1688AC97C62B06B439B69BF1EDBA986E2B0E232D0DDAACDF47CF.png[/IMG]

Choose the name, package name, a place to store your project and finally choose a tempalte to start developing your Card.

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019024950.22823556686770792476266477734451:50511029021624:2800:859E9AE2535AE4DC9364C31EF06AFF41C19928B7C7C7E812CE0AA6204D674E0D.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019024950.22823556686770792476266477734451:50511029021624:2800:859E9AE2535AE4DC9364C31EF06AFF41C19928B7C7C7E812CE0AA6204D674E0D.png[/IMG]

The source file of a Card has the ux extension. A Card file will be packed in a forder with the same name as the ux source file, in this directory you will also find an i18n dir where you can put different translations of your static content.

A card file is diveded on 3 segments:

Template: Here you define the visual components of Your Card with HTML

Style: Here you define the component appearance by using CSS. You can create define your styles in a separated file by using the .scss file extension.

Script: Contains the business logic of your Card by using JavaScript.

Handling different locales

You can display your cards in different languages by adding the js file corresponding to each locale you want to support. To add locales, go to the i18n dir of your card, rigth click and select new file.

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019033125.41622434143368304922576241979358:50511029021624:2800:C32FDB2F44BC9D9732D7716BA5BCF715D396B1CDA60968A781D7FDEC31C22DD2.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019033125.41622434143368304922576241979358:50511029021624:2800:C32FDB2F44BC9D9732D7716BA5BCF715D396B1CDA60968A781D7FDEC31C22DD2.png[/IMG]

Create a js file and name it with the language code you want to support. Then, create a message object with your desired strings.

//es.js
export const message={
title: "Tech Zone",
textArray: ['Microprocesador', 'Stock Disponible'],
url: "https://definicion.de/wp-content/uploads/2019/01/microprocesador.jpg",
buttonArray: ['Comprar']
}

//en.js
export const message={
title: "Tech Zone",
textArray: ['Microprocessor', 'New Item Available'],
url: "https://definicion.de/wp-content/uploads/2019/01/microprocesador.jpg",
buttonArray: ['Buy']
}

On the Script part of your card file, import your locales and select the one which matches with the system locale. You can also define a default locale in case of the user's default language is unsupported by you.

const locales = {
"en": require('./i18n/en.js'),
"es": require('./i18n/es.js')
// TODO:Like the example above, you can add other languages
}
const localeObject = configuration.getLocale();
let local = localeObject.language;
const $i18n = new I18n({ locale: local, messages: locales, fallbackLocale: 'en' }); //use the fallbackLocale to define a default locale

Output:

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019035749.03002361141095680991406731584304:50511029021624:2800:13C4524375B729C56E2283FD3433442C314D054EA4F724DD801B8937513DD30F.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019035749.03002361141095680991406731584304:50511029021624:2800:13C4524375B729C56E2283FD3433442C314D054EA4F724DD801B8937513DD30F.png[/IMG]

Card in spanish

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019035854.10707416187577153275197491552622:50511029021624:2800:086DD2A7877DFEE015136DD76DEB75F1E0103F6EBB07930ED724D246BF9CBA2C.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019035854.10707416187577153275197491552622:50511029021624:2800:086DD2A7877DFEE015136DD76DEB75F1E0103F6EBB07930ED724D246BF9CBA2C.png[/IMG]

Card in english

Data fetching

You can fetch data from remote APIs to perform internal operations or displaying custom messages by using the fetch interface.

onInit: function () {
var fetch = require("@system.fetch")
var mainContext=this;
fetch.fetch({
url:"https://gsajql2q17.execute-api.us-east-2.amazonaws.com/Prod",
success:function(data){
const response=JSON.parse(data.data)
//Do something with the remote data

},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})

}

If you want to display the received data, add properties to your exported data object

<script>

//import
//locale configs

module.exports = {
data: {
i18n: $i18n,
apiString:'loading'// property for receiving the remote parameter
},
onInit: function () {
var fetch = require("@system.fetch")
var mainContext=this;
fetch.fetch({
url:"https://gsajql2q17.execute-api.us-east-2.amazonaws.com/Prod",
success:function(data){
const res=JSON.parse(data.data)
mainContext.apiString=res.body; //updating the apiString with the received value

},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})

}
})
}
}
</script>

From the Template part, display the received String by using the next notation:

"{{KEY}}"

<template>
<div class="imageandtext1_box" widgetid="38bf7c88-78b5-41ea-84d7-cc332a1c04fc">

<!-- diplaying the received value on the Card Title-->
<card_title title="{{apiString}}" logoUrl="{{logoUrl}}"></card_title>

<div>
<div style="flex: 1;align-items: center;">
<b2_0 text-array="{{$t('message.textArray')}}" lines-two="{{linesTwo}}"></b2_0>
</div>
<f1_1 url="{{$t('message.url')}}"></f1_1>
</div>
<card_bottom_3 button-array="{{$t('message.buttonArray')}}" menu-click={{onClick}}></card_bottom_3>
</div>

</template>

Output:

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019041948.84655424336016587522685459353300:50511029021624:2800:BC969BB1FCBEFA56CA858F6AB792AA0E860351B09731BA3C9ECEDDEAF8A3CD11.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019041948.84655424336016587522685459353300:50511029021624:2800:BC969BB1FCBEFA56CA858F6AB792AA0E860351B09731BA3C9ECEDDEAF8A3CD11.png[/IMG]

Card with dynamic title

Handling event parameters

If your card will be triggered by a Push Event, it can be prepared to receive event parameters and using it to perform internal operations and displaying personalized messages. By using Push Events, the event parameters will be transparently delivered to the card on the onInit function.

onInit: function (params) {
//Do something
}

To display the received params, define an exported props array on the Script part of your Card.

<script>
//imports
//locale configs

module.exports = {
props: [ //Define all the desired properties to be displayed
'title',
'big_text',
'small_text'
],
data: {
'screenDensity': 3,
'resolution': 1080,
'posterMargin': 0,
'width': 0,
'height': 0,
i18n: $i18n,
},
onInit: function (params) {
//Parameter assignation
this.title=params.title;
this.big_text=params.big_text;
this.small_text=params.small_text;
this.margin = Math.ceil(this.dpConvert(16));
},
dpConvert: function (dpValue) {
return (dpValue * (750 / (this.resolution / this.screenDensity)));
}
}
</script>

On the Script part of your Card, use {{}} to display your received parameters.

<template>
<div class="maptype_box" widgetid="12e7d1f4-68ec-4dd3-ab17-dde58e6c94c6">
<!--Custom title-->
<card_title id='title' title="{{title}}"></card_title>

<div class="maptype_content_box">
<image src="{{$t('message.url')}}" class="maptype_img" style="width: {{width}}px ;height:{{height}}px;"></image>

<div class="maptype_one">
<!--Custom text-->
<text class="maptype_text_one">{{big_text}}</text>
</div>
<div class="maptype_two">
<text class="maptype_textFour">{{small_text}}</text>
</div>
</div>
<card_bottom_2 dataSource="Source"></card_bottom_2>
</div>

</template>

The IDE allows you defining testing parameters, so you can check your Card behavior. Go to Config from the Card Selector.

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019043724.01110145973614737765211682273339:50511029021624:2800:3AB12253AE00ACCE4624AC86CEDA489B8838936D61F4F70A3E14B38CEFE4F5D1.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019043724.01110145973614737765211682273339:50511029021624:2800:3AB12253AE00ACCE4624AC86CEDA489B8838936D61F4F70A3E14B38CEFE4F5D1.png[/IMG]

On the opened dialog, choose the Card you want to prepare for receiving parameters and then, modify the Startup Parameter List.

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019044031.09762168593383161500620418929116:50511029021624:2800:4A5CDF763A10DCFB0AEBA5B76EF4A2A2B84FCF72AC8A19E1CEE0BBD6D551E61C.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019044031.09762168593383161500620418929116:50511029021624:2800:4A5CDF763A10DCFB0AEBA5B76EF4A2A2B84FCF72AC8A19E1CEE0BBD6D551E61C.png[/IMG]

Testing parameters configuration

Output

[IMG="https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019044803.38126844995783892174430108925465:50511029021624:2800:BEB99A20940B4755A7112B759019A28D3F72823923B98F0BD0B0F03373E0D538.png"]https://communityfile-dre.op.hicloud.com/FileServer/getFile/cmtybbs/002/383/434/2640052000002383434.20201019044803.38126844995783892174430108925465:50511029021624:2800:BEB99A20940B4755A7112B759019A28D3F72823923B98F0BD0B0F03373E0D538.png[/IMG]

Conclusion

Card Abilities are intelliget cards able to receive event parameters or download remote data to display dynamic content. You can use this capabilities to display personalized cards and improve the user experience even out of your app.

Reference

Card Ability Development Guide