Skip to content

Commit

Permalink
adds backend example for custom componentes and widgets. Updates Andr…
Browse files Browse the repository at this point in the history 
…oid example for components and widgets (#895)

Signed-off-by: carlossteinzup <carlos.stein@zup.com.br>

Signed-off-by: carlossteinzup <carlos.stein@zup.com.br>
  • Loading branch information
@carlossteinzup
carlossteinzup committed Sep 30, 2022
1 parent 2aad1f8 commit 08cd2b3
Show file tree
Hide file tree
Showing 6 changed files with 272 additions and 87 deletions.
148 changes: 90 additions & 58 deletions content/en/android/customization/widgets/simple-custom-widget.md
View file
Expand Up @@ -6,42 +6,51 @@ description: Here you will learn how to create and use a widget in Beagle.

---

## How to create components (custom views) and widgets?
## How to create components and widgets?

The example below shows how a custom widget will be implemented and which component it will register. It will have:
- A text;
- Two buttons inside a linear layout.
To create a component and register it on the Front end, it is necessary to create a `Widget` and a `Component` that will return a view.

The buttons in this component will be responsible for increasing and decreasing the text's size and the screen will be like the image below:
## What is the difference between a `component` and a `widget`?

![](/shared/image%20%2883%29.png)
- A component holds all the logic referring to the component's functionality. In our example, this is where the logic for increasing the text size will be. This information is usually implemented on the front end.
- A widget is the structure through which we will pass information to our component, such as the text referring to the title and buttons. This is the one we declare in the hierarchy of a screen in the backend. It is also used to register the component and its signature on Beagle (its contract, properties, etc., both in the back and frontend).

We implement a **custom component** and a Widget that will register it on the example below. This component has:

- A text
- Two buttons within a linear layout.

The buttons here are be responsible for increasing and decreasing the size of the title text. The screen will look like the following image:

{{< figure src="/shared/customComponentMocked.png" width="400" >}}

{{% alert color="info" %}}
You can do this using `@RegisterWidget` annotation and extending the `WidgetView` class.
The elements created here will use come *annotations*, like `@RegisterWidget` and extensions, like `WidgetView`.
{{% /alert %}}

Follow the next steps to create and customize a component and a widget:
## Creating a widget

### Step 1: Create widget
To create a widget:

1. Create a class and name it`"CustomWidgetTitleIncrease"`;
2. Apply the annotation`@RegisterWidget` ;
3. Extend this class using WidgetView interface;
4. This class now will request a toView method to be implemented. Change the class as listed below:
1. Create a class and name it `"CustomWidgetTitleIncrease"`
2. Apply the `@RegisterWidget` annotation to this class;
3. Extend this class using the `WidgetView` interface
4. The class will now ask you to implement the `buildView` method. At this point, leave the class as listed below, as the configuration of this method will be finished later:

```kotlin
CustomWidgetTitleIncrease.kt

@RegisterWidget
class CustomWidgetTitleIncrease: WidgetView() {
override fun buildView(rootView: RootView): View {
TODO("not implemented")
TODO("Not yet implemented")
}
}
```

### Step 2: Create and configure the component
## Step 2: Creating and configuring the component

* Create a `.XML` configuration file and copy and paste the content below, it will create a layout:
Start by creating a `.XML` configuration file and copy and paste the content below, as it creates the layout chosen for this example:

```markup
title_increase_component_layout.xml
Expand Down Expand Up @@ -83,11 +92,10 @@ title_increase_component_layout.xml
</LinearLayout>
```

Now, you have to **create the** **component**:

1. Create a class and name it:`TitleIncreaseComponent`. This class will register how the component work and the business rule;
2. Copy and paste the class below:
Now, it's time to create the component:

1. Create a class and name it: `TitleIncreaseComponent`. It is in this class that sets how the component works and its business rule. Please keep in mind that the business rule of this component is only to increase and decrease the size of your Title. You can add any rule and configuration you wish.
2. Copy and paste the class below:

```kotlin
class TitleIncreaseComponent(context: Context) : LinearLayout(context) {
Expand All @@ -98,51 +106,50 @@ class TitleIncreaseComponent(context: Context) : LinearLayout(context) {
}

fun setTitleText(title: String) {
tvExampleTitle.text = title
tv_example_title.text = title
}

fun setTitleButton1(titleButton:String){
btIncrease.text = titleButton
fun setTitleButton1(titleButton: String) {
bt_increase.text = titleButton
}
fun setTitleButton2(titleButton:String){
btDecrease.text = titleButton

fun setTitleButton2(titleButton: String) {
bt_decrease.text = titleButton
}

private fun changeTitleSize(){
private fun changeTitleSize() {

var size = tvExampleTitle.textSize
tvExampleTitle.textSize = size
var size = tv_example_title.textSize
tv_example_title.textSize = size
Toast.makeText(context, size.toString(), Toast.LENGTH_SHORT).show()

val textView = findViewById<TextView>(R.id.tvExampleTitle)
val b1 = findViewById<Button>(R.id.btIncrease)
val b2 = findViewById<Button>(R.id.btDecrease)

b1.setOnClickListener {
if(size < 50){
bt_increase.setOnClickListener {
if (size < 50) {
size += 5f
tvExampleTitle.textSize = size
tv_example_title.textSize = size
}
Toast.makeText(context, size.toString(), Toast.LENGTH_SHORT).show()
}

b2.setOnClickListener {
if(size > 5){
bt_decrease.setOnClickListener {
if (size > 5) {
size -= 5f
tvExampleTitle.textSize = size
tv_example_title.textSize = size
}
Toast.makeText(context, size.toString(), Toast.LENGTH_SHORT).show()
}
}
}
```

## Step 3: Configuring the Widget

### Step 3: Configure the widget
Now that the layout and component are defined, we need to finish configuring the custom widget

The layout and the component are defined, it is necessary to finish the configuration of the customized widget.
Review the function below and notice that some *text variables* have been added.

1. Check the function below and see that some text variables were added. This was chosen to demonstrate that it is possible to define the value of this variables by the widget, adding title and button names:
- These variables will receive values ​​for texts that will define the componente title (that will change size) and the Buttons titles.
- The text values ​​will be defined from a JSON that will represent a screen with the component created on this example (We will show you this JSON later).

```kotlin
CustomWidgetTitleIncrease.kt
Expand All @@ -163,11 +170,44 @@ class CustomWidgetTitleIncrease(
}
```

### Step 4: Display the component

The customized widget is now ready, the component can be displayed.
## Step 4: Displaying the component

Now that the custom widget is ready, the component can be displayed.

You don't have to configure an entire backend just for testing, you can mock the JSON below, which will simulate an endpoint with a screen that contains the component you just created here on the frontend. (This JSON mocks a backend response. If you wish to check how to create this componente on a backend, please click [here](/backend/kotlin/customization/simple-custom-widget/)).

```json
{
"_beagleComponent_":"beagle:screenComponent",
"child":{
"_beagleComponent_":"beagle:container",
"children":[
{
"_beagleComponent_":"custom:customWidgetTitleIncrease",
"title":"Title",
"buttonTitle1":"Button 1",
"buttonTitle2":"Button 2"
}
],
"style":{
"backgroundColor":"#000000",
"cornerRadius":{

},
"size":{

},
"flex":{
"justifyContent":"SPACE_AROUND",
"alignItems":"CENTER",
"grow":1
}
}
}
}
```

1. To test the component, use the method below:
Now just load it from an Activity on Android, as in the example below:

```kotlin
MainActivity.kt
Expand All @@ -176,22 +216,14 @@ class MainActivity : AppCompatActivity() {

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

setContentView(
CustomWidgetTitleIncrease(
"Example Title",
"Increase",
"Decrease"
).buildView(rootView = object : RootView {
override fun getContext() = this@MainActivity

override fun getLifecycleOwner() = this@MainActivity
})
)
val intent = this.newServerDrivenIntent<ServerDrivenActivity>(RequestData(url = "yourMockedJSONAddress"))
startActivity(intent)
}
}
```

2. Run the aplication and your component will be displayed:
- Run the application and your custom component \(in this case a screen\) will be displayed:

![](/shared/custumwidgetexample.gif)
{{< figure src="/shared/customComponentMockedGif.gif" width="400" >}}
60 changes: 60 additions & 0 deletions content/en/backend/kotlin/customization/simple-custom-widget.md
View file
@@ -0,0 +1,60 @@
---
title: Custom component and Widget
weight: 131
description: On this section you will learn how to create a custom component and widget for Beagle.
---

---

## How to create components and widgets?

To create a component and register it in the Backend it is necessary to create a Widget

## What is the difference between a component and a widget?

- A component holds all the logic referring to the component's functionality. In our example, this is where the logic for increasing the text size will be. This information will be implemented on the front end.
- A widget is the structure through which we will pass information to our component from the backend, such as the text referring to the title and buttons. This is the one we declare in the hierarchy of a screen in the backend. It is also used to register the component and its signature on Beagle (its contract, properties, etc., both in the backend and frontend).

In the example below, we will create a **custom component** and demonstrate how to register it in the backend. This component will consist of:

- One **text** and Two **buttons** (this same example exists in the front end for testing)

The buttons in this component are responsible for increasing and decreasing the size of the title text in the component and it will look like the following image:

{{< figure src="/shared/customComponentMocked.png" width="400" >}}

{{% alert color="success" %}}
Elements created here will use some annotations like `@RegisterWidget` and some extensions like the `Widget` class. Below we will show the when and how.
{{% /alert %}}

## Creating the widget

To create a widget:

1. Create a class in the backend and name it `"CustomWidgetTitleIncrease"`
2. Apply the `@RegisterWidget` annotation to this class;
3. Extend this class using the `Widget` interface

```kotlin
import br.com.zup.beagle.annotation.RegisterWidget
import br.com.zup.beagle.widget.Widget

@RegisterWidget
class CustomWidgetTitleIncrease(
val title: String,
val buttonTitle1: String,
val buttonTitle2: String
) : Widget()
```

Once configured, it is now possible to use this component and set the properties listed above from the backend.

### Create and configure the component in Front end

When creating the component on the front end, it will also be necessary to create a Widget with the same name as the one used on the backend. This will register it on the frontend and allow it to receive the information sent from the backend.

- Click this [link](/android/customization/widgets/simple-custom-widget/) to see how to create this component (and all its logic) on an Android front end.

After implementing it on the front, just run your application and it will be displayed as in the image below:

{{< figure src="/shared/customComponentMockedGif.gif" width="400" >}}

0 comments on commit 08cd2b3

Please sign in to comment.