DEV Community: Rootstrap

RIP XML (Welcome Compose)

Amaury — Wed, 02 Aug 2023 14:57:51 +0000

RIP XML "They killed an innocent" (welcome Compose)
"They killed an innocent," says a song. That's what is happening to XML in Android, Google and the community are slowly killing XML.

Since the announcement of Android Compose back in 2021 at the Google IO developers conference, developers have been testing and working with this new Declarative pattern for Android, and slowly Compose has been winning space in the Android community.

Big steps for a baby:
As with all, new things generate a lot of uncertainty, and usually, when you are adopting a new tech you have to be very careful with it, at the beginning we don't use to count on enough documentation or a community that supports it, so we strongly suggest considering this points before adopting new tech in general:

Learning curve: We should evaluate the learning curve of the new technology and determine if it is feasible to allocate enough time and resources to learn and become proficient in it.
Technical requirements: Analyze the technical requirements and determine if it is compatible with the existing infrastructure and software, and the company vision.
Availability of resources: Assess the availability of resources, such as documentation, tutorials, and support forums, to aid in the learning and development process.
Company goals: Determine if the new technology aligns with the company goals and if it can help achieve them more efficiently or effectively than the current technology.
Cost: Consider the cost of adopting the new technology, including licensing, training, and impact on productivity during the transition.
Risks and challenges: Identify risks and challenges associated with the new technology, such as security, adaptability, compatibility issues, or a lack of community support and updates.
User experience: Consider how the new technology will impact the user experience and whether it will improve or hinder it.

The transition
But the idea of doing the transition to Compose was always over the table, so we started to learn it, testing, documenting, fighting poor online documentation and tutorials, fighting with bugs and undocumented issues (🥲), new design approaches, and studying new architectures.

So trust me when I say this transition can take a while, when you have a big team, aligning all the team members in the same direction is a big challenge, so my advice is don't try to jump into a bottomless pool and start a project with a new tech, or the consequence could be catastrophic.
Right now we can say that Compose is mature enough to start taking it seriously and start the transition to it, so here it's the big question:

Is XML so bad that we need to move to Compose?
No really, in general, over other advantages, XML offers a structured, efficient, and maintainable way to define UI elements, promoting a good development workflow and a consistent user experience. But Compose provide several advantages over XML:

Declarative UI: is cleaner, more readable, and more performant than Imperative UI.
XML depends too much on the application's live cycle.
Compose allows you to do more with less code compared to XML, redefining all the views and simplifying their use, no more recycler views yea!!!.
Compose is more intuitive: as declarative UI you just need to tell the UI what to show changing the data state and not setting up the UI like in XML.
State management: data state is not attached to the app live-cycle, we don't need to take care anymore of that.
Memory: all the compositions are painted "on demand" so the user just sees what needs to see and doesn't have hidden views or unused views in the background, improving the app performance.
Design: the design system is more robust and intuitive.
Learn more about Compose

Why now?
Compose is in a stage where we can use it to create complex solutions, saving time and effort for the team. The Android Development community is adopting compose very fast, and XML will be obsolete in the future, the same thing that happens with Java for Android when we move to Kotlin.

On the other hand with Compose, you can create UI components more intuitively and concisely, using Kotlin code instead of XML. This makes it easier to understand and modify your UI code and reduces the amount of boilerplate code you need to write, improving the readability and the maintenance cost.

Also rovides a faster way to develop your app's user interface. You can use Compose to quickly prototype your UI design and see the results in real-time, without having to compile and run your app. This can save you a lot of time and effort, especially during the early stages of UI development.

And finally Compose provides a more flexible and customizable way to create UI components. You can easily create custom UI components and modify existing ones to fit your specific needs. With Compose, you can also easily reuse UI components across different parts of your app, saving you time and effort in the long run. Compose is designed to perform better than XML-based UI development. Uses a more efficient rendering engine that can reduce the amount of CPU and memory usage, resulting in a smoother and more responsive user interface.

Conclusion
The transition to a new tech could be a challenge depending on the context, as individuals you may take a risk, but as a team, we have to consider a lot of things.

As a team, this is the moment to start developing products with Compose, very soon we will bring you a base project with an initial setup for an Android project with Compose including Theming, Navigation, Testing, DI, and more. We encourage you to start learning Compose to be more productive and bring to the end user a better experience.

Keep calm and code clean. 😜

keywords: #android #compose #xml #google

Imperative and Declarative UI Pattern - Is Declarative Programming the future?

Amaury — Thu, 16 Mar 2023 13:42:00 +0000

Check out the Original post

Behind every mobile application, a UI framework determines how developers create the application and how well it performs. Today, UI frameworks fit into two categories: declarative and imperative. The majority of apps use the imperative approach.

However, as the newer, declarative frameworks develop and reveal their many advantages, several major tech companies have switched to developing their apps with declarative UI designs.

As declarative programming becomes more popular, we want to evaluate its advantages and disadvantages and consider how it improves upon imperative designs.

In this article, we will define and compare imperative and declarative UI design and explore the benefits and drawbacks of designing apps with declarative programming.

Understanding Imperative and Declarative UI Designs
Imperative and declarative UI frameworks refer to frameworks that use imperative and declarative programming styles, respectively. Below, we define these terms as they relate to UI design and describe the differences between the two paradigms or models.

Imperative Programming
Currently the most common paradigm, imperative programming requires the developer to write step-by-step how the program will reflect the desired state or perform an operation. For UI creation, developers write detailed code that tells the device how to display the components.

Declarative Programming
Declarative programming allows developers to design the user interface based solely on what they want to be displayed without regard to how the device will update its state.

Oftentimes, declarative frameworks rely on an underlying imperative implementation that translates the declarative command into a set of imperative instructions for the device to complete.

Let's look at an example
Website designer sitting at a computer
Web design
Consider a simple mobile app with a button that toggles its color.

Imperative design
A developer must create a button component and add an event handler function to it. The event handler function would run when clicked and contain an if-else statement that changes the color based on the button's color when pressed.

Declarative design
The developer creates a button component with the property toggle color. The declarative design appears much simpler and more intuitive.

However, the declarative example only works because of an imperative implementation in the framework that interprets the toggle color property and assigns the proper event handler that determines the current button color and how it needs to change.

Why use Declarative Programming?
Less code, faster development
Imperative programming requires a lot of code to manage the UI. Developers must determine the contents, define themes, position components, and manage event handlers. With many responsibilities, developers have less time to polish the design and debug other UI issues.

Moreover, imperative UI design typically requires multiple programming languages, one for the UI design and another for the functionality of each UI element.

With declarative programming, on the other hand, we only need to design UIs within the Swift (for IOS) or Kotlin (for Android) code, eliminating the need to maintain and handle separate UI files. In short, declarative UI programming means less code and faster development.

Theming
Declarative UIs come with a pre-configured theme. Developers can customize this theme to meet their preferences by altering properties like typography, color, buttons, etc. A pre-configured yet fully customizable theme saves developers time as they don't need to build a theme from scratch.

Dynamism
Declarative UI frameworks provide control structures developers can use to manipulate the drawing of the user interface. Compared to imperative frameworks typically used for Android and IOS development, declaratively developed user interfaces can use these control structures to be more dynamic.

State management
With an imperative design, developers face the difficulty of syncing the UI with the app state by manually updating all the components to reflect the changes in the app. Traditionally, developers created a user interface with a tree of widgets/layouts.

Whenever the app's data or state required a UI component to update, the program had to traverse through the tree of widgets, select the right one, and change it. As the tree of elements grows, the design becomes more complex and error-prone.

The declarative UI paradigm eliminates this process of manual synchronization. The declarative framework automatically updates the UI to match the app's state, simplifying state management by a significant degree.

Other Advantages of Declarative UI Design

Live previews for rapid UI development.
SwiftUI & Compose foster collaboration between designers and web developers
It's an opportunity to learn a valuable skill.

Disadvantages of Declarative UI Design
Since declarative programming has only emerged in the past few years, there are still unresolved issues and disadvantages. Current problems with declarative UI design include:

Declarative UIs only support more recent operating systems
You may encounter problems no one has faced before
Some features are only available in native, imperative UI frameworks
Best declarative programming practices and conventions have not yet been established
Insufficient documentation
Small developer community
Little integration with third-party libraries
The learning curve can be very steep initially
Many issues with the declarative paradigm, however, are likely temporary. As more companies and developers see the advantages of declarative design and invest more resources into growing the development community, they will resolve many of the aforementioned issues.

Why you should start thinking declaratively?
Declarative app development requires a new perspective. Many assumptions that developers might have, in regards to app development, no longer apply if using a declarative design.

For example, with declarative programming, developers can rebuild the UI to reflect the app's current state instead of modifying it directly. The formula below illustrates this new perspective.

When the state of your app changes (for example, the user flips a switch in the settings screen), the state changes, which triggers a redraw of the user interface. There is no imperative changing of the UI itself (like a textView.text = "Hi").

Conclusion
Several major names in the tech industry, such as Meta, Google, and Apple, have already adopted the declarative paradigm because they see its value as a simple yet effective method of app development.

These companies believe it is the future of front-end development. Here at Rootstrap, we believe we should be ready for it too, and we encourage developers to explore how declarative design could improve UI development.

Flutter Navigation: Navigator vs Go Router

Amaury — Thu, 16 Mar 2023 13:35:48 +0000

In this post we are going to learn a little bit more about Flutter Navigation and go_router.

Check the original POST

How does flutter navigation work?

Flutter navigation provides a way for you to navigate from one widget to another in your app. This is achieved by using a navigation stack, which is essentially a collection of routes.

Navigator is a built-in Flutter widget that provides a simple and convenient way to manage the navigation stack and navigate between routes. It's straightforward to use and can be a good choice for basic navigation needs. On it a route represents a widget and its associated data. When you navigate to a new route, it is pushed onto the navigation stack, and when you navigate back, the current route is popped off the stack.

Navigator provides a number of navigation widgets, including Navigator, MaterialPageRoute, and CupertinoPageRoute, that make it easy to manage the navigation stack and provide common navigation patterns.

With Navigator, you can push and pop routes, as well as manage the navigation stack. MaterialPageRoute and CupertinoPageRoute are two common types of routes in Flutter that are used to transition between pages. They provide animation and visual effects appropriate for the material design or Cupertino design languages, respectively.

Overall, Flutter navigation is designed to be flexible, allowing you to create complex navigation patterns that meet the needs of your app.

But there are some limitations and potential problems that you should be aware of:

Limited routing features: Navigator provides basic routing functionality, but it doesn't offer advanced features like named routes, path parameters, query parameters, or wildcard matching, which can make it challenging to build more complex navigation patterns.
Code complexity: As your app grows in complexity, managing the navigation stack with Navigator can become more challenging, making your code more difficult to maintain and debug.
Lack of customizability: Navigator provides basic animation and visual effects for transitioning between routes, but it doesn't allow you to customize the routing transitions and animations.
Global state management: Navigator doesn't provide a built-in solution for managing the global states, which can make it challenging to share data between routes.
Inconsistent navigation patterns: Because Navigator is a low-level widget, it can be challenging to ensure that navigation patterns are consistent across your app. This can lead to a fragmented user experience.
These limitations can make it challenging to build complex, scalable, and consistent navigation patterns with Navigator. If you encounter these limitations, you may want to consider using a third-party routing library, such as go_router, to address them.
On the other hand, go_router is a third-party routing library maintained by the Flutter team, that provides advanced routing functionality that is not available in Navigator. For example, go_router provides features such as named routes, path parameters, query parameters, and wildcard matching, which can be useful for building more complex navigation patterns.
Additionally, go_router provides a more elegant and declarative approach to routing, making it easier to manage the routing logic in your app. This can help to make your code more organized and maintainable, especially as your app grows in complexity.
So, if you need advanced routing features and a more elegant routing solution, you may consider using go_router. But if your navigation needs are simple, Navigator may be a more appropriate choice.

There are several advantages of using go_router in Flutter:

