DEV Community: Enrico Triolo

Mastering the viewBox for fun and profit

Enrico Triolo — Fri, 17 Jul 2020 20:05:59 +0000

This is the first of a series of articles I'm planning to write about a couple of powerful yet fairly simple concepts of the SVG image format: the viewport and the viewBox.
As I'm going to show you, these are very flexible features: indeed they can be (ab)used to obtain many different effects!

In this article I will first introduce the SVG image format. Then I will move on to describe the SVG coordinate system and positioning.

The SVG format

SVG is a rather peculiar format. Unlike raster formats that describe an image through a grid of pixels, SVG describes an image using algorithms that define the shapes and paths that create the complete image.

SVG isn't suited to represent photographic images, but is particularly suited to draw illustrations and icons in a compact way. An SVG image is basically composed of one or more "shapes", each described by a specific mathematical function. Thanks to this, an SVG image can be enlarged/zoomed as much as you want, unlike the raster image formats.

Another difference with the bitmap formats is that SVG is a human-readable text format. In fact an SVG image is nothing more than an XML document. Each shape can be defined using simple textual instructions in the form of XML nodes.

For example, this markup creates an image with a blue circle:



<svg xmlns="http://www.w3.org/2000/svg">
    <circle cx="50" cy="50" r="50" fill="#0971f1"/>
</svg>

The SVG specification defines many other tags that can be used to create both basic and complex shapes, such as rectangles, arcs, ellipses, or "paths", that can be used to define custom shapes using so called "Bezier curves".

Another great feature of the SVG file format, especially when used inside a web page, is that it can be styled in many ways through dedicated css properties or through so called "presentation attributes", i.e. CSS properties that can be used as attributes on SVG elements.

For example, you can change the color of a shape by simply setting the "fill" property.

In the previous example, we indeed defined the color of the circle using the "fill" attribute. Another way would be to assign the circle node a class, and then defining the style rules for that class in a css file:



<svg xmlns="http://www.w3.org/2000/svg">

    <circle cx="50" cy="50" r="50" class="mycircle"/>

</svg>



.mycircle {

    fill: #0971f1;

}

The viewport and the viewBox

The viewport and the viewBox are two very important concepts that affect the size, the position and the visible area of an SVG image.

You can effectively think of the viewport as your mobile phone display with the camera app running.
The viewBox is the part of the scene you see inside the display. You can zoom in and out or move the phone and frame different parts of the scene, so to change the viewBox, but it will always be constrained to the physical size of the display, i.e. the viewport.
Lastly, the whole scene represent your SVG image, the so called SVG canvas.

Inside an SVG document, all measures are unitless: you don't say "this rectangle is 10mm large", you just say "this rectangle is large 10".
In our first example, we are just saying that the circle has its center at (50, 50) (not 50 px or mm) and that its radius is just "50" (and not 50 px). These dimensions are called user units.

The viewport can be set using two attributes on the SVG element: width and height. These represent the width and the height of the "display".
The viewport is specified using one of the units of measure that are known to the user agent: the browser in fact needs to know how much space to reserve in the DOM for the image.
When the viewport is specified in user units, the values are assumed to be in "px".

The viewBox controls which part of the image will be shown and at which size. It is defined using the viewBox attribute on the root SVG element, and its value is a space (or comma) separated list of 4 numbers expressed in user units that describe a rectangle that will be mapped to the size of the viewport. The four numbers represent respectively:

min-x: the horizontal coordinate of the upper left corner of the rectangle.
min-y: the vertical coordinate of the upper left corner of the rectangle
width: the width of the rectangle...
height: you guessed it!

When not specified, the viewBox is assumed to correspond to the SVG canvas.

Some examples

In the following example we are mapping the full SVG canvas to the viewport.
As you can see, the canvas size is 200 x 200, while the viewport size is 50px x 50px. Since the viewBox area has its top-left corner at (0,0), width and height both equal to 200 (which are the same sizes of the canvas), all the image is rendered inside the viewport:

In the next example, the viewBox size is 100 x 100, which corresponds to half of the canvas size. Since the top-left corner of the viewBox is set to (0,0), the viewport will show only the top-left quarter of the image:

This time the viewBox rectangle has its top-left corner right in the middle of the canvas. The width and height of the viewBox are both 100... What we get to see in the viewport is therefore the bottom-right part of the svg:

The preserveAspectRatio attribute

The examples seen till now all have one thing in common: the viewBox has the same aspect ratio of the viewport, i.e. the ratio between the viewBox width and height is the same ratio between the viewport width and height.

