Feature/react native docs v1.8 (#632)

* documentation for Beagle React Native * Update content/en/resources/customization/beagle-for-react-native/localhost.md Co-authored-by: Matheus Ribeiro Lima <57918064+matheusribeirozup@users.noreply.github.com> * Update content/pt/resources/customization/beagle-for-react-native/localhost.md Co-authored-by: Matheus Ribeiro Lima <57918064+matheusribeirozup@users.noreply.github.com> Co-authored-by: Tiago Peres França <tiago.franca@zup.com.br> Co-authored-by: Tiago Peres França <tiagoperesfr@gmail.com> Co-authored-by: Matheus Ribeiro Lima <57918064+matheusribeirozup@users.noreply.github.com>
ZupIT · Jun 9, 2021 · 3c0cdd4 · 3c0cdd4
1 parent 1fab96b
commit 3c0cdd4
Show file tree

Hide file tree

Showing 28 changed files with 786 additions and 17 deletions.
diff --git a/content/en/get-started/installing-beagle/backend.md b/content/en/get-started/installing-beagle/backend.md
@@ -1,6 +1,6 @@
 ---
 title: Backend
-weight: 12
+weight: 13
 description: "You will find here how to configure a backend with Beagle."
 ---
 

diff --git a/content/en/get-started/installing-beagle/react-native.md b/content/en/get-started/installing-beagle/react-native.md
@@ -0,0 +1,59 @@
+---
+title: React Native
+weight: 12
+description: >-
+  Here, you'll find how to install Beagle on your React Native application.
+---
+
+---
+
+## Introduction
+This guide considers you're familiar with React Native. If this is not the case, please check the
+[React Native guide on how to install its dependencies and create your first application](https://reactnative.dev/docs/environment-setup).
+
+Beagle is available for React Native, but it's not stable yet. The development is incomplete and we
+still have some work to do before moving from beta versions. Unfortunately, our team is not big
+enough to make React Native a priority and because of this, the development is relatively slow. We
+decided to release a beta version anyway because we figured out if it's in interest of the
+community, it can help us finalize it.
+[Here]({{< ref path="/resources/customization/beagle-for-react-native/development" lang="en" >}})
+you can find a list of everything that should be working properly and everything that still needs
+work. Help is very welcomed here!
+
+## Versioning
+All versions of Beagle RN (Beagle React Native) to be launched before the final stable version
+follows the pattern "0.x.y", where "x" represents the version of Beagle Web Core it uses. Since we
+are currently in version "1.7.0" of Beagle Web Core, the current version of Beagle RN is 0.7.0. "y"
+will be used to launch new versions that uses the same version of Beagle Web Core.
+
+## Compatibility
+Beagle RN Beta is guaranteed to work only with latest releases of React Native, i.e.
+version 0.64.1 or above. It is probably possible to support older versions, but it is not a priority
+right now.
+
+## Installation
+At the root of your React Native project, install it with npm or yarn.
+
+If you use yarn:
+```bash
+yarn add @zup-it/beagle-react-native
+```
+
+If you use npm:
+```bash
+npm install @zup-it/beagle-react-native
+```
+
+{{% alert color="success" %}}
+Well done! Your library was installed. Continue at
+[**how to use Beagle on React Native.**]({{< ref path="/get-started/using-beagle/react-native" lang="en" >}})
+{{% /alert %}}
+
+## **Next Steps**
+
+In this section, you made Beagle's **initial installation** on your application!  
+Now, keep configuring Beagle:
+
+👉 Go to
+[**initial configurations** ]({{< ref path="/get-started/using-beagle/react-native" lang="en" >}})
+to enable the use of Beagle on your React Native project.
diff --git a/content/en/get-started/using-beagle/backend.md b/content/en/get-started/using-beagle/backend.md
@@ -1,6 +1,6 @@
 ---
 title: Backend
-weight: 28
+weight: 29
 description: >-
   Here, you'll find how to make Beagle's usage configuration for backend's
   projects.

diff --git a/content/en/get-started/using-beagle/react-native.md b/content/en/get-started/using-beagle/react-native.md
@@ -0,0 +1,85 @@
+---
+title: React Native
+weight: 28
+description: >-
+  This section shows the initial walkthrough to use the Beagle library in React Native projects.
+---
+
+---
+
+## **Configuration**
+
+After you finish the installation, you need to **configure the React Native project to use Beagle.**
+To do this, just follow the guide below.
+
+Run one of the commands below to generate the files that will be used by the Beagle library. You can
+run the command according to your package manager (yarn or npm).
+
+**If you use yarn:**
+```text
+yarn beagle
+```
+
+**If you use npm:**
+```text
+npx beagle
+```
+
+If the files beagle create already exist, a question will be made asking if you wish to replace
+them or not.
+
+Two files are created after running this command: `src/app.tsx` and
+`src/beagle/beagle-service.ts`. The first is the entry point for your app, while the second is
+the beagle configuration.
+
+{{% alert color="warning" %}}
+Attention: we highly recommend the use of Typescript, that's why both files are generated using
+this language. If you want to use plain javascript, rename the files to `app.jsx` and
+`beagle-service.js`. Also remove all typing information.
+{{% /alert %}}
+
+{{% alert color="warning" %}}
+Attention: if you're using prettier and/or eslint, you'll probably have to format the generated
+files according to the project rules. You can also ignore the rules if you don't want to change
+the code.
+{{% /alert %}}
+
+To view the beagle application in action, make sure that your app renders the component `App` at
+`src/app.tsx`. If you created your project via `react-native init`, change your `index.js` file to
+the following:
+
+```javascript
+import {AppRegistry} from 'react-native';
+import App from './src/app';
+import {name as appName} from './app.json';
+
+AppRegistry.registerComponent(appName, () => App);
+```
+
+Your application is ready to be executed! Once run, the app should show a welcome message loaded
+remotely from `https://usebeagle.io/start/welcome`.
+
+{{% alert color="success" %}}
+Congrats, you have finished your first Beagle Screen!
+{{% /alert %}}
+
+## Other configurations
+
+- [Cache]({{< ref path="/resources/customization/beagle-for-react-native/cache" lang="en" >}})
+- [WebView]({{< ref path="/resources/customization/beagle-for-react-native/web-view" lang="en" >}})
+- [Accessing the localhost]({{< ref path="/resources/customization/beagle-for-react-native/localhost" lang="en" >}})
+- [Local images]({{< ref path="/resources/customization/beagle-for-react-native/local-images" lang="en" >}})
+
+👉 For more details on how to use the Beagle Config and the component BeagleRemoteView, please,
+check the [React guide]({{< ref path="/get-started/using-beagle/web/react" lang="en" >}}), it works
+exactly the same!
+
+👉 Beagle React Native is still Beagle Web! Everything in this documentation for Beagle Web is also
+valid for Beagle React Native. To go deeper into the lib, we suggest reading the articles under
+[resources > customization > Beagle for React Native]({{< ref path="/resources/customization/beagle-for-react-native" lang="en" >}})
+as well as
+[resources > customization > Beagle for Web]({{< ref path="/resources/customization/beagle-for-web" lang="en" >}})
+
+👉 If you wish to know the current development status of Beagle React Native, check it
+[here]({{< ref path="/resources/customization/beagle-for-react-native/development" lang="en" >}}).
+Contributions are welcomed!
diff --git a/content/en/overview.md b/content/en/overview.md
@@ -28,9 +28,10 @@ Beagle's current releases version are:
 * **Android:**[![Maven Central](https://img.shields.io/maven-central/v/br.com.zup.beagle/android)](https://mvnrepository.com/artifact/br.com.zup.beagle/android)
 * **iOS:**[![badge](https://img.shields.io/cocoapods/v/Beagle)](https://cocoapods.org/pods/Beagle)
 * **WEB:** 
-  * **Angular:**[![badge](https://img.shields.io/npm/v/@zup-it/beagle-angular?logo=Angular)](https://github.com/ZupIT/beagle-web-angular)
-  * **React:**[![badge](https://img.shields.io/npm/v/@zup-it/beagle-react?logo=React)](https://github.com/ZupIT/beagle-web-react)
-* **Backend**[![back](https://camo.githubusercontent.com/27998a386042ecb2cae7b9f09ae159bd07c935bd/68747470733a2f2f696d672e736869656c64732e696f2f6d6176656e2d63656e7472616c2f762f62722e636f6d2e7a75702e626561676c652f6672616d65776f726b)](https://mvnrepository.com/artifact/br.com.zup.beagle/framework)
+  * **Angular:**[![badge](https://img.shields.io/npm/v/@zup-it/beagle-angular?logo=Angular)](https://www.npmjs.com/package/@zup-it/beagle-angular)
+  * **React:**[![badge](https://img.shields.io/npm/v/@zup-it/beagle-react?logo=React)](https://www.npmjs.com/package/@zup-it/beagle-react)
+* **React Native:**[![react native badge](https://img.shields.io/npm/v/@zup-it/beagle-react-native?logo=React)](https://www.npmjs.com/package/@zup-it/beagle-react-native)
+* **Backend:**[![back](https://camo.githubusercontent.com/27998a386042ecb2cae7b9f09ae159bd07c935bd/68747470733a2f2f696d672e736869656c64732e696f2f6d6176656e2d63656e7472616c2f762f62722e636f6d2e7a75702e626561676c652f6672616d65776f726b)](https://mvnrepository.com/artifact/br.com.zup.beagle/framework)
 {{% /alert %}}
 
 Some definitions on this documentation exists only only in some specific minors or patches. See the captions used to denote these cases:
@@ -39,7 +40,7 @@ Some definitions on this documentation exists only only in some specific minors
 * `>=x.y.z`: existing definition from x.y.z version;
 * `<=x.y.z`: existing definition until the x.y.z version. 
 
-## How does Beagle works?
+## How does Beagle work?
 
 The tool works as a facilitator of **BFF** \([**Backend For Frontend**]({{< ref path="/key-concepts#backend-for-frontend" lang="en" >}})\). This means that Beagle, from a library of components defined in the [**Design System**]({{< ref path="/key-concepts#design-system" lang="en" >}}) of the Android, iOS or Web application, makes the visual and behavioral change of them by returning a JSON file that indicates what and where each component should be rendered and which the action they are going to perform.
 

diff --git a/content/en/resources/customization/beagle-for-backend/_index.md b/content/en/resources/customization/beagle-for-backend/_index.md
@@ -1,7 +1,7 @@
 ---
 title: Beagle for Backend
-weight: 190
-description: 'Here, you''ll find the main customizations provided for backend.'
+weight: 194
+description: Here, you'll find the main customizations provided for backend.
 ---
 
 ---

diff --git a/content/en/resources/customization/beagle-for-backend/beagle-framework.md b/content/en/resources/customization/beagle-for-backend/beagle-framework.md
@@ -1,6 +1,6 @@
 ---
 title: Beagle Framework
-weight: 192
+weight: 195
 description: Here you'll understand how to use this framework.
 ---
 

diff --git a/content/en/resources/customization/beagle-for-backend/serialization.md b/content/en/resources/customization/beagle-for-backend/serialization.md
@@ -1,6 +1,6 @@
 ---
 title: Serialization
-weight: 194
+weight: 196
 description: Here you'll find more informations about serialization.
 ---
 

diff --git a/content/en/resources/customization/beagle-for-react-native/_index.md b/content/en/resources/customization/beagle-for-react-native/_index.md
@@ -0,0 +1,11 @@
+---
+title: Beagle for React Native
+weight: 188
+description: >-
+  You will find here the main classes that are part of Beagle's framework for
+  Beagle React Native.
+---
+
+---
+
+You will find here additional information about Beagle React Native.
diff --git a/content/en/resources/customization/beagle-for-react-native/cache.md b/content/en/resources/customization/beagle-for-react-native/cache.md
@@ -0,0 +1,30 @@
+---
+title: Cache
+weight: 189
+description: >-
+  You will find here information of how to persist cache in Beagle React Native.
+---
+
+---
+
+By default, Beagle RN will only cache files temporally, i.e. as soon the app is closed, the cache
+will be lost. To make a persistent cache, you must provide an implementation of the interface
+`BeagleStorage`. Both `react-native/AsyncStorage` and `@react-native-async-storage/async-storage`
+implement this interface. We don't use React Native's default implementation because it's
+deprecated.
+
+If you need to persist the cache, we recommend using `@react-native-async-storage/async-storage`. To
+install it, follow the instructions
+[here](https://react-native-async-storage.github.io/async-storage/docs/install/).
+
+To use it with beagle, just add the following configuration to `src/beagle/beagle-service.ts`:
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage'
+// ...
+
+export default createBeagleUIService({
+  // ...
+  customStorage: AsyncStorage,
+})
+```
diff --git a/content/en/resources/customization/beagle-for-react-native/development.md b/content/en/resources/customization/beagle-for-react-native/development.md
@@ -0,0 +1,58 @@
+---
+title: Development status
+weight: 193
+description: >-
+  You will find here information about the current development status of Beagle React Native.
+---
+
+---
+
+## Current development status
+This is our current development status. Please help us get to a stable version!
+
+To contribute to this project, please use
+[this repository](https://github.com/ZupIT/beagle-web-react).
+
+### Core features
+Fully implemented. Renderization, context, custom components and custom actions all work! In truth,
+if you don't intend on using the default components and default actions, Beagle React Native is
+ready for production.
+
+### Components
+| Component      | Status          | Description                                                                                     |
+|----------------|-----------------|-------------------------------------------------------------------------------------------------|
+| Container      | done            |                                                                                                 |
+| Screen         | not implemented | Working as a container                                                                          |
+| Button         | done            |                                                                                                 |
+| Image          | incomplete      | There might be some problems with the image size. Placeholder is not implemented.               |
+| TextInput      | done            |                                                                                                 |
+| Lazy component | done            |                                                                                                 |
+| ListView       | incomplete      | Extremely buggy and slow. Mainly on Android.                                                    |
+| GridView       | not implemented |                                                                                                 |
+| PageView       | incomplete      | Doesn't render the children properly. Can't navigate between pages.                             |
+| SimpleForm     | not implemented | Working as a container                                                                          |
+| TabBar         | incomplete      | The tabbar doesn't scroll There seems to be a bug where a second tab bar in a page won't render |
+| Text           | done            |                                                                                                 |
+| Touchable      | done            |                                                                                                 |
+| WebView        | done            |                                                                                                 |
+
+We also need to check the styling here. Some of the components, even the ones marked as done, have
+way to many styles, which might create some undesired behavior.
+
+### Actions
+| Actions         | Status          | Description                                                      |
+|-----------------|-----------------|------------------------------------------------------------------|
+| PushStack       | incomplete      | It works exactly like in web, i.e. the back button does nothing. |
+| PopStack        | incomplete      | It works exactly like in web, i.e. the back button does nothing. |
+| PushView        | incomplete      | It works exactly like in web, i.e. the back button does nothing. |
+| PopView         | incomplete      | It works exactly like in web, i.e. the back button does nothing. |
+| PopToView       | incomplete      | It works exactly like in web, i.e. the back button does nothing. |
+| ResetStack      | incomplete      | It works exactly like in web, i.e. the back button does nothing. |
+| OpenNativeRoute | not implemented | will try to use the browsers location, which doesn't exist.      |
+| OpenExternalUrl | not implemented | will try to use the browsers location, which doesn't exist.      |
+| AddChildren     | done            |                                                                  |
+| Condition       | done            |                                                                  |
+| Confirm         | not implemented |                                                                  |
+| SendRequest     | done            |                                                                  |
+| SetContext      | done            |                                                                  |
+| SubmitForm      | not implemented |                                                                  |
diff --git a/content/en/resources/customization/beagle-for-react-native/local-images.md b/content/en/resources/customization/beagle-for-react-native/local-images.md
@@ -0,0 +1,43 @@
+---
+title: Local images
+weight: 192
+description: >-
+  You will find here information on how to register your local images.
+---
+
+---
+
+Beagle components normally refer to images by an id, see the example below:
+
+```json
+{
+  "_beagleComponent_": "beagle:image",
+  "path": {
+    "_beagleImagePath_": "local",
+    "mobileId": "zup-logo"
+  }
+}
+```
+
+Above, the image component refers to `zup-logo`. For this to work, this id must be registered in
+Beagle. To register images that can be used for beagle, you must provide a map in the configuration
+at `beagle-service.ts`. See the example below:
+
+```typescript
+import zupLogo from '../assets/zup-logo.png'
+// ...
+
+export default createBeagleUIService({
+  // ...
+  localAssetsPath: {
+    'zup-logo': zupLogo,
+  },
+})
+```
+
+The image must exist in your assets folder, in this case, located at `src/assets`. If Typescript
+complains, you can create a `src/globals.d.ts` file with the following content:
+
+```typescript
+declare module '*.png'
+```