Named routes: go_router supports named routes, which makes it easier to manage and organize the navigation logic in your app. Named routes allow you to define the routes in a central location and then reference them throughout your app, making it easier to make changes to your navigation logic in the future.
Path parameters: go_router supports path parameters, which allow you to pass data to your routes based on the URL. This is useful for building dynamic navigation patterns, such as when you need to pass an ID or other data to a route.
Query parameters: go_router also supports query parameters, which allow you to pass data to your routes through the URL query string. This is useful for cases where you need to pass data that is not part of the route path.
Wildcard matching: go_router supports wildcard matching, which makes it easy to define catch-all routes that can handle any URL that doesn't match another route.
Declarative routing: go_router provides a more elegant and declarative approach to routing, making it easier to manage the routing logic in your app. This can help to make your code more organized and maintainable, especially as your app grows in complexity.
Custom routing transitions: go_router allows you to customize the routing transitions and animations, making it possible to create custom and unique navigation experiences in your app.

Overall, go_router provides a number of advanced routing features that can make it easier to manage and organize the navigation logic in your Flutter app. If your navigation needs are complex, go_router may be a good choice for your project.

Let's see an example of how we can structure our app:


 Dart
static GoRouter onBoardingRouter(AuthState authState) => GoRouter(
        initialLocation: "/logIn",
        navigatorKey: onBoardingNavigatorKey,
        routes: [
          GoRoute(
            name: "login",
            path: "/logIn",
            builder: (context, state) => const LoginPage(),
            //Example of redirection        
            redirect: (context, state) => authState == AuthState.loading ? "/splash" : null,
          ),
          GoRoute(
            name: "splash",
            path: "/splash",
            builder: (context, state) => const SplashPage(),
          ),
          GoRoute(
            name: "signUp",
            path: "/signUp",
            builder: (context, state) => const SignUpPage(),
          ),
          GoRoute(
            name: "passwordReset",
            path: "/passwordReset",
            builder: (context, state) => const ResetPasswordPage(),
          ),
        ],
      );


static GoRouter mainRouter = GoRouter(
    initialLocation: "/main",
    routes: [
      ShellRoute(
        navigatorKey: mainNavigatorKey,
        builder: (context, state, child) {
          return Cookies(
            child: HomeCorePage(
              child: child,
            ),
          );
        },
        routes: [
          GoRoute(
            name: "main",
            path: "/main",
            builder: (context, state) => const HomePage(),
            routes: [
              GoRoute(
                name: "postDetails",
                path: "postDetails",
                builder: (context, state) =>
                    PostDetailsPage(postId: state.params['id'] ?? ""),
              ),
              GoRoute(
                name: "chat",
                path: "chat",
                builder: (context, state) => ChatPage(),
              ),
              //...........
            ],
          ),
        ],
      ),
      ShellRoute(
        navigatorKey: mainNavigatorKey,
        builder: (context, state, child) {
          return Cookies(
            child: SettingsCorePage(
              child: child,
            ),
          );
        },
        routes: [
          GoRoute(
            name: "settings",
            path: "/settings",
            builder: (context, state) => const HomePage(),
            routes: [
              GoRoute(
                name: "profileEdit",
                path: "profile",
                builder: (context, state) => const EditProfilePage(),
                routes: [
                  GoRoute(
                    name: "resetPassword",
                    path: "resetPassword",
                    builder: (context, state) => const ResetPasswordPage(),
                  ),
                ],
              ),
              GoRoute(
                name: "themeSetup",
                path: "theme",
                builder: (context, state) => const ResetPasswordPage(),
              ),
              //...........
            ],
          ),
        ],
      ),
    ],
  );

Go_router manages different types of routes:
ShellRoute: is a container, basically, all the child routes will be rendered inside of its widget.
i.e: Here HomeCorePage can have a container that renders a child widget with a classic nav drawer or a bottom nav bar to nav between screens, as usual when you change between screen we de HomeCorePage render again the new child and keeps the state of the rest of the screen.


 Dart
static GoRoutermainRouter= GoRouter(
  initialLocation: "/main",
  routes: [
    // Home Navigation with drawer or bottom nav bar
    ShellRoute(
      navigatorKey: mainNavigatorKey,
      builder: (context, state, child) {
        return Cookies(
          child: HomeCorePage(
            child: child,
          ),
        );
      },
      routes: [
        GoRoute(
          name: "main",
          path: "/main",
          builder: (context, state) => const HomePage(),
        ),
        GoRoute(
          name: "settings",
          path: "/settings",
          builder: (context, state) => const SettingsPage(),
        ),
      ],
    ),
  ],
);

GoRoute: the main route type, this is where you declare your route with the widget to render, and can have different children, let's see:


 Dart