But what happens when the viewBox aspect ratio differs from that of the viewport? The preserveAspectRatio attribute controls just this behaviour. Its value is made up of two keywords: the alignment value and the meet or slice reference.

The alignment value determines how the image should be scaled. It can take up to 10 values, the most straightforward of them being:

none: in this case the image will be scaled non uniformely to completeley fit into the viewport without taking into account its aspect ratio.

In all the following cases the image is instead uniformely scaled. These values determine where to position the scaled viewBox with respect to the viewport:

xMinYMin: the min-x and min-y values of the viewBox (the first two numbers) are aligned to the upper left corner of the viewport.
xMidYMin: the horizontal center of the viewBox is aligned with the horizontal center of the viewport while the min-y of the viewBox is aligned with the top of the viewport.
xMaxYMin: the min-x + width of the viewBox (i.e. the "right side") is aligned with the right of the viewport while the min-y of the viewBox is aligned with the top of the viewport.
xMinYMid: the min-x of the viewBox is aligned with the left of the viewport while the vertical center of the vieBox is aligned with the vertical center of the viewport.
xMidYMid: the horizontal and vertical centers of the viewBox are aligned with the center point of viewport.
xMaxYMid: the min-x + width of the viewBox (the "right side") is aligned with the right of the viewport while the vertical center of the viewBox is aligned with the vertical center of the viewport.
xMinYMax: the min-x of the viewBox is aligned with the left of the viewport while the min-y + height of the viewBox (the "bottom side") is aligned with the bottom of the viewport.
xMidYMax: the horizontal center of the viewBox is aligned with the horizontal center of the viewport while the min-y + height of the viewBox (the "bottom side") is aligned with the bottom of the viewport.
xMaxYMax: the min-x + width of the viewBox (the "right side") is aligned with the right of the viewport while the min-y + height of the viewBox (the "bottom side") is aligned with the bottom of the viewport.

The second keyword of the preserveAspectRatio atttibute (the meet or slice reference) is optional and determines how the image should be scaled. It can be one of the two following values:

meet: the default value. The image is scaled such that the viewBox entirely fits into the viewport while preserving its aspect ratio. This means that the viewBox could result smaller than the viewport, depending on their aspect ratios.

slice: The image is scaled such that the viewBox covers the viewport while preserving its aspect ratio. This means that the viewBox could extend beyond the viewport, depending on their aspect ratios.

That's all for now!

Now that we introduced the base concepts we can go on and see how just by changing the numbers of the viewBox we can achieve different "tricks". In the next articles of this serie we are just going to see some of them!

References

Mozilla article on the viewBox
Understanding SVG Coordinate Systems and Transformations (Part 1) — The viewport, viewBox, and preserveAspectRatio by Sara Soueidan - Btw, you should definitely follow her!
Cover photo by Pine Watt on Unsplash

oauth2_client: implement OAuth2 clients with Flutter

Enrico Triolo — Mon, 06 Apr 2020 21:33:47 +0000

In the first part of this article I will give you an overview of the OAuth 2 standard, in particular I will introduce the two most used grants, the Client Credentials and the Authorization Code grants.
In the second part I will introduce oauth2_client, a Flutter library that considerably simplifies working with OAuth 2.
By the end of the article you will be able to implement your own client with just little lines of code.

If you are already familiar with the concepts behind OAuth2, you can directly skip to the hands on section, otherwise keep reading...

What is OAuth 2?

OAuth 2 is an open standard protocol that allows applications to access protected resources of a service on behalf of the user. OAuth 2 defines authorization flows for native apps, web apps and for mobile devices.

Many companies offer OAuth 2 endpoints: these include the usual suspects, such as Google, Facebook, LinkedIn, GitHub, as well as many other.

Generally speaking, an authorization process can be carried on as follow:

The application sends to the authorization server an Authorization Request to access a protected resource
The owner of the resource (usually, the user) grants access to it
The authorization server sends back an Access Token to be used with all the subsequent requests as a sort of authorization badge

This is just an high level depiction of the whole process. The actual flow will differ depending on the authorization grant type in use.

The two most used grant types are the Client Credentials grant and the Authorization Code grant.

The Client Credentials grant

The Client Credentials grant is primarily used on machine-to-machine applications, such as daemons, services or CLI. In this case the authorization server grants access to the application itself rather than to the user.

To use this flow, an application must have been assigned a client ID and a client secret. These parameters are generated by the authorization server, and are needed to ensure that the client connecting is the one that has been authorized.