GoRoute(
          name: "main",
          path: "/main",
          builder: (context, state) => const HomePage(),
          redirect: (context, state) {
                if (!isUserAuthTo("main"))
                         return "/unauth";
                if (!state.params.containsKey("id"))
                      return "/main"
                    // return null to continue to the sub route
                return null;
          },
          routes: [
            GoRoute(
                name: "details",
                    path: "/details/:id",
                    builder: (context, state) => const Details(id: state.params["id"] ?? ""),
                ),
),
@amaury901130

Here we can see different things:
Every route can have N sub-routes.
We can add validations before nav to a sub-route and redirect the user to any other page that we need in case don't match the validation.
Another advantage of go_router is that we can manage nav errors easily in the GoRouter class:


 Dart
GoRouter(
   // when trying to nav to a missing route.
      errorBuilder: (context, state) {
          return ErrorPage(ErrorCode.e404);
      },
      initialLocation: "/main",
      routes: ....
)

Deeplinks:
When a deep link is received from the platform, GoRouter will display the configured screen based on the URL path. To configure your Android or iOS app for deep linking, see the Deep linking documentation at flutter.dev:

Enable deep linking on Android
Add a metadata tag and intent filter to AndroidManifest.xml inside the tag with the ".MainActivity" name:


 xml
<!-- Deep linking -->
<meta-data android:name="flutter_deeplinking_enabled" android:value="true" />
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="http" android:host="flutterbooksample.com" />
    <data android:scheme="https" />
</intent-filter>

A full restart is required to apply these changes.
Test on Android emulator
To test with an Android emulator, give the adb command an intent where the host name matches the name defined in AndroidManifest.xml:


 xml
adb shell 'am start -a android.intent.action.VIEW \\ -c android.intent.category.BROWSABLE \\ -d "<http://flutterbooksample.com/book/1>"' \\ <package name>

Replace the <package name> with the package name of your Android app. If you named the package com.example.myflutterapp, run the following command:

adb shell 'am start -a android.intent.action.VIEW \\ -c android.intent.category.BROWSABLE \\ -d "<http://flutterbooksample.com/book/1>"' \\ com.example.myflutterapp

For more details, see the Verify Android App Links documentation in the Android docs.

Enable deep linking on iOS
Add two new keys to Info.plist in the ios/Runner directory:


 xml
<key>FlutterDeepLinkingEnabled</key> 
<true/> 
<key>CFBundleURLTypes</key> 
<array> 
    <dict> 
    <key>CFBundleTypeRole</key> 
    <string>Editor</string> 
    <key>CFBundleURLName</key> 
    <string>flutterbooksample.com</string> 
    <key>CFBundleURLSchemes</key> 
    <array> 
    <string>customscheme</string> 
    </array> 
    </dict>
</array>

The CFBundleURLName is a unique URL used to distinguish your app from others that use the same scheme. The scheme (customscheme://) can also be unique.
A full restart is required to apply these changes.
Test on iOS simulator
Use the xcrun command to test on the iOS Simulator:
xcrun simctl openurl booted
customscheme://flutterbooksample.com/book/1

In conclusion
Go_router is an alternative to Navigator that offers some advantages over the latter, especially in large and complex applications. We strongly recommend that if you're working on a complex application and need advanced navigation management, you should consider using go_router.
Below are some reasons why we should consider using go_router instead of Navigator:

Greater flexibility in defining routes: Go_router allows for a more flexible definition of navigation routes than Navigator. With go_router, we can define routes based on any criteria, such as the access route, URL parameters, application state, etc.
Better navigation management: Go_router offers more advanced navigation management than Navigator. For example, go_router allows us to define multiple navigation stacks for different areas of the application, making it easier to navigate between them without losing context.
Integration with the BLoC pattern: Go_router integrates well with the Business Logic Component (BLoC) pattern, which is a popular architecture pattern in Flutter. Go_router allows us to define routes that are directly linked to BLoC events, making it easier to manage navigation and application state.
Better performance: Go_router offers performance improvements over Navigator in large and complex applications. Go_router uses a tree-based data structure to store navigation routes, allowing for faster and more efficient route lookup.

¿Qué tanto sabemos de Agile? Conceptos claves y el porqué funcionan.

Karen Stoletniy — Thu, 02 Feb 2023 16:43:59 +0000

Agile se convirtió en el grupo de metodologías de trabajo más popular en el desarrollo de software. La mayoría de los desarrolladores hemos escuchado hablar de Scrum o Kanban (entre otros) o incluso puesto en práctica, sin embargo ¿qué sabemos realmente de Agile?.

Muchas veces nos unimos a equipos, con listas de funcionalidades, deadlines o sprints ya definidos, pero ¿alguna vez nos hemos preguntado como desarrolladores como surge todo esto?.

Este artículo pretende develar qué hay detrás de escena de algunos conceptos claves que algunas de estas metodologías comparten, con las cuales trabajamos en el día a día como es la priorización de features o la definición de la duración de los sprints. Además quizás te inspire a dar un nuevo giro a tu carrera, u odiar un poquito menos al Product Owner o Scrum Master.

Planificación Ágil

Si trabajas con Scrum quizás la parte no tan divertida son las comúnmente llamadas “Sprint Planning”, reuniones previas a cada inicio de sprint para planificar el trabajo de esa iteración.

Pero antes de profundizar en este tema veamos la siguiente imagen llamada Planning Onion:

Lo que se puede apreciar de esta imagen son los diferentes horizontes de planificación. Normalmente estamos acostumbrados a focalizar hasta el “Release Plan”, y de hecho se pretende que así sea para el equipo de desarrollo. Sin embargo me gustaría hacer foco en el hecho de cómo un plan engloba a otro y cómo un cambio puede afectar a las otras capas que engloba.

Ahora bien, ¿por qué tanta planificación? Recordemos que detrás de todo proyecto hay un negocio con sus prioridades y que la planificación Ágil se dirige hacia a donde hay más valor para dicho negocio, el cual puede ser muy variante a lo largo del proyecto.

Es por eso que el foco se encuentra más en la planificación que en el plan en sí mismo, lo cual ayuda a promover los cambios y se debe dar a lo largo de todo el proyecto. Los cambios son importantes y absolutamente necesarios para obtener nuevos resultados; no es menor destacar que esta es en parte la clave del éxito de Agile dado que da más flexibilidad y tolerancia que las metodologías tradicionales.

En el desarrollo la planificación también juega un rol importante a la hora de intentar encontrar una solución óptima a lo que se pretende desarrollar.

Pero además una buena planificación ayuda a:

Reducir riesgos.
Reducir incertidumbres.
Aumentar la confianza del proyecto.
Mejorar la toma de decisiones.
Transmitir información mediante reportes periódicos.

Iteraciones

El producto cambia, la gente cambia, el mercado cambia, por lo tanto el plan también y es de allí donde cobra tanta importancia iterar.

Si trabajamos con Scrum sabemos que en cada iteración se obtiene como resultado un entregable que aporta valor, es por eso que el equipo tiene que trabajar como uno, con el mismo propósito y foco; de aquí juega un rol clave la definición del largo de las iteraciones (Sprints).

Probablemente estemos acostumbrados a sprints de dos semanas, pero ¿por qué no una semana, o cuatro? Bueno, eso depende de muchos factores:

Qué tan largo es el Release Plan.
El nivel de incertidumbre del proyecto, se recomienda hacer iteraciones más cortas cuanta más incertidumbre haya.
Elegir el largo para maximizar el feedback, se debe planear en base a los aprendizajes.
Suficientemente cortas para que no cambien las prioridades durante la iteración.
Último y no menos importante, debe ser suficiente para trabajar comprometidos a llegar a los entregables, pero sin estrés.

Es por eso que las iteraciones de dos semanas han tomado popularidad, suelen ser más organizadas y menos apresuradas, puesto que en una iteración muy corta el deadline está muy próximo y no deja tiempo de recuperación en caso de enfermedad de un miembro del equipo o si algo va mal durante dicho periodo. Por su contraparte una iteración muy larga tiende a empezar muy tranquilo, pero terminar muy desenfrenado, sin mencionar que se queda propenso a que el plan cambie durante la iteración.

Velocity

Ahora que ya se tiene definido el largo de cada iteración, hay que calcular cuánto trabajo asignarle a cada miembro del equipo, y es aquí donde entra en juego los conceptos de Velocity y Story Points.

Comencemos por Velocity, ¿cómo se calcula? Hay tres formas de hacerlo:

Usar valores históricos: Probablemente el más usado, pero para que sea efectivo hay que cumplir las siguientes condiciones.
- Las tecnologías y herramientas son las mismas.
- El equipo y ambiente de trabajo es el mismo.
- Las estimaciones son hechas por las mismas personas.
Si no se tienen datos históricos, simplemente ejecutar iteraciones y visualizar la velocidad. Esto sí, mientras más iteraciones previas a la estimación, menos incertidumbre.
Hacer un pronóstico: Aquí vienen los cálculos; se estima que las personas usan el 55-80% de su tiempo para el proyecto*, teniendo en cuenta meetings, sincronización, el cafecito de la mañana y los debates del partido del fin de semana 😬. Sabiendo lo anterior y los recursos disponibles, calculamos con el siguiente ejemplo:
- 4 personas en el equipo, 8 horas diarias cada uno.
- Por lo tanto, 6 horas disponibles por día (considerando el 80% del tiempo).
- Iteración de dos semanas (10 días hábiles).
- 10 días x 6 horas x 4 personas = 240 -> Horas por iteración

*Cohn, Mike. 2005. Agile estimating and planning. Prentice Hall

Story Points

En la diaria estamos acostumbrados a estimar las tareas/stories con dicha unidad pero no vamos a mentir, en nuestras cabezas al dar una estimación lo traducimos en horas ya que sigue siendo aún un concepto abstracto que no lo terminamos de entender del todo.

Imaginemos que nos piden estimar cuánto tiempo nos llevaría terminar de leer un libro. En una primera instancia debemos saber el tamaño del libro, pues no es lo mismo leer un libro de 100 páginas que uno de 350. Además hay que tener en cuenta el tópico y que tanto estamos relacionado con este, ya que quizás se nos sea más complejo leer y entender un libro de Mecánica Cuántica, que “Bajo la misma estrella”. Basados en eso y la disponibilidad diaria en horas para leer el libro, podemos estimar cuándo lo vamos a terminar.

Lo mismo ocurre en un proyecto de Software, para estimar la duración de un proyecto se comienza por estimar su tamaño, de aquí surge protagonismo los Story Points. Básicamente lo que hacemos al estimar con esta medida es decir que una tarea/story es más grande o pequeña que otra, la cual va a conllevar más o menos esfuerzo.

Estimaciones

Probablemente ahora nos estemos preguntando, ¿y cómo encontrar la unidad mínima de estimación? Independientemente de la unidad escojamos (como por ejemplo los números de Fibonacci) hay dos formas de definirlo:

Tomar una story que se considere más pequeña del resto y estimarla con un punto.
Tomar una story mediana y asignar puntos del medio dentro del rango de Story Points.

Una vez que tenemos esta estimación y una aproximación de la velocidad del equipo, estamos en condiciones de estimar la duración de lo que estamos planificando.

¿Por qué no estimar en tiempo directamente? Una de las grandes ventajas de los story points es que son auto-corregibles, no se devalúan y se adaptan a todos los miembros del equipo. Si por alguna circunstancia en una iteración hubo una velocidad menor a la estimada, simplemente se vuelve a recalcular el número de iteraciones que el proyecto va a requerir.

Cuando hablamos de estimar la duración en tiempo, hay que tener en cuenta el “Tiempo ideal” vs “El tiempo transcurrido”. Es aquí donde entran en juego los factores que pueden afectar ese “Tiempo ideal”, como las reuniones, trainings, demos, enfermedad, etc. Es por eso que en la mayoría de los casos es más difícil estimar en tiempo, en donde la estrategia de estimación cambia por completo (dicha explicación quedará para otro artículo), pero sigue siendo una opción válida para implementar.

Prioridades

Para culminar este artículo, me gustaría hablar sobre el cambio de prioridades. Independientemente de la metodología que usamos dentro de Agile, a todos nos duele ver como una feature que hicimos con tanto esmero y dedicación es sacada del tablero, o que el Product Owner con la voz temblorosa nos dice a mitad de sprint que este debe cambiar.

Como mencionamos al principio de este artículo, la planificación Agile está dirigida hacia dónde hay más valor y eso puede variar por diversos factores:

Valor en el mercado
Costos
Nuevos conocimientos: mientras más se conoce hay menos incertidumbres
Riesgos: ya sean funcionales, problemas presupuestales, etc.

Así que la próxima vez que veas estas variaciones, recuerda que hay muchos factores en juego que a veces el propio cliente no puede controlar o predecir.

Conclusión

Estas son algunas de las cosas que nos encontramos a diario con Agile y que por alguna razón las asumimos porque funcionan, y muy bien. Pero la verdad es que hay mucho más detrás, estudios, pruebas y errores que hace esta metodología tan efectiva y flexible para cada proyecto en particular frente a otras metodologías tradicionales.

How to manage large files with Heroku and Amazon S3 Buckets in Django Projects

brunomichetti — Tue, 16 Aug 2022 13:58:33 +0000

As a developer, I’ve recently worked on a Django API that processes large-sized images and videos. The system requires the admin to upload those mentioned files, and since the API is deployed in Heroku, we used to get the TIMEOUT error.

This happens because it takes some time to upload a file that is not light causing Heroku to crash. So, what can we do if we don’t want to reduce the size or the quality of the files?

In this blog post, I will provide a solution for this problem and will explain the flow and tools used. This information will hopefully help you with any working Django project that requires the management of large files.

The software architecture and flow

After discussing different approaches, my team and I decided to maintain the files in Amazon S3 buckets. These are containers where you can store objects (such as images and videos) and access them with fast performance.

As an example, if a Django model has an image attribute, let’s call it profile_picture, then we store the file in a bucket, and store the corresponding URL to that file in the database. So, if the Frontend requires the picture, the Backend returns the corresponding URL for that instance.

But, we don’t want everyone on the internet to have access to the image in the bucket, we only wish for the Frontend to do that. That’s why we have to configure the bucket as private.

Now, we need to answer: if the bucket is private, how does our Frontend access the files in it?. Well, in this case, we have to generate a pre-signed URL, that is a URL to grant temporary access to the file.

Here I will explain the proposed solution:

Store the system files in private buckets of Amazon S3.
Frontend and/or Django admin upload the files directly to a private Amazon S3 bucket.
The Backend stores the corresponding URL of each file.
When the Django admin creates/updates a file attribute for a given instance, the file is uploaded directly to the bucket, and the corresponding URL is stored in the database.

Explanatory interaction diagram:

When Frontend is about to upload a file:

It requests the Backend to get a valid upload URL to upload it to the private bucket.
The Backend generates and sends the upload URL.
The Frontend uses the upload URL to store the file in the private bucket.
After the upload, the Frontend sends the file URL to the Backend to store it for the corresponding file.

Explanatory interaction diagram:

When the Backend sends the URL of a file to the Frontend:

It uses a function to generate a pre-signed URL so the Frontend can access the file in the private bucket.

Explanatory interaction diagram:

The tools I used

Now that we have defined the solution flow, let’s talk about the tools. The first one I want to mention is django-s3direct, a library to directly upload files to the Amazon bucket from the admin panel. Also, it provides a model field that corresponds to the URL stored in the database.

On the other hand, we will use boto3 to generate the pre-signed URLs that the Backend sends to the Frontend in order to access the file. This library also generates the upload URL to allow the Frontend to upload files without the need of knowing the Amazon credentials.

In the following section, I’ll show the corresponding configurations.

Amazon S3 private bucket

I won't speak about the creation of buckets as there is plenty of documentation available. Next up, I’ll describe the configuration of the bucket to make it private and integrate it with django-s3direct.

Assuming you have already created the bucket and you have a user with access ID, access secret key, and permissions, these are the next steps:

Log in to Amazon S3 and create the bucket. Make sure you have the permissions.
Select the bucket, and go to the Permission tab.
In the bucket policy, paste the next policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPublicRead",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:ListMultipartUploadParts",
                "s3:AbortMultipartUpload"
            ],
            "Resource": "arn:aws:s3:::<name-of-bucket>/*"
        }
    ]
}

Change by your bucket name.
Now in the same tab, block all the public access to make it private:

Finally, in the same tab, paste this CORS configuration (needed by django-s3direct):


[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "HEAD",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 3000
    }
]

And that’s it, you have configured your private bucket. Keep in mind, if you want to change the policy in the future, first need to uncheck the blocking access.

Django-s3direct library

Now I will explain the use of the django-s3direct library to directly upload the files from the Django admin.

If you have a model that has a file attribute, when you change that attribute, this library will directly upload the file from the browser without sending it to the server. This is to avoid the named timeout error.

Let’s go step by step on how to get this configured:

Install django-s3direct in your project.
Add the library to your INSTALLED_APPS list in the settings:

# your settings file

INSTALLED_APPS = [ 
    …
    's3direct',
    …
]

Make sure you have the APP_DIRS configuration set as True in your TEMPLATES settings:

# your settings file

TEMPLATES = [
   {
        …
        'APP_DIRS': True,
        …
   }
]

Add django-s3direct urls to the urlpatterns list in your main urls.py file:

from django.urls import include, path

...

urlpatterns += [
    ...
    path('s3direct/', include('s3direct.urls')),
    ...
]

Add the configuration corresponding to Amazon to your settings (strongly recommended to put the access id and secret key values in environment variables):

# your settings file

# If these are set to None, the EC2 instance profile and IAM role are used.
AWS_ACCESS_KEY_ID = 'your-aws-access-key-id'
AWS_SECRET_ACCESS_KEY = 'your-aws-secret-access-key'
# Bucket name
AWS_STORAGE_BUCKET_NAME = 'your-aws-s3-bucket-name'
# The region of your bucket, more info:
# http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
AWS_S3_REGION_NAME = 'eu-west-1'
# The endpoint of your bucket, more info:
# http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
AWS_S3_ENDPOINT_URL = 'https://s3.eu-west-1.amazonaws.com'

Run collect static if needed:

python manage.py collectstatic

Now you can define in your model a file attribute corresponding to an image or video. Let’s take a look at an example:

from django.db import models
from s3direct.fields import S3DirectField

class Example(models.Model):
    image = S3DirectField(dest='example_destination')

And, what is example_destination? When you define a file attribute as an S3DirectField, you have to specify the dest parameter. There you have to put the string corresponding to the key in the S3DIRECT_DESTINATIONS dictionary in the configuration.
Let’s look at an example of the configuration to understand this better:

# your settings file

S3DIRECT_DESTINATIONS = {
   'example_destination': {
       'key': 'images/example-images/',
       'region': AWS_S3_REGION_NAME,
       'acl': 'private',
       'allow_existence_optimization': False,
   },
}

Inside each dictionary, you can configure a lot of parameters and check the library documentation to know them. - This example has the key where you define the folders where you want to store the corresponding file inside the bucket. You can test that it’s working by creating an instance of the class in the Django admin:

from django.contrib import admin

from example_app.models import Example


class ExampleAdmin(admin.ModelAdmin):
   fields = ('image',)


admin.site.register(Example, ExampleAdmin)

Now you should go to django admin and you will see something like this:

Then if you select an image, the library will directly upload the image to the private bucket and store the corresponding URL in the database. The Backend won’t receive a file, just a string URL. After the correct upload, you will see something like:

And the stored URL will have this structure: https://s3.<region-name>.amazonaws.com/<bucket-name>/<key>/<file-name>
If you click on the name of the picture, the browser will try to open it, but you won’t be able to see it because the bucket is private, and that’s ok. Also, if you click on REMOVE, the file will be removed from the instance but it will continue existing in the bucket.

Customize the name of the pictures

As highlighted, in the S3DIRECT_DESTINATIONS dictionary, you can configure in the key attribute the folders route to store the files corresponding to the given destination.