The authorization process works more or less like this:

The application sends to the authorization server an Authorization Request along with the client id and the client secret.
The authorization server checks the provided credentials
The authorization server sends back to the application an Access Token, along with a Referesh Token.
The application uses the Access Token in every subsequent request to the service.

The Authorization Code grant

The Authorization Code grant is by far the most used flow as it is employed by applications that effectively operate on some user owned resources.

To use this flow, the application must have been registered with the OAuth server, providing at least a name and a redirect URI, that will be used to inform the application that the user authorized the request. During the registration, the provider assigns the application a client ID and a client secret, that will be exchanged in the authorization process.

To access a specific resource, the application should specify one or more scopes, a list of strings that represent the "permissions" the application is requiring. The scopes are defined by the resource server and are normally included in the API documentation of the service.

This flow can be summarized like this:

The user opens up the app
The app opens up a browser instance pointing to the authorization endpoint on the authorization server, requiring permission to access the needed resources, and passing in the Client ID and the list of required scopes.
The user authenticates with the authorization server and grants access to the resources
The authorization server redirects the client to the redirect uri sending an Authorization Token
The client app issues an Access Token Request, passing in the Authorization Token and the client secret.
The server validates the client secret and the Authorization Token and sends back an Access Token and a Refresh Token
The client app uses the Access Token in every subsequent request to the API service as a sort of authorization badge.

The OAuth 2 framework has been designed to be extensible, and as such it underwent some additions since its inception, for example to address potential security flaws or extend its functionalities. One of these is the PKCE extension, designed to increase the Authorization Code grant security through an exchange of a client generated code that limits the chances of the authorization code to be intercepted.

Access Token expiration / invalidation

To limit the risks of token hijacking, the Access Token often has a limited lifespan after which it cannot be used anymore. Moreover, the Access Token could be explicitly invalidated by the resource server.

When the token expires, the application must require another Access Token using another grant type, the Refresh Token grant. As the name suggests, this flow uses the Refresh Token returned by the previous authorization flows to generate a new Access Token that must be used from that moment onward.

Hands on!

By now it should be clear that to implement an OAuth 2 capable application, one must implement not only the authorization process provided by the service he is going to use, but even the mechanisms to deal with the expiration or invalidation of the Access Token. These can easily become quite wasteful activities!

oauth2_client is a Flutter library specifically created with the purpose of simplifying the process of requiring and refreshing the OAuth 2 access token. It provides pre-made classes to authenticate againts the leading providers, such as Google, Facebook, LinkedIn, GitHub, but it's particularly suited for implementing clients for custom OAuth 2 servers.

It additionally provides convenience methods for secure token storage, automatic token refreshing and to transparently perform authenticated HTTP requests.

Suppose we wanted to implement an app with the GitHub API. As per their API documentation, GitHub recommends on using the Web application flow (with the Authorization Code grant).
This means that one of the steps of the process involves opening up a browser instance and intercepting a redirection to a provided redirect uri.

If one of the targets of our app is Android, we first need to set up an Intent Filter in the AndroidManifest.xml file to define a custom uri scheme that will be intercepted by our app:



<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.mypackage">
    ...
    <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
        <intent-filter android:label="flutter_web_auth">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="my.app" />
        </intent-filter>
    </activity>
</manifest>