But what happens when you upload a file with the same name as another existing one in the same folder?

Well, that will overwrite the file, and I assume you don’t want that because it can be the file of another instance in your system.

Here are two tips for this:

Add a timestamp to the file name to avoid repeated file names in the system.
Use a slugify function to manage spaces and/or invalid characters in the file name.

If you do that, you can avoid a lot of future problems. Let’s look at an example:

# your settings file
import os

from django.utils import timezone
from django.utils.text import slugify


… 


EXAMPLE_DEST_KEY = 'images/example-images/'
TIMESTAMP_FORMAT = '%m-%d-%Y_%H-%M-%S-%f'

def normalize_filename(filename):
   name, extension = os.path.splitext(filename)
   time_stamp = timezone.now().strftime(TIMESTAMP_FORMAT)
   return f'{time_stamp}--{slugify(name)}{extension}'


S3DIRECT_DESTINATIONS = {
  'example_destination': {
      'key': lambda filename: f'{EXAMPLE_DEST_KEY}/{normalize_filename(filename)}',
      'region': AWS_S3_REGION_NAME,
      'acl': 'private',
      'allow_existence_optimization': False,
  },
}

In this example, for each new file, we apply a normalization of the file name. First, we normalize the filename using the slugify function from Django, and then we append at the beginning the timestamp.

If we upload a file with the name image.png, the system will store that file with the form <timestamp>--image.png.

Another example is if we have a file with the name FILE with SPACEs.png, the system will store <timestamp>--file-with-spaces.png. This is super easy to understand and solves a lot of problems.

Now, in this next section, we will see how to return presigned files to the Frontend.

It’s important to note, that this mentioned normalization will be executed only when uploading files in the Django admin. To be consistent, it would be nice to make the same normalization in the Frontend when it has to upload a file.

Boto3 and pre-signed URL

We know how to configure a private Amazon S3 bucket, and how to integrate it with django-s3direct to directly upload a file from the Django admin.

Now, we need to know how to do the following:

Send a pre-signed URL from the Backend to the Frontend so this last can access the existing file in the private bucket.
Send a pre-signed upload URL from the Backend to the Frontend so this last can upload a file.

Let’s now look at how we do this using the boto3 library.

Generate and send a view pre-signed URL

Since the bucket is private, if we take a file URL in the database and we try to access it, we won’t be able to. We would then see something like this:

This is why we need to generate a pre-signed URL in the Backend for the corresponding file to be temporarily available for the Frontend. For this I use the boto3 library, let’s look at the used functions:

# some utils file for boto3 functions

from boto3 import Session
from typing import Any, Dict

from django.conf import settings

def get_object_key_from_url(url: str) -> str:
   '''
   Returns the object key for the given url
   '''
   endpoint = settings.AWS_S3_ENDPOINT_URL
   bucket_name = settings.AWS_STORAGE_BUCKET_NAME

   return url.split(f'{endpoint}/{bucket_name}/')[1]


def get_presigned_url(object_key: str) -> str:
   '''
   Returns a presigned URL for the given object key
   '''
   session = Session(
       aws_access_key_id=settings.AWS_ACCESS_KEY_ID,
       aws_secret_access_key=settings.AWS_SECRET_ACCESS_KEY,
       region_name=settings.AWS_S3_REGION_NAME,
   )
   s3client = session.client('s3')
   url = s3client.generate_presigned_url(
       ClientMethod='get_object',
       Params={
           'Bucket': settings.AWS_STORAGE_BUCKET_NAME,
           'Key': object_key,
       },
       ExpiresIn=settings.AWS_PRESIGNED_URL_EXPIRATION_TIME_MINUTES,
   )
   return url

In this example, the function get_object_key_from_url obtains the object key from the file URL. As mentioned, the object key is the route of folders and the file name in the bucket.

Why do we need the object key? We need it to generate the presigned URL of the file. That object key will be used in the get_presigned_url function for that purpose.

The next thing to do is to execute that function when the Frontend makes a GET request and needs to access the file.

There are several ways of doing that, and I’m going to show you one that I find easy to understand:

Create a property in the model, that corresponds to the pre-signed attribute:

# your models file

from django.db import models
from s3direct.fields import S3DirectField

from example_app.s3_files import get_object_key_from_url, get_presigned_url

class Example(models.Model):
   image = S3DirectField(dest='example_destination')

   @property
   def presigned_image(self):
       return get_presigned_url(get_object_key_from_url(self.image))

The presigned_image property first extracts the object key for the stored URL and then generates the pre-signed one to send it to the Frontend.
Now add the property to a model serializer:

from rest_framework import serializers

from example_app.models import Example


class ExampleSerializer(serializers.ModelSerializer):

   class Meta:
       model = Example
       fields = ('presigned_image',)

This way, if you use that serializer to send the data to the Frontend, it will return a pre-signed URL in the presigned_image field.

A pre-signed URL looks like this:

https://<bucket name>.s3.amazonaws.com/images/<object key>?<lots of needed parameters>

With that URL, the file will be available for the time period defined in your settings as in the example.

Generate an upload pre-signed URL

Last but not least, I’m going to explain how to send an upload URL from the Backend to the Frontend. Imagine we have an app where the users have profile pictures and the Frontend needs to upload the image.

The flow would then look like this:

The Frontend generates the object key of the image file (recommend adding a timestamp and normalizing the file name as in the example in the previous section).
The Frontend sends the object key in a POST request to the Backend.
The Backend takes the object key and generates a pre-signed upload URL.
The Frontend uploads the image using the pre-signed upload URL.
The Frontend sends the image URL to the backend so it can be stored in the database.

Let’s look at an example of this function:

def get_presigned_url_dict_to_upload_file(object_key: str) -> Dict[str, Any]:
   '''
   Returns a dict with the necessary data to upload a file for the given key
   '''
   session = Session(
       aws_access_key_id=settings.AWS_ACCESS_KEY_ID,
       aws_secret_access_key=settings.AWS_SECRET_ACCESS_KEY,
       region_name=settings.AWS_S3_REGION_NAME,
   )
   s3client = session.client('s3')

   url = s3client.generate_presigned_post(
       Bucket=settings.AWS_STORAGE_BUCKET_NAME,
       Key=object_key,
       Fields={
           'acl': 'private',
       },
       Conditions=[
           {'acl': 'private'},
       ],
       ExpiresIn=settings.AWS_PRESIGNED_URL_EXPIRATION_TIME_MINUTES,
   )

   return url

Finally, let’s look at an example in a viewset for the action POST to receive an object key and return the necessary information to upload the file.

First, we must define the serializer like so:

from rest_framework import serializers

from example_app.models import Example


class ExampleSerializer(serializers.ModelSerializer):

   class Meta:
       model = Example
       fields = ('presigned_image',)


class ExampleUploadURLSerializer(serializers.Serializer):
   object_key = serializers.CharField()
   upload_url_dict = serializers.DictField(required=False)

Second, we must define the viewset with the corresponding action:

from rest_framework import viewsets, status
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.request import Request

from example_app.models import Example
from example_app.serializers import ExampleSerializer, ExampleUploadURLSerializer
from example_app.s3_files import get_presigned_url_dict_to_upload_file


class ExampleViewSet(viewsets.ModelViewSet):
   serializer_class = ExampleSerializer
   queryset = Example.objects.all()

   @action(detail=False, methods=('post',), url_path='upload-url')
   def upload_url(self, request: Request) -> Response:
       serializer = ExampleUploadURLSerializer(data=request.data)
       serializer.is_valid(raise_exception=True)

       object_key = serializer.validated_data['object_key']

       upload_url_dict = get_presigned_url_dict_to_upload_file(object_key)

       return_serializer = ExampleUploadURLSerializer(
           data={'object_key': object_key, 'upload_url_dict': upload_url_dict,}
       )
       return_serializer.is_valid(raise_exception=True)

       return Response(return_serializer.validated_data, status=status.HTTP_200_OK)

So, after this, we are sending the necessary information to upload the file. And that’s it! We have finished the proposed solution.

I have created a public repo where you can see this little example project to get further insight. If you’d like, you can download it and give it a try for yourself.

Summary

Throughout this blog, I presented a solution for a common problem for developers - managing big files in Django projects that are deployed using Heroku.

I detailed in-depth the defined flow and tools I used, as well as providing some useful tips and examples to help you create a good solution.

However, this doesn’t mean that the workaround we found is the only possible one. But it could very well be the most efficient.

I hope you enjoyed reading and if you have another process that you think is useful, feel free to let us know in the comments section. Thanks for reading!

Building an Engine-modularized API in Rails

GuilleLeopold — Fri, 05 Aug 2022 13:51:33 +0000

When big development teams build an API, one of the main challenges that we face is being able to work together on different features while avoiding bottle-necks or other common issues such as conflicting perspectives or avoid overlapping efforts on particular features.

Because of this, when we started working on our latest project, we decided to work with a new approach; designed to help us scale by splitting the app into microservices. I recommend taking a look into this article to learn more about the approach we took: Monolith First

We knew from the beginning that it wouldn't be easy since this approach is novel and there aren't too many examples regarding APIs built this way. It forced us to think outside the box from the start as we had to devise an approach from the ground up, by using our Rails base project with some common gems and the signup/signin already ready to use.

With all this compiled, we conducted some research, looking for some examples and studying how engines work on Rails. Afterwards, we proceeded to the next step: start working on building a modularized API, leaving behind the classic monolithic architecture.

First steps: Designing the API

Before starting development, it’s crucial to take some time to give a structure to these modules.
The implication is that we must take into account the whole project, and therefore we need to think about how we can separate our application in a way that makes sense to encapsulate certain pieces of code.

In our case, we were working on an e-commerce website, which made us think that some of the larger modules could be the following: catalog, user, orders, payments and admin. Of course this may grow and we are not attached to only using these modules; we may need to add new engines/modules when the app starts growing but at least this will give us the big picture of the app.

Given this, a first picture of the API architecture may look like this:

It may look weird that the engines in the box are the ones that have access to the user engine and not the opposite but when implementing this, we need to have it this way.
To explain this better, let’s take the orders engine as an example:

The order engine has a model called purchase, it represents all the purchases in the system.
Each purchase belongs to a customer (which belongs to the user engine) and a customer can have many purchases in terms of business.

In order to be able to model this properly, we need to add a foreign key to the customer table in the purchases table and because of this, the purchase (and so too the orders engine) will, by definition, need to have access to the user engine.
GuilleLeopold marked this conversation as resolved.
This implies two considerations in terms of code:

We can define the belongs_to association in the purchase model due to orders engine having access to the user engine.
We won’t be able to have the has_many association in the user engine and because of that, if we need to have all the purchases for a user, we will need to define a scope in the purchases model that retrieves that information.

Building an engine

After going through the first steps, the benefits of working with an API built with engines are already visible. The modules make it easier to split the team and start working on different features at the same time (let’s say: a pair of devs in the catalog, another pair in the admin and a few ones in the user engine).

But it also made us feel uncomfortable as the lack of information, especially in terms of configuration and how to work between engines were a constant issue during the first few weeks.

We decided to implement some scripts that would help us when we created new engines and we also wrote down some guides. At this point the collaboration between our development team was really important to learn how to deal with the engines.

Having said that, the following is a helpful step-by-step guide on what to do when adding a new engine.

The first step, of course, is to create the engine. To achieve that, rails provides a command with some flags:

rails plugin new engines/engine_name --mountable --skip-test --dummy-path=engines/engine_name/spec/dummy

.
Let’s got a bit deeper on how this command is built:

The --mountable flag means that we want to create the engine inside an isolated namespace. * The --skip-test flag means that we don’t want the engine to include the scaffold for the testing suite as we are going to install rspec.
The --dummy-path is used to define the path where we want to generate the dummy app that "works as the main app" when running the test suite. Following this, we started by cleaning our engine, removing a lot of unnecessary files, adding some common configuration and copying some files that we need across all the engines. After building a few engines, we decided to improve our experience and create our own script to create the engine getting some files from an "engine template" and also complete the following forementioned steps. The script basically does the following: * Runs the command to create the engine * Removes some unnecessary folders and files * Copy some files to the engine, like a generic gemspec with gems that we use in all the engines. I.e: rspec, rails, pg, rubocop, etc. * Installs rspec * Runs bundle install and remove some new unnecessary files * Copy a generic version spec_helper, rails_helper. * Rename/adapt some filenames to the standard that we are following. The script looks like this:

I won’t go deeper on which files we removed or we added as this may change according to the needs of each project but I would like to mention a few configurations that are needed to make this work properly and are going to save you a couple of headaches. 1. Related to the migrations, we want each engine to have it owns migrations files, to achieve this we added the following block of code in lib/engine_name/engine.rb:

So, with this code we are telling Rails to look for new migrations in the db/migrate folder that belongs to the engine. 2. We want to be able to define a routes file in each engine and have the ability to have access to those endpoints from the main app. An easy way to achieve this and keeping it generic, is adding this piece of code in the routes.rb in the main application

This is iterating over the engines directory and mounting the routes of each engine. 3. A similar approach is taken to load all the engines in the gemfile in the main application.

By creating the script and adding these configurations into the main application, we were able to simplify a lot of the processes to add new engines and we ensured that all the engines are going to follow the same standard. ## Developing and testing a feature: considerations and tips Now that we have gone through all this process that may seem extra thorough at the beginning, we are ready to start. At this point, if everything is ok, there shouldn’t be many problems or inconveniences as we are going to be doing pretty much what we already used to do while developing features in Rails. There are still a few considerations related to how engines work that are worth mentioning: * An engine works like a library, so when adding dependencies in between, we must take care to avoid circular dependencies. This means that if we have the engines A, B and C; if the engine A can see B and B can see C, then A may be able to see C but C shouldn’t be able to see either B or A. GuilleLeopold marked this conversation as resolved.

Following on from this, when adding a dependency between engines, we need to add this one into the gemfile that belongs to that engine, not the gemspec. We will also need to add the engines that the other engine has as dependencies too. GuilleLeopold marked this conversation as resolved.
When installing a new gem, in order to be able to use it across the whole engine, we should require it in lib/engine_name.rb
As a result of the engine namespace models, services, controllers and even the tables in the database will be namespaced too.
Some tips I suggest:
- Create an engine that is visible in all the engines across the application. This engine will help us reduce repeated code and may contain things that we want to use in all the engines. In our case, we have an engine called Api that handles all the requests validations (checking headers, render some common errors, etc) and all the main controller from other engines inherit from a controller located in the Api engine
- Create “libraries” that work as interfaces between our API and external services. I.e: In our case we have a gem called Catalog Providers and inside it we have services for each provider that we use in our system (like Target, Amazon, BestBuy)
- It might be useful to create a few scripts to run migrations and test suite or install gems across all the engines. The scripts will iterate over the engines folder and run the command inside each one.
Finally, it's worth to mention two ways to handle the escenario where we need to trigger an action in an engine where we don't have access from the engine we are currently working:
- Using an async pattern like queue with pub/sub where the element that is running publishes a message in the queue and the element that is responsible of running the desired triggered action is subscribed to that queue and reads any message to know which action has to take.
- The other pattern that works fine is implementing an observer pattern, in our application we followed this pattern as Rails already has a good implementation of it for ActiveRecord. This pattern works by having classes called observers that are responsible of beware of any action happening in the "observed class" and trigger actions depending on what action was taken in the followed class. Using the User and Payment engines where Payment can access to User but User can't access to Payment to avoid having a circular dependency, let's see step by step how we implement the observer pattern in our application:
  1. Create an observer class inside our models folder in the Payment engine as we want to trigger an action in this engine as a consequence of an action in the User engine.
  2. Set up the observer in the engine.rb file by adding the following line:
  3. Implement your observer, we need to specify which model we want to observe and implement an action according that behaves similar to a callback in ActiveRecord. It might look like this:
  4. Finally, if you want to disable observers while running rspec, you can add this line in your test suite as a before action:
    
    On the other hand, testing inside an engine with rspec is quite similar to what we are used to doing, it provides us with some guarantees and the only considerations that took us some time are:
We will need to load manually factories from other engines when using FactoryBot in our engine
We need to require in our rails_helper.rb any development dependency that we are using in our test suite After developing a feature, one of the advantages that we found out about working with engines is that we can just run the test suite for the engine where we have been working on without the necessity to go through all the suite tests in the application. This reduces the time to run tests locally dramatically. The API architecture and the project structure will look something like this:

Summing up

It’s been a while since we started working with this project structure. Right now we are at a point where we can already look back and find the pros and cons of making this particular decision:
Pros:

Helps to parallelize work when working with medium-sized development teams.
Makes the code more organized and easier to read or find where a feature should be implemented.
The possibility to run tests inside an engine scope reduces time when testing locally.
A modular application like this is a mid-step between a monolith API and microservices.
Possibility to pick a full engine and use it in another API. We did this with our catalog engine and an admin that we develop in another project. Cons:
Lot of configuration and changes are needed when starting working with engines, as a consequence it requires a bit of time during the first weeks.
Lack of information on the internet, building an API with engines doesn’t seem to be a popular choice.
Despite our effort to avoid repeating code, we repeat even more code than when working in a monolith api. After overcoming the initial learning curve, we feel quite comfortable working with engines and we found out the benefits of having chosen this architecture instead of a monolith one, so I think that I would use it again if it fits the project requirements. In spite of that, we still have a lot to learn and improve upon what we already did. As a pending feature, we would also like to see how we could take advantage of this architecture and try to deploy our application into microservices; of course that implies some changes will need to be made but it would be a valuable achievement. ## Learning about engines and references When we started our investigation on how to build our application, we learned a few things from this Medium post: The Modular Monolith: Rails Architecture To learn more about engines, the Ruby on Rails official documentation is a good follow-on reading.

Read this article and more content in the Rootstrap blog: https://www.rootstrap.com/blog

How to Effectively Integrate a Typography System in React Native

Agustina Chaer — Tue, 05 Jul 2022 15:17:34 +0000

The Problem

If there is one thing that most react native apps have in common, it is how they display text. Some simple apps show very little, but most apps display a lot. That is why it's vital to put the right system in place, to ensure adding and refactoring texts in your app is as simple as possible.

Now, you might be thinking - why am I reading an article on how to manage such a simple component? It's just text, right? Yes, but more often than not, you need to apply styles and properties to said text to make it look the way you want. When you have to do it for all the texts in your app, it adds up. This, of course, begs the question - how can I reduce the amount of code repetition?

Over the years, I have seen my fair share of attempts at solving this problem, and I can finally say that I have landed on one solution that left me quite pleased.

The Solution

The solution is quite simple, but it's based on following best UI practices. What do I mean? Having predefined styles for headings, paragraphs, and other texts that you might need. What is important is that all the texts of your app fall into one of those definitions and that the amount doesn't get out of hand. It's good to keep the number of definitions short, so it's easier to remember what to put when coding and that your app is consistent in its respective styling, which in turn, gives you usability and accessibility points.

Without any further ado, here is the aforementioned code of the component and supplementary files:

Once you have all of that in place, you can simply import the component and use it as follows:

It's as simple as that, and usually, you will only have to apply extra styles to a particular text component instance if you need to add spacing, color, or wrapping.

Taking the naming convention and hierarchy of text components from the web makes it very easy to understand and remember. As you may have noticed, with the use of prop-types, it is very easy to notice if you misspelled a type when setting it on an instance of said component.

Although adding custom fonts to your React Native project is out of scope for this article, you might find (link here) this article useful where we cover that subject (How to customize fonts in React Native)

Conclusion

As you can see, the solution is very clean and simple, but it fixes a problem in a component that is so basic that it is also often overlooked. Putting a bit of time and thought into these kinds of components that make up the core DNA of our apps can go a long way.

I hope you find this article helpful and that you end up implementing this solution in your projects.

Digital Accessibility 101: The importance of Digital Accessibility

Agustina Chaer — Tue, 05 Jul 2022 14:56:41 +0000

This is the first installment of a series of articles where we are going to dive into digital accessibility. Some of the topics that are going to be covered are:

Why is this subject so important?
Why should you make your sites/applications accessible?
How can you make your site/app accessible?

In this article, we are going to tackle the first two questions.

Why is Digital Accessibility so Important?

It is estimated that over 1.2 billion people live with some form of disability. This makes up approximately 15% of the population. As you can imagine, just as with the real world, people with disabilities encounter barriers to navigate the digital space on a daily basis.

When done right, the digital medium can be a great tool for people with disabilities as it can enable them to do things that they couldn’t do before or make a task more effortless. Some examples of this are:

A blind person reading the news with their computer using a screen reader whereas before there were only newspapers.
A physically disabled person opting for online shopping vs going to the store in person.
A hard-of-hearing person opting for the online version of a class they are attending at a university because it’s close-captioned.
A speech-impaired person filling in a contact form or ordering food with an app because calling is not an option or they would have needed to ask someone else to do it for them.

There are many more examples just like those. That being said, the one thing they all rely on to actually work is that they need to be accessible. We can easily transform the examples above so they are not useful anymore:

The news site is not coded properly, it does not have the correct text hierarchy. Without going into too much detail, the site becomes just a big blob of text to the tools a blind person would use to navigate the site making it unusable. The blind person would need to find another place to get the news from.
The e-commerce site is not keyboard accessible so many of the physically disabled people that don’t use a mouse to navigate the web wouldn’t be able to shop online in that store. They would need to find another site or go to the store in person.
The university uploads the class but doesn’t add any closed captions or transcripts making it useless for the hard of hearing.
The restaurant has a web page showcasing their menu but the only way to order is by calling the phone number on their site, speech impaired people would probably order someplace else that is accessible.

With the digital medium becoming more and more popular, the lack of digital accessibility can become even prohibitive and exclusionary. Think how many things you do on a normal day that involves interacting with a website or an app?

How would you feel if those sites and apps weren’t built in a way that you could use them? You would feel left out and you would probably find it harder to get things done.

The Curb Cut Effect

The curb cut effect is the phenomenon that occurs when disability-friendly features end up benefiting a larger group of people than the people it was originally designed for.

The name comes from the curb cut ramps installed for people in wheelchairs, those ended up being really useful to other people. For example, parents pushing strollers, workers pushing heavy carts, business travelers wheeling luggage, even runners and skateboarders.

The same can be identified in many places in the digital space. One very clear example that probably most people have used is the addition of closed captions, now included in all streaming services and video platforms.

Closed captions have allowed hard-of-hearing people to watch and understand content in a way they couldn’t before. They also allow everyone to watch content in a foreign language or watch a video without audio if needed too, especially in situations like being at a library without headphones.

We all suffer at some point some kind of disability, limitation or impairment

To further solidify the concept of “Accessibility benefits us all” let’s talk broaden the scope and talk about disabilities, limitations and impairments:

Permanent: These are the ones we normally think about when we think of disabilities (Visual, Auditory, Cognitive, Physical, and Speech).
Temporary: Ear infection that prevents you from hearing properly for a while or you broke your arm and now can’t use a mouse to use your computer for a couple of weeks.
Situational: You are on a bus and want to watch a video but you forgot your headphones so you need close captions. Even something as simple as looking at your phone outside if it’s very bright, not enough contrast ratio on an app you might be using might make it unusable in that situation.
Socioeconomic: Using a very old device with a poor internet connection in a site that has not been optimized for those conditions can result in a very poor experience for the user.

As you can see the lack of accessibility affects us all to some degree.

Why Should You Make Your Site/Application Accessible?

The simplest answer to the question above is that “It’s the right thing to do”. That alone should be enough to convince you. It should be a no-brainer that making your products usable by anyone and not excluding more than a billion people is the way to go.

What you might not know is that by doing the right thing, you will also be benefiting your company in a lot of ways. Some of them are:

Reach a wider audience, hence more customers and more revenue.
Better SEO (Search Engine Optimization), which means that people will find you more easily when using search engines like Google.
Better user experience for all users can help with user retention.
Avoid potential discrimination lawsuits, if you want to know more here is a good article about digital discrimination lawsuits in the US.

What Comes Next?

Now that we have talked about why accessibility is so important and why you should make your site/application accessible, it’s time to start the journey of making your site/application accessible.

To help you in that journey, we’ll be posting more articles in the upcoming weeks that will touch on key things you need to do and take into consideration.

How to Test React Native Apps

Manuela Viola — Thu, 23 Jun 2022 20:06:49 +0000