The value of the android:scheme attribute can be anything you want, and must match the scheme used for the redirect uri (as we'll see later). Just make sure, if at all possible, not to use http(s), because in that case our application won't be able to intercept the server redirection, as it will be automatically handled by the system browser.

If you really want/need to use an HTTPS url as the redirect uri, you must setup it as an App Link.
First you need to specify both the android:host and android:pathPrefix attributes, as long as the android:autoVerify="true" attribute on the intent-filter tag:



<activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
    <intent-filter android:label="flutter_web_auth" 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="https"
                android:host="www.myapp.com"
                android:pathPrefix="/oauth2redirect" />
    </intent-filter>
</activity>

Then you need to prove ownership of the domain host by publishing a Digital Asset Links JSON file on your website. This involves generating an App signing key and signing your app with it.

Our sample app will retrieve the list of the user's repositories. To do so, we must tell the server which "permissions" we'll need, using the scope parameter. The scope that requires access to the user's repositories (both public and private) is "repo".

Before you can interact with GitHub's OAuth 2 endpoint, you must create a new OAuth App. After this step your application will be assigned a clientId and a clientSecret.

Ok, enough of talking... Let's see some code!



import 'package:oauth2_client/github_oauth2_client.dart';
import 'package:oauth2_client/access_token_response.dart';

//Instantiate the GitHub client
OAuth2Client client = GitHubOAuth2Client(
    //Corresponds to the android:scheme attribute
    customUriScheme: 'my.app',
    //The scheme must match the customUriScheme parameter!
    redirectUri: 'my.app://oauth2redirect'
);

//Require an Access Token with the Authorization Code grant
AccessTokenResponse tknResp = await client.getTokenWithAuthCodeFlow(
    clientId: 'myclientid',
    clientSecret: 'myclientsecret',
    scopes: ['repo']);

//From now on you can perform authenticated HTTP requests
httpClient = http.Client()
http.Response resp = await httpClient.get('https://api.github.com/user/repos',
    headers: {'Authorization': 'Bearer ' + tknResp.accessToken});

//The list of the user repositories is encoded in the resp.body property...

As you see, fetching an Access Token is quite simple, and since GitHub tokens don't expire we should be all set... But what happens if the token gets invalidated by the app owner? You would need to check the validity of the token after every request and possibly fetch another token. Something like this:



...
httpClient = http.Client()
http.Response resp = await httpClient.get('https://api.github.com/user/repos',
    headers: {'Authorization': 'Bearer ' + tknResp.accessToken});

//The request to the service didn't succeed...
//We must refresh the token (not supported by GitHub endpoint) or
//generate a new Access Token
if(resp.statusCode != 200) {
    AccessTokenResponse tknResp = await client.getTokenWithAuthCodeFlow(
        clientId: 'myclientid',
        clientSecret: 'myclientsecret',
        scopes: ['repo']);

    //Perform another request to the server with the new access token
    http.Response resp = await httpClient.get('https://api.github.com/user/repos',
        headers: {'Authorization': 'Bearer ' + tknResp.accessToken});
}

Fortunately enough, the library provides an helper class that takes care of all of the burden:



//Instantiate the client...
OAuth2Client client = GitHubOAuth2Client(
    redirectUri: 'my.app://oauth2redirect',
    customUriScheme: 'my.app');

//Instantiate the helper passing it the client and passing in the authorization parameters
OAuth2Helper oauth2Helper = OAuth2Helper(client,
    grantType: OAuth2Helper.AUTHORIZATION_CODE, //default value, can be omitted
    clientId: 'myclientid',
    clientSecret: 'myclientsecret',
    scopes: ['repo']);

//Perform a request to the server
http.Response resp = await oauth2Helper.get('https://api.github.com/user/repos');

As long as the first request is made, the helper class performs the following operations:

Checks if an Access Token already exists in the device storage
If it doesn't exist, generates an Access Token using the required flow (Authorization Code when not specified) and stores it into the device secure storage.
Sends the request to the server, adding the "Authorization" header with the access token
If the server returns an "unauthorized" response, try to refresh the Access Token through the Refresh Token flow, if the service supports it, otherwise generate a new token. Finally, send another request with the new token.

As you see, not only the helper class takes care of the token retrieval/refresh process, it even stores the token in a secure storage on the device. This means that if your app is closed or the device is restarted, the retrieved tokens are still available and can be used without requiring a new authorization process.

That's all well and good, but what if I wanted to implement my own client?

Up until now, we saw how to use a predefined client class, but what if you needed to authenticate against a service that doesn't have a dedicated class?

Implementing your own clients is really simple, and normally requires only a couple of lines of code. For example, let's see how the GitHub client is made:



class GitHubOAuth2Client extends OAuth2Client {
  GitHubOAuth2Client(
      {@required String redirectUri, @required String customUriScheme})
      : super(
            authorizeUrl: 'https://github.com/login/oauth/authorize',
            tokenUrl: 'https://github.com/login/oauth/access_token',
            redirectUri: redirectUri,
            customUriScheme: customUriScheme) {

      //By default, GitHub responds to an Access Token request with a querystring-like
      //format. We need a json formatted response, that can be required through
      //the 'Accept' header...
      this.accessTokenRequestHeaders = {
        'Accept': 'application/json'
      };

  }
}

That's it! You really just need to extend the OAuth2Client class and provide the authorization and the token urls.
After that, you can use your client or even the helper as seen above, without any modifications.

Finally... The inevitable TL;DR

oauth2_client really simplifies working with OAuth 2 endpoints, as it takes care of all the peculiarities of the protocol and automates the process of refreshing the tokens upon expiration. It even transparently implements many of the best practices introduced to enforce the security and reliability of the process.