Introduction

Have you ever had a bug introduced by solving another problem and didn't realize it until weeks later? This could have been easily avoided if you had tests for your App.

In a project with a tight schedule, tests are generally the first thing to be forgone, but they are being underestimated. Once you make that click and understand how to create tests, it's not that complicated to add them and avoid future problems.

Overview

In this article, you will learn how to test React Native Apps using jest and @testing-library/react-native.

About @testing-library/react-native

One important thing to point out is that this testing library has changed many times and migrations were needed from one version to another. This tutorial will work with the latest version at the time of writing it (7.0.1). For migrations, you can check their migration guide.

App to be tested

For this tutorial, we are going to use this simple app, but of course, you can apply everything learned in any app you want. In this app, we just have two simple screens with some components we can test.

Configuration

Since we are going to use the @testing-library/react-native library, we need to install it. To use the specific 7.0.1 version we can install it like this:
npm install @testing-library/react-native@7.0.1

We also need to configure jest. We should create a jest.config.js file in the projects root folder and for our example, we can fill it with this content:

module.exports = {
  preset: 'react-native',
  modulePathIgnorePatterns: ['extras'],
  setupFiles: [
    '<rootDir>/node_modules/react-native-gesture-handler/jestSetup.js',
  ],
  transformIgnorePatterns: [
    'node_modules/(?!(jest-)?react-native|react-(native|universal|navigation)-(.*)|@react-native-community/(.*)|@react-navigation/(.*)|bs-platform|@rootstrap/redux-tools)',
  ],
  verbose: true,
};

I will mention some of these configurations later in this tutorial and you can find more information here.

Tests folder

As you can see, our project already has a __tests__ folder with an App-test.js file inside. This tests if the app is created and rendered correctly.

Creating tests

To actually create a test, we should create a file with a .spec.js extension inside the __tests__ folder. We could even add folders inside to better organize the tests, for example, add a folder called screens and have one test per screen inside.

Inside these tests, we are going to use describe() just to describe what we want to test, it() (same as test()) to create the tests we want to have, expect() to assert our expected behavior and beforeEach() to execute some code before each it() test. Here is a complete list of jest methods to use inside tests.

Correspondingly, we use the @testing-library/react-native library to test our components behavior. We could use fireEvent to fire a button pressed event or waitFor() to wait for promises results. Here is a cheat sheet with the possible methods to use.

Notice that to know how to ask for a specific component, we can simply add the testID="componentId" property to the component we want to identify. To simplify, I already added this property to all the components we are testing.

Creating tests for our App

Now we need to create our own tests, so we can test our MainScreen and SecondaryScreen. We can create the screens folder inside the __tests__ folder to have better organized tests.

Also, we are going to need some extra files to handle navigation and screen parameters data, so we can create an extras folder inside the __tests__ folder for this purpose. If you paid attention you may have noticed that we added modulePathIgnorePatterns: ['extras'] to the jest.config.js file. This is to tell jest to ignore the .js files that this folder contains, otherwise, it will consider them as tests and we don't want that.

Navigation helper

To test our app we need to start on some screen. If we use a simple render AppStack we would always start on the same screen and we would need to have some flow to go to a different one. To avoid this, we could just start our stack with the screen we want and if we need to test our screen redirecting to some other screen we just need to add that other screen to the stack for the test to work.

Keeping this in mind, we will create a helpers.js file inside the extras folder that looks like this:

import React from 'react';
import {NavigationContainer} from '@react-navigation/native';
import {createStackNavigator} from '@react-navigation/stack';
import {render} from '@testing-library/react-native';

const Stack = createStackNavigator();

const renderOtherComponents = (otherComponents, screenConfig = {}) => {
  return otherComponents.map(({name, component}) => {
    return (
      <Stack.Screen
        {...screenConfig}
        key={name}
        name={name}
        component={component}
      />
    );
  });
};

export const renderWithNavigation = (
  mainComponent,
  {otherComponents = [], navigatorConfig = {}, screenConfig = {}} = {},
) => {
  const App = () => (
    <NavigationContainer>
      <Stack.Navigator {...navigatorConfig}>
        <Stack.Screen
          {...screenConfig}
          name="TestNavigator"
          component={mainComponent}
        />
        {otherComponents &&
          renderOtherComponents(otherComponents, screenConfig)}
      </Stack.Navigator>
    </NavigationContainer>
  );

  return {...render(<App />)};
};

We will get more into detail when we use it in the SecondaryScreen test.

MainScreen test

Inside the screens folder, we should create the MainScreen.spec.js file.

Since we are in the AppStack's first screen we can just render the entire AppStack and it would start rendering the screen we want.

This file should test the MainScreen components existence and behavior:

It renders the MainScreen component
It renders the button-to-secondary-screen component
When pressing button-to-secondary-screen component, it redirects to the SecondaryScreen component
It renders the alert-button component
When pressing alert-button component, it shows an alert

Each of these items should translate to an it() jest method and so our MainScreen.spec.js file should look like this:

import {act, fireEvent, waitFor} from '@testing-library/react-native';
import {Alert} from 'react-native';
import AppStack from '../../src/navigators/AppStack';

import {renderWithNavigation} from '../extras/helpers';

describe('<MainScreen />', () => {
  let wrapper;

  beforeEach(() => {
    wrapper = renderWithNavigation(AppStack);
  });

  it('should render the main screen', () => {
    expect(wrapper.queryByTestId('MainScreen')).toBeTruthy();
  });

  it('should render the go to secondary screen button', () => {
    expect(wrapper.queryByTestId('button-to-secondary-screen')).toBeTruthy();
  });

  describe('when go to secondary screen button is pressed', () => {
    it('it should render SecondaryScreen ', async () => {
      act(() => {
        fireEvent.press(wrapper.queryByTestId('button-to-secondary-screen'));
      });
      await waitFor(() =>
        expect(wrapper.queryByTestId('SecondaryScreen')).toBeTruthy(),
      );
    });
  });

  it('should render the alert button', () => {
    expect(wrapper.queryByTestId('alert-button')).toBeTruthy();
  });

  describe('when take alert button is pressed', () => {
    it('it should render an Alert ', async () => {
      const alertSpy = jest.spyOn(Alert, 'alert');
      act(() => {
        fireEvent.press(wrapper.queryByTestId('alert-button'));
      });
      await waitFor(() => expect(alertSpy).toHaveBeenCalled());
    });
  });
});

SecondaryScreen test

Inside the screens folder we should create the SecondaryScreen.spec.js file.

Since we are not in the AppStack's first screen and our screen receives parameters, we are going to take advantage of the helper we created. We will call the function renderWithNavigation with these parameters:

mainComponent: SecondaryScreen
otherComponents: [{name: 'MainScreen', component: MainScreen}]
screenConfig: {initialParams: { screenParameters }}

We will create a data.js file inside the extras folders to set our screenParameters:

export const screenParameters = {
  paramOne: 'This is a parameter that is a text',
  paramTwo: {
    content: 'This is a parameter that is an object with a content',
  },
};

This file should test the SecondaryScreen components existence and behavior:

It renders the SecondaryScreen component
It renders the back-button component
When pressing back-button component, it redirects to the MainScreen component
It renders the title component
It renders the param-one component
It renders the param-two-content component

Notice that our param-one and param-two-content only render if they have content to render, so if our tests pass means that the screen is getting the parameters right!

Our SecondaryScreen.spec.js file should look like this:

import {act, fireEvent, waitFor} from '@testing-library/react-native';

import {screenParameters} from '../extras/data';
import {renderWithNavigation} from '../extras/helpers';
import SecondaryScreen from '../../src/screens/SecondaryScreen';
import MainScreen from '../../src/screens/MainScreen';

describe('<SecondaryScreen />', () => {
  let wrapper;

  const otherComponents = [{name: 'MainScreen', component: MainScreen}];

  beforeEach(() => {
    wrapper = renderWithNavigation(SecondaryScreen, {
      otherComponents,
      screenConfig: {
        initialParams: screenParameters,
      },
    });
  });

  it('should render SecondaryScreen', () => {
    expect(wrapper.queryByTestId('SecondaryScreen')).toBeTruthy();
  });

  it('should render the go back button', () => {
    expect(wrapper.queryByTestId('back-button')).toBeTruthy();
  });

  describe('when go back button is pressed', () => {
    it('it should render MainScreen ', async () => {
      act(() => {
        fireEvent.press(wrapper.queryByTestId('back-button'));
      });
      await waitFor(() =>
        expect(wrapper.queryByTestId('MainScreen')).toBeTruthy(),
      );
    });
  });

  it('should render title', () => {
    expect(wrapper.queryByTestId('title')).toBeTruthy();
  });

  it('should render param one', () => {
    expect(wrapper.queryByTestId('param-one')).toBeTruthy();
  });

  it('should render param two content', () => {
    expect(wrapper.queryByTestId('param-two-content')).toBeTruthy();
  });
});

Running tests

To run the tests we just simply need to execute npm test. This command will run all the tests we have under the __tests__ folder. If we want to just run one particular test, we can do npm test __tests__/screens/one_particular_test.js instead.

We can see how our tests run successfully:

Debugging tests

If we want to debug our tests we can use ndb.

To use this, first, we need to install it, as the documentation explains, by running npm install ndb and you can add the -g option to make it global.

Then, we can configure our project by setting the value "test:debug": "ndb jest", inside our package.json file under the "scripts" section (we can put it right after the "test" value).

Finally, we can debug our tests by running npm run test:debug and this will install Chromium where you will be able to set breakpoints in your tests and debug them.

Mocks

Since our app was really simple, we didn't need to implement mocks, but it's really an important part of testing react native apps. I will explain why we need them and how we can create them.

The first thing you need to know is that there are lots of functionalities you will have to mock in order to use and test. For this purpose, you can create a __mocks__ folder inside the __tests__ one. Every file in there will be named after a react native library, so when you are testing something that uses that library, jest will take and use the implementation made in the mock.

Let's exemplify. Suppose that in our project we have a backend we access through a URL that we have saved in an .env file with the name API_URL and we use the library react-native-config to access that information. Our tests won't be able to access that .env file, so instead, we have to mock it. We would create (if we haven't already) the __mocks__ folder and inside we would create a file named react-native-config.js that contains the URL we want, like this:

export default {
  API_URL: 'https://mock.com/api'
};

A slightly more complex example would be if we use an ImagePicker to access our photos gallery. Let's say we use the react-native-image-crop-picker library and in our code we call ImagePicker.openPicker() expecting a selected image as a result. If our test calls the button that opens the picker expecting a selected image as a result but we don't have the picker mocked, our test would fail, getting a null result, which is not what we expected. So, we have to create our react-native-image-crop-picker.js file and inside we could have something like this:

export default {
  openPicker: jest.fn().mockImplementation(() => Promise.resolve(result))
};

What we are doing here is mocking our openPicker function, by saying it is a function (jest.fn()) and that its mocked implementation would be Promise.resolve(result). Notice that since our real openPicker is a promise, our mocked implementation is also a promise. We can decide if we want our mocked promise to be completed successfully (with Promise.resolve()) or if we want it to fail (with Promise.reject()). We also decide if we want to return something, like in this case, we are returning result. A question you might be asking is, how do I test both fail and success results by only mocking one openPicker function? Well, the answer is quite simple actually, and it would look like this:

export default {
  openPicker: jest
    .fn(() => Promise.resolve(result)) // default implementation
    .mockImplementationOnce(() => Promise.reject(result)) // first time is called
    .mockImplementationOnce(() => Promise.resolve(result)), // second time is called
};

By using the method mockImplementationOnce() we can give different behaviors to our function, depending on each time you call it. So in this case, the first time we call it we would get a rejected promise (for example to mock that we don't have access to the gallery yet), the second time would be a successful case with our expected result and if we were to call it more times it would use the default implementation inside the fn() method, which in this case would also be successful.

Summary

In this tutorial, we saw how to use jest and @testing-library/react-native to test React Native Apps. You can find the complete GitHub project (with tests included) here.

Read this article and more content in the Rootstrap blog: https://www.rootstrap.com/blog/how-to-test-react-native-apps/

How to customize fonts in React Native

Manuela Viola — Thu, 23 Jun 2022 19:38:27 +0000

Introduction

At Rootstrap, my first assignment was to develop a React Native application, that involved maps, chat, and following the design specifications to the letter. While doing this, one of the first things I tried was to set the family font that the application uses, and I found out it wasn't as easy as I expected.

The biggest issue was that all the tutorials said to execute react-native link, which in my experience was a bad idea because afterwards the application stopped building successfully. This occurs because since React Native 0.60 released, there is a property called Autolinking that changed how to link a library, as this post explains.

Overview

In this tutorial, you will learn how to add and link fonts manually, without using the link command.

First, you will see all the configurations that need to be done to use custom fonts and then you will learn its usage in a simple application.

Configuration

Create Project

First of all, you should create a project in react native. To do that, open the terminal and navigate to the folder you want to create your project in, and execute:

react-native init customize_fonts_react_native_tutorial

Install libraries

After creating the project, some libraries need to be installed:

cd customize_fonts_react_native_tutorial
npm install --save react-native-global-props
npm install --save babel-plugin-module-resolver

Download and rename fonts

Since this is a tutorial about customizing fonts, you will need to have some fonts downloaded, in order to add them to your React Native project.

There are many places where you can get these customized fonts. For this tutorial, I used two different fonts, GoodFeelingSans and Dan'sDisney. In both cases, I ended up with a .ttf file.

In iOS, it is important for the font filename to be the same as its PostScript name. To find the PostScript name, open your ttf file with Font Book, see what its PostScript name is and rename the font to it.

Configurations in React Native

To use your custom fonts in a React Native project, each platform requires a different configuration, but there are also some general configurations all platforms need.

General

In both cases, you will need to create these folders in your project's root: src/assets/fonts. Inside the fonts folder, you should add you custom fonts .ttf files, one for every font you want to use.

Also, modify babel.config.js adding this code:

plugins: [
    [
      'module-resolver',
      {
        alias: {
          assets: './src/assets',
        },
      },
    ],
  ],

Android

In Android, you need to add this folders into android/app/src/main/ : assets/fonts. You should also add your ttf files to the fonts folder.

iOS

In iOS, the configuration is a little more tricky. You need to go to ios/ folder and open the
customize_fonts_react_native_tutorial.xcodeproj file with Xcode.

Afterwards, you need to press on customize_fonts_react_native_tutorial -> Build Phases and find the Copy Bundle Resources section.

You should add your fonts by pressing the plus symbol, then Add Other... option, select your fonts from your src/assets/fonts folder and Finish.

Usage

Finally, after all these steps you will be able to use customized fonts in your React Native project.

As an example, you can create a very simple screen, just to test everything is configured correctly. Add in src folder App.js and styles.js files.

App.js:

import React from 'react';
import {SafeAreaView, Text, TextInput} from 'react-native';
import {setCustomText, setCustomTextInput} from 'react-native-global-props';
import styles from './styles';

const App = () => {
  const customTextProps = {
    style: {
      fontFamily: 'GoodFeelingSans',
    },
  };

  setCustomText(customTextProps);
  setCustomTextInput(customTextProps);

  return (
    <SafeAreaView style={styles.container}>
      <Text style={styles.header}>How to Customize Fonts in React Native</Text>
      <Text style={styles.textDefaultFont}>
        This is the default font (GoodFeelingSans)
      </Text>
      <Text style={styles.textDifferentFont}>
        This is a different font (DansDisneyUI)
      </Text>
      <TextInput value="This input has default font" />
      <TextInput
        value="This input has a different font"
        style={styles.inputDifferentFont}
      />
    </SafeAreaView>
  );
};

export default App;

styles.js:

import {StyleSheet} from 'react-native';

const differentFont = "Dan'sDisneyUI";

const styles = StyleSheet.create({
  container: {
    alignItems: 'center',
    flex: 1,
    justifyContent: 'space-around',
  },

  header: {
    fontSize: 18,
    fontWeight: 'bold',
    margin: 15,
    textAlign: 'center',
  },

  inputDifferentFont: {
    fontFamily: differentFont,
  },

  textDefaultFont: {
    fontSize: 16,
    marginVertical: 15,
    textAlign: 'center',
  },

  textDifferentFont: {
    fontFamily: differentFont,
    fontSize: 16,
    marginVertical: 15,
    textAlign: 'center',
  },
});

export default styles;

Also modify index.js to point to new ./src/App instead of ./App.

In this app, you are using the react-native-global-props library to set a custom font as default, in case you have an entire app with some default font. This is not necessary if you don't need it, you can just set the custom font only in the texts you want. Note how you can still do this even if you define a default custom font. Also note that there are two different default settings, one for the Text component and another for the TextInput.

Now, if you execute react-native run-ios or react-native run-android you should see the text with your custom fonts.

iOS "Unrecognized font family" error

After following all these steps, if you are getting the very common Unrecognized font family error, there are still some things you can check or do.

First, you should check your info.plist file, located in the ios/customize_fonts_react_native_tutorial folder. This file must have a section with key UIAppFonts that contains an array of strings with your fonts. If this is missing, then you should add this:

<key>UIAppFonts</key>
    <array>
        <string>GoodFeelingSans.ttf</string>
        <string>Dan'sDisneyUI.ttf</string>
    </array>

If your project has multiple build targets, you should apply this change to their respective info.plist files.

After this, if you are still getting the error, you could try doing some (or all) of the things listed below:

Uninstall app from simulator (or device)
Delete node_modules folder, package-lock.json file and execute npm install
In ios folder delete Pods folder, Podfile.lock file and execute pod install
Reset cache by runnning npm start --reset-cache command

I hope after doing all this, you now have your new custom fonts working!

Summary

In this tutorial, you learned how to add, link and use custom fonts in React Native. You can find the GitHub project here.

Read this article and more content in the Rootstrap blog: https://www.rootstrap.com/blog/how-to-customize-fonts-in-react-native/

AppleAuth: Ruby Gem for Apple Sign in Rails Integration

Antonieta Alvarez — Fri, 10 Jun 2022 15:37:36 +0000

What is AppleAuth?

AppleAuth is a Ruby gem we developed to integrate Apple Sign In in our server side applications.

Apple announced Sign in with Apple in the WWDC 2019 Conference, then in September 2019 Apple updated its App Store Review Guideline to state that if your iOS app implements a third-party or social login service (like Facebook Login or Google Sign-In) it will be mandatory to offer Apple sign in as an option by the end of April 2020. Besides following the standards, implementing apple authentication will let sign in using their two-factor authentication Apple ID. After the user follows Sign in with Apple to log in, your app receives tokens and user information that you can use to authenticate the user in your server.

Apple sign-in workflow

For more information, check the Apple Official Documentation

How does AppleAuth works?

Validation

Apple authentication follows the OAuth 2.0 flow, and this gem will help us with this flow. After the user signs in the client-side, we will have access to the user_identity, code, and JWT on our server-side. The last one is a token that will be used to validate user authentication with Apple. So Apple_Auth's first step will be to decode and validate the JWT.

# with a valid JWT
user_id = '000343.1d22d2937c7a4e56806dfb802b06c430...'
valid_jwt_token = 'eyJraWQiOiI4NkQ4OEtmIiwiYWxnIjoiUlMyNTYifQ.eyJpc...'
AppleAuth::UserIdentity.new(user_id, valid_jwt_token).validate!
>>  { exp: 1595279622, email: "user@example.com", email_verified: true , ...}

# with an invalid JWT
invalid_jwt_token = 'eyJraWQiOiI4NkQsd4OEtmIiwiYWxnIjoiUlMyNTYifQ.edsyJpc...'
AppleAuth::UserIdentity.new(user_id, invalid_jwt_token).validate!
>> Traceback (most recent call last):..
>> ...
>>  AppleAuth::Conditions::JWTValidationError

Authentication

If we successfully validate the JWT, we can authenticate users and get their information. At this point, we can persist refresh-token, to once a day, and if needed get a fresh token from Apple and ensure that the user continues to have their apple_id validated.

code = 'cfb77c21ecd444390a2c214cd33decdfb.0.mr...'
AppleAuth::Token.new(code).authenticate!
>> { access_token: "a7058d...", expires_at: 1595894672, refresh_token: "r8f1ce..." }

DeviseTokenAuth Integration

If you already have DeviseTokenAuth gem implemented on your Rails project, you can just run this generator:

$ rails g apple_sign_in:appple_auth_controller [scope]

In the scope you need to write your path from controllers to your existent devise controllers and set up the routes.

This generator will create a controller, that implements AppleAuth methods, get the user's email, and register them.

You can find more info and the guide to install the gem on the README.
You can find a full implementation of this gem in this demo.

Read this article and more content in the Rootstrap blog: https://www.rootstrap.com/blog

Testing in Django & Django REST – Useful Tools & Best Practices

brunomichetti — Mon, 06 Jun 2022 19:44:10 +0000

If you are a developer, you already know how important testing is in any software project. In particular, automatic testing, as it can help you to corroborate your coding, and quickly see what your program does what you want it to do. It also helps to corroborate any new changes in your code that didn’t break any previous functionalities.

In saying that, does this mean that if you have automatic tests then your project won’t have any errors? It does not. As computer scientist Edsger W. Dijkstra once said:

“Program testing can be used to show the presence of bugs, but never to show their absence”.

This phrase helps us to understand that we can’t be sure that a program is perfect, but, testing is fundamental to help us discover errors and make fixes and improvements. As a person that works in software development, I can say that it’s a lot better when you discover an error rather than your client or a user in production. In this article, I’ll talk about basic knowledge in automatic testing, useful tools, and good practices in Django projects, with a focus on API’s.

Testing in Django & Django REST Framework

Django has very nice documentation about testing, and Django REST Framework too. So, in this blog, I’ll talk about the main tools in those two frameworks, and what you can do and use to improve your testing.

Main Testing Classes

Django provides several classes for testing. The one I’ll talk about here is TestCase, which is very useful if your application uses databases.
As the name states, to create a test case in your Django project, you will define a class that inherits from TestCase. By doing this, you can use all the methods and properties of the named class that will help you to create and execute your tests. Then you will define different functions that will correspond to each unit test inside the test case. Let’s see an example of the structure of a test case:

# your test file
from django.test import TestCase


# class to define a test case for login
class UserLoginTestCase(TestCase):

    ...
    # some setup here, explained later

    def test_correct_login(self):
        # unit test
        # Corroborate the expected scenario
        ...

    def test_if_password_incorrect_then_cant_login(self):
        # unit test
        # Corroborate that user's password needs to be only the correct one
        ...

    def test_if_user_not_registered_cant_login(self):
        # unit test
        # Corroborate that user's are able to login only if they're registered

    ...

Also, you can use the Client class of Django which simulates a dummy browser so you can make HTTP requests and test how your Django API responds.

Since we are focusing on API testing, I want to talk about APITestCase, a class of Django REST framework that is a mirror of TestCase but uses a different client class: APIClient. This client extends the TestClient, meaning that it has the same functionalities and adds others such as the credentials function. This function is very useful to overwrite authentication headers, for example, using OAuth1, OAuth2, or any simple token authentication scheme.
So, if you are working on a project with the Django REST framework, you can change the previous example in this way:

# your test file
from rest_framework.test import APITestCase


# class to define a test case of login
class UserLoginTestCase(APITestCase):

    ...

Main Testing Functions

The aforementioned classes each have a set of methods that will help you through the testing. With these functions, you are able to corroborate that your software works as expected and make necessary test fixtures.
A test fixture is an environment that you can create to run your tests using consistency. Using fixtures you can make sure that certain conditions are met before the execution. For example, to have a determined set of data in your testing database, or to create needed objects. Here is a list of the main ones:

setUp and tearDown: These are functions to be executed before (setUp) and after (tearDown) in each unit test. These are very useful for fixtures.
setUpClass and tearDownClass: In an analogous way of setUp and tearDown, these functions are executed before (setUpClass) and after (tearDownClass) during the whole test case. This means that it is executed only once for a test case. Since they’re used by Django to make important configurations, if you overwrite these methods in your test case class, don’t forget to call the super implementation inside the functions.
setUpTestData: this function can be used to have a class-level atomic block to define data for the whole test case. That means that this function automatically rollbacks the changes in the database after the finalization of all the unit tests in the test case. This is mainly used to load data to your test database.
Assert methods: Django has the set of assert methods from unittest, and has another ones created for the framework. These methods, such as assertEqual, assertIsNone, assertTrue, etc, can be used in the unit test to check the different conditions that have to be met. For example, in the unit test of login, you can assert that the response has a status code of 200 because you want to make sure that if the data is sent correctly, then your application has to return the response with that code.

You can avoid using these functions, or use any combination of them. They’re not needed, but they’re very useful and will help you a lot.

Test Discovery & Databases

Where do you have to put your test classes? By default, Django recognizes any file that fulfills the pattern test*.py under the current working directory. That is, any file under the directory that starts with a test, and of course, has the .py extension. Inside it, Django will execute any function in the test case class starting with test.
When you run your tests, you can pass a parameter indicating the desired pattern just in case you want to use a different one. With that behavior, the place to put the test cases can be anywhere, but I recommend dividing the tests into the several Django apps that you may have in your project. For example, if you have a Django app called users that has the models and functionalities related to the users in your project, you can define in there a test folder as a module (adding the init.py file) with all the tests that cover that important part: tests for login, for sign-up, for user data, account deletion, etc. Something similar to this:

my_project
   |__django_apps
       |__users
          |__test
             |__ __init__.py
             |__ test_login.py
             |__ test_signup.py
             |__ test_delete_user.py
             ...
        ...
    ...
...

Regarding the databases, when you run your tests by default, Django creates one and then destroys it after the finalization. This is to avoid conflicts between your production and/or development databases, as well as your testing database. You can define and customize a database for tests, inside the DATABASES dictionary, adding another one named TEST. Something like:

DATABASES = {
    'default': {
        'ENGINE': '<engine>',
        'NAME': '<database name>',
        'USER': '<database user>',
        ...
    },
    ...
    'TEST': {
        # testing database customization here
            'NAME': '<your testing database name>',
            # some other customization, for example the user user, password, etc
        },
}

Take a look at the available keys for the TEST dictionary. If you don’t define it, Django will create a database naming it equal to your database in the default settings, appending the _test suffix.

Useful Tools

In this section, I will talk about two external tools that are very helpful for fixtures: Faker and Factory Boy.

Faker

Faker is a python package used to generate fake but realistic data. You can use its functionalities to load data into your testing database, generate data for the requests that you want to test, generate data for the models, etc. Faker has a huge and diverse set of possibilities. You can generate execution time, for example, first names, last names, phone numbers, dates, passwords, emails, etc.

Additionally, you can pass parameters to the functions to generate data with different constraints, for example, you can obtain a password specifying if you want to use special characters or not, the desired length, and if you want to have an upper case or not, etc. Take a look at the Faker providers to see all the different fake but realistic data that you can generate for your tests. Instead of using for example user_test@mail.com for your test cases, you can have data that is closer to reality and improve the quality.

Factory Boy

If you use factories for tests, you define in a class the data structure that you want to have in your testing database. Then in your tests, it will be easier to have instances of your models, and loaded data with the desired structure. Factory Boy is a tool to replace static, hard-to-maintain fixtures using factories. Also, you can combine it with Faker to have factories with fake but realistic data. Let’s see an example:

In this case, we can see a static fixture of Django, to load data to the testing database in a model called Person, which has a first name and last name. This JSON file defines two instances:

[
  {
    "model": "myapp.person",
    "pk": 1,
    "fields": {
      "first_name": "John",
      "last_name": "Lennon"
    }
  },
  {
    "model": "myapp.person",
    "pk": 2,
    "fields": {
      "first_name": "Paul",
      "last_name": "McCartney"
    }
  }
]

Now let’s see the analogous definition using Factory Boy and Faker:

from factory import django, Faker
from myapp import models 

class PersonFactory(factory.django.DjangoModelFactory):

    class Meta:
        model = models.Person

    first_name = Faker('first_name')
    last_name = Faker('last_name')

With this, you can use functions that Factory Boy provides, for example, PersonFactory.create_batch(2) to create instantly 2 instances in your testing database of Persons with different and realistic first and last names. In the JSON case, if you want to have for example 10 instances, you will need to add them and define new first and last names explicitly. And if you want to have huge datasets, the JSON file will be enormous and hard to maintain, while in the factory case you only need to call a function. Also, what if the model Person changes? In the JSON case, you have to update one by one each defined instance. In the factory case, you only need to change a class definition. Factory Boy documentation has a section called common recipes, where you can find useful tools, practices, and tips from the library. Here is a list of interesting functionalities:

You can create factories of models including the model relationships using the RelatedFactory or SubFactory class.
Use the create function to create a new instance of the model in the factory and save it into the testing database. If you want to have instances but without saving them into the database, use build instead.
In an analogous way, you can create and save into the database N instances of the model in the factory using create_batch(N), and build_batch(N) if you don’t want to save them.
You can define an attribute in a factory that selects a choice of a set of choices just like a Django model choice field, using random_element of Faker. In the next section, we will see an example of this.

Test Example & Good Practices

In this section, I want to wrap up and show a little example. This is the tiny reality: In the project, we have a Django app called users where we have the user model that has a username, phone_number, and a category in the system, that could be admin, common user, and guest. The user can sign-up and login into the application.

Model & Factory Definition

# model.py in the Django app called users
from django.db import models
from django.contrib.auth.models import AbstractUser


# class to define choices
class Category(models.TextChoices):
    GUEST = 'G', 'Guest user'
    COMMON_USER = 'C', 'Common user'
    ADMIN = 'A', 'Admin user'


# user model that inherits from AbstractUser
# there is no need to define a username field
# because is defined in the parent class
class User(AbstractUser):
    phone_number = models.CharField(max_length=50, blank=True, null=True)
    category = models.CharField(
        max_length=1,
        choices=Category.choices,
        default='G',
    )

Now, let’s see the implementation of the user factory. This file is inside a test folder in the users Django app:

# factory.py inside users/test
from faker import Faker as FakerClass
from typing import Any, Sequence
from factory import django, Faker, post_generation

from users.models import User, Category


CATEGORIES_VALUES = [x[0] for x in Category.choices]


class UserFactory(django.DjangoModelFactory):

    class Meta:
        model = User

    username = Faker('user_name')
    phone_number = Faker('phone_number')
    category = Faker('random_element', elements=CATEGORIES_VALUES)

    @post_generation
    def password(self, create: bool, extracted: Sequence[Any], **kwargs):
        password = (
            extracted
            if extracted
            else FakerClass().password(
                length=30,
                special_chars=True,
                digits=True,
                upper_case=True,
                lower_case=True,
            )
        )
        self.set_password(password)

A couple of things about this:

In the Meta class inside the factory, we have to indicate the corresponding model.
In the category attribute, we use random_element of Faker to randomly select a choice of the Category choice list. We’ve defined CATEGORIES_VALUES to specify which part of the choice we want to take. That is because each element in the choices list is a tuple, where the first part is the value, and the second one the explanatory text. So, that CATEGORIES_VALUES set has only that first part for each element.
Through the post_generator decorator and the password function, we indicate that at the moment of the creation of a user instance, we can pass a desired password to be used, or else we generate one using the Faker functionality.

Django Test Case

Now, let’s see an example of testing for the user sign-up functionality. The implementation of the authentication part for this example project has been made using dj-rest-auth. I won’t talk about that, but if you want to know more, please take a look at this blog. This is a test_singup.py file inside the test folder of the user Django app:

from django.urls import reverse
from rest_framework import status
from rest_framework.test import APITestCase, APIClient

from users.test.factory import UserFactory
from users.models import User, Category
from faker import Faker


class UserSignUpTestCase(APITestCase):

    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        cls.user_object = UserFactory.build()
        cls.user_saved = UserFactory.create()
        cls.client = APIClient()
        cls.signup_url = reverse('rest_register')
        cls.faker_obj = Faker()

    def test_if_data_is_correct_then_signup(self):
        # Prepare data
        signup_dict = {
            'username': self.user_object.username,
            'password1': 'test_Pass',
            'password2': 'test_Pass',
            'phone_number': self.user_object.phone_number,
            'category': self.user_object.category,
        }
        # Make request
        response = self.client.post(self.signup_url, signup_dict)
        # Check status response
        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
        self.assertEqual(User.objects.count(), 2)
        # Check database
        new_user = User.objects.get(username=self.user_object.username)
        self.assertEqual(
            new_user.category,
            self.user_object.category,
        )
        self.assertEqual(
            new_user.phone_number,
            self.user_object.phone_number,
        )

    def test_if_username_already_exists_dont_signup(self):
        # Prepare data with already saved user
        signup_dict = {
            'username': self.user_saved.username,
            'password1': 'test_Pass',
            'password2': 'test_Pass',
            'phone_number': self.user_saved.phone_number,
            'category': self.user_saved.category,
        }
        # Make request
        response = self.client.post(self.signup_url, signup_dict)
        # Check status response
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
        self.assertEqual(
            str(response.data['username'][0]),
            'A user with that username already exists.',
        )
        # Check database
        # Check that there is only one user with the saved username
        username_query = User.objects.filter(username=self.user_saved.username)
        self.assertEqual(username_query.count(), 1)

Well, in this file we have a test case, defined as UserSignUpTestCase, and two unit tests inside, one to test the expected case, and the other to test an error case. I want to list a couple of main points to discuss good practices:

Take a look at the unit tests names: You can name them as you want (always starting with test unless you change the pattern). A good practice is to make a name that describes it. This will help you when testing and debugging, for example, if a test fails and you want to trace the error.
In the setUpClass method, we call the super() function, remembering that it’s important for Django. Also, we set up the needed instances, such as the API client, a user, and a faker instance. Besides we load a user to the database with the create function.
Notice that the sign_up URL defined in the setUpClass method, uses reverse from Django. You can put directly the URL string if you want. By using reverse, you obtain an URL entering the related name. In the dj-rest-auth package, the related name is rest_register. I recommend you use reverse in your project to improve maintainability. When you define URLs, give them a name, and then in the tests use reverse. After that, if a URL changes, you won’t need to change anything in the tests, because reverse solves this.
The general structure chosen for the unit test is:
- Prepare data: You can use the instance generated with build to obtain the data for the request.
- Make the request: Use the APIClient to make the request.
- Check the response: Check the response data (if there is data) and status. When working with Django REST framework, I recommend using status. With this, you have the HTTP status codes in a cleaner way. If you don’t want to, you can just put the number directly.
- Check the database: If the request generates changes in the database, please corroborate it to make sure that the functionality modifies it correctly. If you have the case that doesn’t modify the database, it’s a good practice to test that the database remains without changes (just as in the second unit test).

This was an example of a Test Case with two unit tests. You can add more unit tests, for example, to test if some data is incorrect in the request or the user can’t sign-up. Besides you can add in that file (or another file) more test case classes, for example, to test the login functionality of the app.

Running Your Tests

Once you have coded a couple of tests, you can execute them with this command in the main folder of the project (the one that has the manage.py file):

python manage.py test

This will search for all of your tests files under that folder and then execute them, showing the error or success of each unit test.

Customize the Execution of the Tests

You can customize the test execution, for example, you can indicate to test:

Only a Django app, specifying <Django app name>:

python manage.py test users

Only a file in a given Django app, specifying <Django app name>.path.to.file:

python manage.py test users.test.test_signup

Only a test case class, specifying: <Django app name>.path.to.file.ClassName:

python manage.py test users.test.test_signup.UserSignUpTestCase

Only a unit test function, specifying <Django app name>.path.to.file.ClassName.function_name:

python manage.py test users.test.test_signup.UserSignUpTestCase.test_if_data_is_correct_then_signup

You can also add some flags to the command to customize the execution, for example:

--keepdb to avoid erasing the database between executions. This can improve the speed.
--parallel to run the tests in parallel improving also the speed on multi-core hardware. If you do this make sure they’re well isolated.

Summary

Throughout this blog, I’ve presented some basics of testing with Django and Django REST framework. Also, I showcased some useful tools and good practices that are more focused on API’s. I highlighted some examples, and how to run and customize your tests with the named framework. I hope you enjoyed reading and I hope that this blog can help you to test and improve your own Django API projects.

Read this article and more content in the Rootstrap blog: https://www.rootstrap.com/blog