Forem: Akshay Ram Vignesh

useReport Hook and some thoughts on good API design for libraries

Akshay Ram Vignesh — Sat, 16 May 2020 23:46:37 +0000

This post covers how to embed your Microsoft PowerBi reports into your React application using _ useReport _ hook from powerbi-report-component. I'll go into some depth of inner working of the package and rational behind useReport, and some thoughts on good API design libraries.

TLDR; if you just want to use useReport, here's how it works.

import React, { useEffect, useRef } from "react"
import { useReport } from "powerbi-report-component"

// Some powerbi setting disable your nav and filters from embed
const settings = {
  filterPaneEnabled: false,
  navContentPaneEnabled: false,
}

const MyReport = () => {
  const reportRef = useRef(null)
  // userReport returns `report` the embed instance and setEmbed a function to
  // set your embed into the div
  const [report, setEmbed] = useReport()

  const myReportConfig = {
    embedType: "report",
    tokenType: "Embed",
    accessToken: "", // your access token
    embedUrl: "", // your embed url
    embedId: "", // your embed Id
    settings,
  }

  // !important
  useEffect(() => {
    // call inside useEffect so the we have the reportRef (reference available)
    // pass in the ref for the div and your config
    setEmbed(reportRef, myReportConfig)
  }, [])

  const handleclick = () => {
    // you can use "report" from useReport like
    if (report) report.print()
  }

  return (
    <div className="report-container">
      <div className="report" ref={reportRef} />
      <button onClick={handleclick}>Print my report</button>
    </div>
  )
}

export default MyReport

Now, for those interested in why useReporthook and how it works.

So, what do I mean by good API design?

Let's first see what an API is. API is an acronym for Application Programming Interface. It is a software delegate that allows two applications to talk to each other. When we talk about APIs we are usually referring to REST API or HTTP endpoints.

How does it apply to libraries?

Functions or components exposed by your library are also APIs.As it allows the developer to communicate between their application code and your code that exists in the library.

When I first created the component it allowed you to embed a report in your React application. So it exported React component as a default called Report.

The library user would've imported it and used it like:

import Report from "powerbi-report-component";

<Report
  embedType="report" // or "dashboard"
  ...{otherProps}
/>

(Note: Microsoft PowerBi actually supports multiple types of embeds: Report, Dashboard, Tile)

This made sense at that time. As it would be used to embed only an Microsoft PowerBi Report not Dashboard or Tile. Soon I added embedType as a prop to support embedding Dashboard.

This felt a little odd when you're actually embedding a dashboard and you still had to use a <Report /> and pass dashboard to embedType prop inside your code.

Also, using embedType to determine what kind of props can be passed to the component made the library code bloated and less clean with the use of switch is multiple places.

Soon I started getting feature requests to support Tile and for Create Report feature.

Each embed type had to support a lot more handlers and other properties.

For example, You can have handler onPageChange handler on embedType = report but not in embedType = dashboard or embedType = tile or, You can have a pageView prop for embedType = dashboard but not for embedType = report orembedType = tile.

But, the library just exported a single component (Report) and propTypes of the component looked like this.

Report.propTypes = {
  embedType: PropTypes.string.isRequired,
  tokenType: PropTypes.string.isRequired,
  accessToken: PropTypes.string.isRequired,
  embedUrl: PropTypes.string.isRequired,
  embedId: PropTypes.string,
  pageName: PropTypes.string,
  extraSettings: PropTypes.object,
  permissions: PropTypes.string,
  onLoad: PropTypes.func,
  onError: PropTypes.func,
  onSelectData: PropTypes.func,
  onPageChange: PropTypes.func,
  onTileClicked: PropTypes.func,
  style: PropTypes.object,
  reportMode: PropTypes.string,
  datasetId: PropTypes.string,
}

React component is nothing but a function and props are nothing but parameters that you pass in to the function. This means that Report is one function that you can pass _ 16 _ parameters into. Library user can never actually know which parameter to pass in unless they go and see the documentation every time they had to make a change.

User's IDE intellisense also becomes useless as suggestions will have _ 16 _ props instead of only right props for their use case.

This parameter list was only going to increase in number as I keep adding new handlers or properties based on feature requests. Exporting a single default export of a Report also was not maintainable.

This is an example of a _ bad _ API design. As it doesn't compliment the users development environment like the IDE or doesn't help speed the user's workflow.

Having the embedType as a prop creates confusion here as the user might be using library to embed a Tile but would still be using it as Report in their code.

With this in mind. Maintainers and I went ahead refactored the code to export multiple components as named exports. i.e, Report, Dashboard and Tile with their respective props. Now we have multiple named exports based on embedType which can be imported like. This also made the library code more maintainable.

Now the library can be used like.

import { Tile, Dashboard, Report } "powerbi-report-component";

And the propTypes of respective exports look like:

Report.propTypes = {
  tokenType: PropTypes.string.isRequired,
  accessToken: PropTypes.string.isRequired,
  embedUrl: PropTypes.string.isRequired,
  embedId: PropTypes.string,
  pageName: PropTypes.string,
  extraSettings: PropTypes.object,
  permissions: PropTypes.string,
  style: PropTypes.object,
  reportMode: PropTypes.string,
  datasetId: PropTypes.string,
  onLoad: PropTypes.func,
  onRender: PropTypes.func,
  onError: PropTypes.func,
  onButtonClicked: PropTypes.func,
  onSelectData: PropTypes.func,
  onPageChange: PropTypes.func,
  onCommandTriggered: PropTypes.func,
}

Dashboard.propTypes = {
  tokenType: PropTypes.string.isRequired,
  accessToken: PropTypes.string.isRequired,
  embedUrl: PropTypes.string.isRequired,
  embedId: PropTypes.string.isRequired,
  pageView: PropTypes.string,
  style: PropTypes.object,
  onLoad: PropTypes.func,
  onTileClicked: PropTypes.func,
}

Tile.propTypes = {
  tokenType: PropTypes.string.isRequired,
  accessToken: PropTypes.string.isRequired,
  embedUrl: PropTypes.string.isRequired,
  embedId: PropTypes.string.isRequired,
  dashboardId: PropTypes.string.isRequired,
  style: PropTypes.object,
  onLoad: PropTypes.func,
  onClick: PropTypes.func,
}

This enables the user to use the library without having to go back and see the docs every time and IDE intellisense will suggest the right props which speeds up the developer's workflow and the user doesn't have to go to see the docs every time they had to make a change.

Since, We made the exports from the library more explicit. User will be able use Tile in the place where they are embedding Tile or Dashboard when they want to embed a Dashboard. This solves a lot of confusion and is explicit enough to make sense where it's used in your codebase.

A _ good _ API design for libraries has to get these right:

Complement the tools available in the end user's development environment.
Explicit enough to make sense where it's used.

One way to compliment the user's development environment is enabling IDE intellisense to speed up user's workflow. i.e, by making _ exports explicit _ or using right propTypes like what you just saw.

Another way would be to support multiple ways to use your library based on user's development environment.

The library supported embedding your reports using components by exposing React components. This is one way of sharing code or using the API.

Now, React has hooks to share code. (Read more about it here)

I refactored the library to use the React hooks and it internally looked like this:

// private used inside the library to embed
function _useReport(performOnEmbed = null) {
  // store the embed instance
  const [report, _setEmbedInstance] = useState(null)

  const setEmbed = (embedDivRef, embedConfig) => {
    // validate your configuration passed as props
    const errors = validateConfig(embedConfig)
    if (!errors) {
      embed(embedDivRef.current, embedConfig)
    } else {
      throw new Error("invalid configuration passed")
    }
  }

  const embed = (ref, config) => {
    const { reportMode } = config
    // check reportMode
    const isCreateMode = reportMode === "create"
    let embedInstance

    // call the right powerbi library method
    if (isCreateMode) embedInstance = powerbi.createReport(ref, config)
    else {
      embedInstance = powerbi.embed(ref, config)
    }

    if (performOnEmbed) {
      // add handlers to the embedInstance that are passed as props
      // like onPageChange, onSelectData, etc..
      performOnEmbed(embedInstance, ref)
    }

    // set the embed instance in the state
    _setEmbedInstance(embedInstance)
  }

  // expose embed instance and a method to embed
  return [report, setEmbed]
}

Since, React now enables sharing of code as a hook. I can remove a lot of library specific code and expose this hook for the end user.

// cleaner and a default API to export
function useReport() {
  const [report, _setEmbedInstance] = useState(null)

  const setEmbed = (ref, config) => {
    // create config based on embedType
    const embedConfig = createEmbedConfigBasedOnEmbedType(config)
    // validate the config
    const errors = validateConfig(embedConfig)
    if (!errors) {
      embed(ref.current, embedConfig)
    } else {
      throw new Error("invalid configuration passed")
    }
  }

  const embed = (ref, config) => {
    const embedInstance = powerbi.embed(ref, config)
    _setEmbedInstance(embedInstance)
  }

  // expose instance and method to embed
  return [report, setEmbed]
}

See the full code here

By exporting useReport from the library the user has more than one way to use the library. This adds to the value of the library as it complements the users development environment by the use React hooks.

The hook exposes an internal function as an API for end user to get the most out of the library and by using the hook user can choose to reduce the extra abstraction and logic that comes along with using the API with an component.

This was the rationale behind the useReport hook and my thoughts on good API design for libraries.

Next step in the quest to improve the API design for the library would be add typings and support types. i.e, to add support for Typescript (In progress). In the next post I'll cover some basics of Typescript and more on migrating the library to Typescript.

If you're interested seeing more of the code you can head here: https://github.com/akshay5995/powerbi-report-component/

PRs or issues welcome for the library.

Thanks for your time!

Redux - Predictive state management on the client side

Akshay Ram Vignesh — Sun, 30 Jun 2019 23:46:37 +0000

Hi guys, It’s been a really long time since I wrote a blog post. I’m starting a habit of regularly blogging about the things I learn. I plan to blog about both technical and non-technical subjects.

Without any further ado.

Redux is a state management library for javascript applications. It comes in handy in projects where state management becomes too complicated or state gets difficult to keep track. Redux helps us by making the state predictable, centralized, debuggable and flexible.

Let’s get into the details of what those mean in a minute. Let’s look at the Flux architecture first. You might be thinking, “Flux? Why?” .

It’s really important as Redux was inspired by the Flux architecture. Bear with me.

Flux

Flux is a pattern for handling data in your application. Flux and React grew up together in Facebook. Just like Redux, Flux and React are mostly used together in applications even though they can be used independently.

Flux was created to fix a very specific problem at the time in facebook. I highly recommend you read this amazing intro to Flux by Lin Clark.

Flux and Redux are fundamently very similar. You can’t directly mutate the store without firing an action.

The underlying problem they were trying to solve at facebook was the way dat flowed through the application.

They had models which held the data and would pass data to the view layer to render the data. There were several scenarios by which your model can get updated. An user interaction can update the model or, a model can update another model. There were even complex scenarios where cascading updates. Lin in here article makes an analogy of “Throwing a whole bag of ping-pong balls into your Pong game, with them flying all over the place and crossing paths”. There updates also happened asynchronously. This made things very hard for debugging.

Solution : Unidirectional Data Flow

Facebook came up with this unidirectional data flow architecture where data flow only in one directi. And, they called it Flux.

This is what data flow in flux looks like:

I’ll not go deeper into Flux in this article as it’s about Redux. I highly recommend that you to read about the flux architecture.

Now back to Redux.

Redux was inspired by Flux architecture. Dan Abramov wanted to improve flux. He wanted to make better tooling around the state management ecosystem and make it extensible. (like, Time travel debugging).

According to official Redux's official site. Redux can be explained using the follwing Principles.

Single Soure of truth.
State is read only.
Changes are made with pure functions

Redux is made up of the following entities:

Action creators
Reducers
Store
View i.e, Smart and Dumb components

The store

I. Single source of truth

The store is the data store a place store all your information. By definition of First Principle. The store is the single source of truth for your application.

Reducers

II. State is read only

“To specify how the state tree is transformed by actions, you write pure reducers.”

Reducers are pure functions that take the previous state of the app and return a new state based on the action passed to it.

They look something like this:

const initialState = {}

const myReducer = (state = initialState, action) => {
  switch (action.type) {
    case "ADD_TODO": {
      const { id, todo } = payload
      return { ...state, [id]: todo }
    }
  }
}

Action creators

Actions are events that happen in your application which can change in your model (store). They are the only way you can send data from your application to your Redux store.

Actions are plain JavaScript objects and they must have a type property to indicate the type of action to be carried out. They must also have a payload that contains the information that should to worked on by the action.

Actions have this signature:

{
  type: "UPDATE_MY_STORE",
  payload: {
    "dummy": "data"
  }
}

Actions are created by functions called Action creators. They look something like this:

const signIn = (username. password) => {
  return({
    type: types.SIGN_IN,
    payload: {
      username,
      password
    }
  });
}

III. Changes are made with pure functions

We dispatch these action using the store's function and the Reducer (a pure function) receive's this action and current state and gives us the new state.

Views (Smart and Dumb)

Views are just the components that subscribe to the store.

Smart components = Containers

Dumb Components = Presentational Components

Smart components can be though of as an inteface between your Redux store and the Dumb components. They only deal with the subscription and passing down of actions and/or state from the store to the Dumb components. Do not email any DOM of their own.

Dumb components are purely responsible for rendering the DOM. Hence are called Presentational Components. They receive the actions and state as props passed to them by the container components.

This distinction is an important pattern followed as a standard across most projects you'll come across. Read more

These are some important points to remember when you work with redux:

The only way a user should be able to mutate state is through actions.

Reducers are pure functions in a state tree. Your app’s state properties are each represented by a function that provides updates to their state. Each reducer is unique to each state property and vice versa.

The store is singular and contains the entire state of the app. When we use it this way, we can track each and every change to the state of the app.

Reducers can be thought of as behavioral definitions of state tree properties.

If you're building a small application I suggest you use React's component state or the new Context API to share state among your components. Don't make Redux your defacto state management tool for all your React apps or projects.

(Tradeoffs) Redux asks you to:

Describe application state as plain objects and arrays.
Describe changes in the system as plain objects.
Describe the logic for handling changes as pure functions.

Okay, You don't have to take my word for it. Instead, believe Dan.

There are tradeoffs in any solution you pick so choose wisely by carefully analysing your use case and the list of available solutions. I always recommend starting with something minimal and moving to something advanced when you hit a roadblock.

If you're interested in how redux works under the hood. I highly recommend you try implementing Redux from scratch.

Hope I this article was worth your time. Thank you for reading :)

React's Context API By Implementing a Simple Snack Bar

Akshay Ram Vignesh — Sat, 15 Sep 2018 23:46:37 +0000

In React, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of data that is required by many components within an application. Context provides a way to share values like these between components without having to explicitly pass a prop through every level of the tree.

I'm sure we all have had requirement where we had to implement snack bar for our react application. I'll be showing you how to implement simple snack bar using the React's Context API in this article. Little background before we dive deep. The Context API before React 16.3 was available as an experimental API. Now it's not experimental anymore and has been shipped as a part of React 16.3+ versions for quite some time. The goal of the article is to build a minimal Snack Bar component and to understand how to use the Context API and it's use case.

This is a more complex example than the one provided in the official documentation. Context is designed to share data that can be considered "global" for a tree of React components. Here in our example we'll be using context to pass down data and handler functions that's needed to control opening/closing our SnackBar anywhere inside your app and as well as data needed for our SnackBar. Let's use create-react-app to bootstrap a new app called react-context-demo.

File names are provided in comments above every snippet use the same to create files accordingly.

createContext

/* file: SnackBarContext.jsx */

// Default State of our SnackBar
const DEFAULT_STATE = {
  show: false, // boolean to control show/hide
  displayText: "", // text to be displayed in SnackBar
  timeOut: 2000, // time SnackBar should be visible
};

// Create our Context
const SnackBarContext = React.createContext(DEFAULT_STATE);

The created context(SnackBarContext) has properties { Provider, Consumer }.When React renders a context Consumer, it will read the current context value from the closest matching Provider above it in the tree.

Provider

<Provider value={/* some value */} />

A React component that allows Consumers to subscribe to context changes. It accepts a value to be passed on to Consumers that are descendants of this Provider.

Now Let's create a Provider called SnackBarProvider.

/* file: SnackBarContext.jsx */

export class SnackBarProvider extends PureComponent {
  constructor(props) {
    super(props)
    // DEFAULT_STATE defined earlier
    this.state = Object.assign({}, DEFAULT_STATE)
    this.handleClose = this.handleClose.bind(this)
    this.handleOpen = this.handleOpen.bind(this)
  }
  handleOpen(displayText) {
    // Show the SnackBar with 'displayText'
    this.setState({
      show: true,
      displayText,
    })
    setTimeout(
      // To hide SnackBar after 2s
      () => this.setState({ show: false }),
      this.state.timeOut
    )
  }
  handleClose() {
    // Show the SnackBar with 'displayText'
    this.setState({
      show: false,
      displayText: "",
    })
  }
  render() {
    return (
      <SnackBarContext.Provider
        value={{
          ...this.state,
          handleOpen: this.handleOpen,
          handleClose: this.handleClose,
        }}
      >
        {this.props.children}
      </SnackBarContext.Provider>
    )
  }
}

The SnackBarProvider will be a stateful component which will return it's children (this.props.children) inside the SnackBarContext.Provider to provide necessary values (State's Data and Handlers) to be passed on to SnackBarContext.Consumer used by our SnackBar component some where down the component tree of it's children. (!important)

Inside the SnackBarProvider we assign DEFAULT_STATE to this.state. DEFAULT_STATE has the default values to be passed down to the Consumer.

We need our SnackBar to be stateful for showing and hiding. State's show property will be a boolean used for showing or hiding our SnackBar. Functions handleClose and handleOpen are used as handlers for state changes to do the same in the will be used in our SnackBar.

handleOpen will accepts an argument displayText the text to displayed in our SnackBar and sets displayText and show to true. And, handleClose will change the show to false and displayText to it's default state i.e, empty string.

Inside render we'll our SnackBarContext.Provider to which will pass in prop named value our SnackBarProvider's state (…this.state) and our handlers (handleOpen and handleClose). SnackBarContext.Provider will enclose our SnackBarProvider's children so we can use SnackBarContext.Consumer access these values and functions down the our children's component tree.

Now that we're done with our Provider let's see how to use our Consumer.

Consumer

<Consumer>
  {value => /* render something based on the context value */}
</Consumer>

Consumer takes a function as a child. The value parameter of the function is the one that contains our prop value passed to our closestProvider.The function receives the current context value and returns a React node. Let's see how we'll use it in our case.

We'll have a SnackBar component which will use the props from our Provider to control it's visibility (show/hide functionality).

const SnackBar = ({ show, handleClose, displayText }) => (
  <div className="snackBarHolder">
    {show && ( // controls visibility
      <div className="snackBar">
        <span>
          {
            displayText // text to be displayed
          }
        </span>
        <button onClick={() => handleClose()}>OK</button>
      </div>
    )}
  </div>
)

show will control the visibility, handleClose will be used by the button in our SnackBar to force the SnackBar to hide and displayText is the main text that will be displayed in our SnackBar.

So we know that our SnackBar component requires props show, handleClose, displayText for it to work as required. Let's see how to use SnackBarContext.Consumer to get the required props.

So we'll create a Higher Order Component that will take a Component as a parameter and passes the value from Provider as props to that Component. Let's call it withSnackBarConsumer.

/* file: SnackBarContext.jsx */

export const withSnackBarConsumer = WrappedComponent => {
  const WrapSnackBarConsumer = props => (
    <SnackBarContext.Consumer>
      {({ show, displayText, handleOpen, handleClose }) => {
        const snackBarProps = {
          show,
          displayText,
          handleOpen,
          handleClose,
        }
        return <WrappedComponent {...snackBarProps} {...props} />
      }}
    </SnackBarContext.Consumer>
  )
  return WrapSnackBarConsumer
}

Here, withSnackBarConsumer will accept a WrappedComponent as a parameter and returns WrapSnackBarConsumer which wraps the WrappedComponent with SnackBarContext.Consumer by using our function as a child signature of Consumer.

Using the Consumer we get the values (show, displayText, handleOpen, handleClose) provided by our Provider and pass these values (snackBarProps) to our WrappedComponent as props. We can use our withSnackBarConsumer to wrap our SnackBar like:

*/* file: SnackBar.jsx */*

import { withSnackBarConsumer } from './SnackBarContext';

const SnackBar = ({ show, handleClose, displayText }) => (
  <div className="snackBarHolder">
   {
    show // controls visibility
    && (
      <div className="snackBar" >
       <span>{
         displayText // text to be displayed
        }</span>
       <button onClick={() => handleClose()}>
          OK
        </button>
      </div>
     )
   }
  </div>
);

export default withSnackBarConsumer(SnackBar);

Now that we have connected (Just like Redux, eh ?) our SnackBar to values provided by our SnackBarProvider.

We can start on how to use the same withSnackBarConsumer to provide other components in our app ability to make our SnackBar visible using handleChange.

Let's create a SnackBarControl a button with handleOpen using withSnackBarConsumer HOC.

/* file: SnackBarControl.jsx */

import { withSnackBarConsumer } from "./SnackBarContext";

const SnackBarControl = ({ text, handleOpen }) => (
  <button onClick={() => handleOpen(text, buttonText)}>Show me!</button>
);

export default withSnackBarConsumer(SnackBarControl);

SnackBarControl uses our handleOpen from our SnackBarProvider. We connected SnackBarControl to handleOpen using the our withSnackBarConsumer.

Now that We have SnackBarControl, SnackBar, SnackBarProvider let's see it in action.

/* file: App.js from create-react-app */

import React, { Component } from 'react';
import { SnackBarProvider } from './SnackBarContext';
import SnackBarControl from './SnackBarControl.jsx';
import logo from './logo.svg';
import './App.css';

class App extends Component {
  render() {
    return (
      <SnackBarProvider>
         <div className="App">
            <header className="App-header">
             <img src={logo} className="App-logo" alt="logo" />
             <h1 className="App-title">Welcome to React</h1
             </header>
             <SnackBarButton text="Hey There!"/>
          </div>
        <SnackBar />
     </SnackBarProvider>
     );
   }
}

export default App;

Add these styles for your SnackBar inside App.css to make it look like a real snackBar!

/* file: App.css from create-react-app */

.SnackBarHolder {
  position: fixed;
  z-index: 50;
  bottom: 20px;
  left: 50%;
  -webkit-animation: fadein 0.5s, fadeout 0.5s 2.5s;
  -moz-animation: fadein 0.5s, fadeout 0.5s 2.5s;
  -ms-animation: fadein 0.5s, fadeout 0.5s 2.5s;
  -o-animation: fadein 0.5s, fadeout 0.5s 2.5s;
  animation: fadein 0.5s, fadeout 0.5s 2.5s;
}
@-webkit-keyframes fadein {
  from {
    bottom: 0;
    opacity: 0;
  }
  to {
    bottom: 20px;
    opacity: 1;
  }
}
@keyframes fadein {
  from {
    bottom: 0;
    opacity: 0;
  }
  to {
    bottom: 20px;
    opacity: 1;
  }
}
@-webkit-keyframes fadeout {
  from {
    bottom: 20px;
    opacity: 1;
  }
  to {
    bottom: 0;
    opacity: 0;
  }
}
@keyframes fadeout {
  from {
    bottom: 20px;
    opacity: 1;
  }
  to {
    bottom: 0;
    opacity: 0;
  }
}
.SnackBar {
  width: 250px;
  padding: 10px;
  background: black;
  display: flex;
  align-items: center;
  justify-content: space-between;
  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
}
.SnackBar > span {
  color: white;
}
.SnackBar > button {
  background: transparent;
  color: #00b4d2;
  outline: none;
  border: 0;
  cursor: pointer;
}

Click on Show me! to see the magic ✨.

Congrats, You've successfully implemented a simple snack bar using React's Context API.

Please do read the official docs for better understanding.

JavaScript, The Beast Within

Akshay Ram Vignesh — Mon, 27 Aug 2018 23:46:37 +0000

I was amused by JavaScript ever since I saw the things that can be done using it and the ease, with what we can achieve such things. I've been working with React JS and Node JS for almost a year and a half now. Needless to say, I'm a big React fanboy.

Recently, I've started to understand what's really going on under the hood and behind all those layers of abstraction presented to us as developers. This revelation has made go back to basics and understand workings of JavaScript in detail 😲

Every time I look back at all the work I've achieved with JS without knowing really anything about its inner workings is really amusing to me. Please, take that as an ode to the JavaScript community. You guys are amazing 🙌

Note: In this article, I hope to cover introduction to JS and 4 topics/ features that intrigued me about JavaScript and made me an avid reader of MDN Web Docs and other JS related articles. It'll be useful for folks just getting started with JS or, it'll act as a refresher for the experienced.

I hope you too get inspired to understand this mysterious world of JavaScript 🌎 (or, just learn something new 😉).

Here’s a little introduction to JS from my personal favourite.

JavaScript is notorious for being the world’s most misunderstood programming language.

It is often derided as being a toy, but beneath its layer of deceptive simplicity, powerful language features await.( Async pun, eh ? 😜 )

JavaScript is now used by an incredible number of high-profile applications, showing that deeper knowledge of this technology is an important skill for any web or mobile developer.

Unlike most programming languages, the JavaScript language has no concept of input or output. It is designed to run as a scripting language in a host environment, and it is up to the host environment to provide mechanisms for communicating with the outside world.

Host environment is usually a browser.

JavaScript interpreters can also be found in a huge list of other places, including Adobe Photoshop, SVG images, server-side environments such as Node.js, NoSQL databases like the open source Apache CouchDB, embedded computers, complete desktop environments like GNOME (one of the most popular GUIs for GNU/Linux operating systems), etc.

JavaScript is a multi-paradigm, dynamic language with types and operators, standard built-in objects, and methods. Its syntax is based on the Java and C languages — many structures from those languages apply to JavaScript as well.

I’ll also point you to some articles, if you wish to read more. These can be features of ES6 or it’s predecessors.

What’s with the name ?

or, What's ECMAScript ?

JavaScript was created in 1995 by Brendan Eich (Netscape Engineer). It was originally named Mocha and was changed to be called LiveScript, but it was renamed after a marketing decision that attempted to capitalise on the popularity of Java language at that point in time.

Netscape submitted JavaScript to ECMA (a European standards organisation), it resulted in the first edition of the ECMAScript standard that year.

The standard received a significant update as ECMAScript edition 3 in 1999, and it has stayed pretty much stable ever since.

The fourth edition was abandoned, due to political differences concerning language complexity. Many parts of the fourth edition formed the basis for ECMAScript edition 5, published in December of 2009, and for the 6th major edition of the standard, published in June of 2015.

So in conclusion, I believe JavaScript is considered the Language which implements a standard called ECMAScript.

JavaScript is the implementation of the standard that is, ECMAScript.

Prototypal Inheritance and Classes

One of the most fascinating features for me personally

What's prototypal inheritance you ask ?

JavaScript only has one construct: objects. Each object has a private property which holds a link to another object called its prototype.

That prototype object has a prototype of its own, and so on until an object is reached with null as its prototype. By definition, null has no prototype, and acts as the final link in this prototype chain. Nearly all objects in JavaScript are instances of Object which sits on the top of a prototype chain. Every object in JS can have another object as its prototype. Then the former object inherits all of latter's properties.

An object specifies its prototype via the internal property [[Prototype]]. The chain of objects connected by the [[Prototype]] property is called the prototype chain

The __proto__ property exposes the internal prototype linkage.

prototype vs __proto__

The prototype is a property on a constructor function that sets what will become the __proto__ property on the constructed object.

var animal = {
  eats: true,
  walk() {
    console.log("walking!!")
  },
}

var rabbit = {
  jumps: true,
  __proto__ : animal,
}

var bugsBunny = {
  likesEating: "Cartoon Carrots",
  isCartoon: true,
  __proto__ : rabbit,
}

bugsBunny.walk() // walking!!!
// resolved by going up the prototype chain to 'animal'

console.log(bugsBunny.jumps) // true
// resolved by going up the prototype chain to 'rabbit'

Now, tell me about classes ?

Okay, Now classes in JavaScript are just syntactic sugar on top of it's prototypal inheritance.( Making prototypal inheritance more classy for all OOPs people out there 😅)

ES6 introduced a new set of keywords implementing classes. i.e, class, constructor, static, extends, and super

I'm gonna let you take it from here to find out more about classes.

_Sources: Classes

What is "this " ?

Spoiler: it's just spell binding

this behaves a little differently in JavaScript compared to other languages. It also has some differences between strict and non-strict mode in Javascript.

The value of this is determined by how a function is called.It can't be set by assignment during execution, and it may be different each time the function is called.

Global Context

In non-strict mode by default this points to the global window object in browser, and in strict mode by default this is undefined.

In browser
console.log(this === window); //true

In Node
console.log(this === global); //true

'use strict'
console.log(this); //undefined

Function Context

The value of this remains at whatever it was set to when entering the execution context.

To pass the value of this from one context to another, use call, or apply:

var obj1 = { a: "Custom" }

var a = "Global"

function whatIsA() {
  return this.a
}

console.log(whatIsA()) //Global

console.log(whatIsA().call(obj1)) //Custom

Bind()

ES5 introduced a new function for Function.prototype called the bind().

Calling func.bind(someObject)creates a new function with the same body and scope as func, but where this occurs in the original function, in the new function it is permanently bound to the first argument of bind

// function WhatIsA from the above example
var obj2 = { a: 'I'm Object 2's a!' };

var whatIsAInObj2 = whatIsA.bind(obj2);

console.log(whatIsAInObj2()); // I'm Object 2's a!

Arrow Functions

With the introduction of arrow functions this retains the value of the enclosing lexical context's this.

var obj = {
  bar: function() {
    var x = () => this
    return x
  },
}

var fn = obj.bar()

console.log(fn() === obj) // true

I can keep going.But, for more on this take a look at the MDN Docs. 😉

Note: Read about how this binding is only affected by the most immediate member reference.

Hoisting ⬆️

Up and up and up ? ( Coldplay fans will get it 🎶)

Hoisting came in to picture or specification only with ES6.

Hoisting was thought up as a general way of thinking about how execution contexts (specifically the creation and execution phases) work in JavaScript.

A definition of hoisting might suggest that variable and function declarations are physically moved to the top of your code.

It's not true , the variable and function declarations are put into memory during the compile phase, but stay exactly where you typed them in your code.

console.log(sayHello("world!")) // Hello world!

console.log(a)

// undefined and not 'ReferenceError' due to hoisting
console.log(sayOla("world!"))

// TypeError: sayOla is not a function
function sayHello(param) {
  return "Hello " + param
}

var a = 1
var sayOla = function(param) {
  return "Hello " + param
}

Above example shows hoisting in action. Conceptually, how your run time sees it is.

function sayHello(param) {
  return "Hello " + param
}

var a
var sayOla

console.log(sayHello("world!")) // Hello world!
console.log(a)
// undefined and not 'ReferenceError' due to hoisting
console.log(sayOla("world!"))
// TypeError: sayOla is not a function
a = 1
sayOla = function(param) {
  return "Hello " + param
}

Note: only declarations are hoisted but not assignments. also, class declarations are not hoisted.

Now, Let's bring it to a "Closure" 🔚

Another JS pun (sorry!)

A closure is the function bundled together (enclosed) with references to its surrounding state (the lexical environment).

Closure gives you access to an outer function's scope from an inner function. In JavaScript, closures are created every time a function is created, at function creation time.

function outerFunction() {
  var x = "Hello "
  return function(param) {
    return x + param
  }
}

var newFunc = outerFunction()

console.log(newFunc("World!")) // Hello World!
// Even after returning the function has access to variable x

Closures are usually used to give objects data privacy and to fix order of partial application of functions.

// partial application

function makeAdder(x) {
  return function(y) {
    return x + y
  }
}

var add5 = makeAdder(5)

console.log(add5(10)) // 15

I hope this article got you inspired or curious to learn more about JavaScript.

PS: I'll just leave you with my personal favourite JS articles/ docs 💌

You can also follow this really interesting YouTube channel for cool JS related stuff and more .

How To Embed Microsoft Power BI Charts Into Your React Application

Akshay Ram Vignesh — Sun, 12 Aug 2018 23:46:37 +0000

Embedding Microsoft Power BI charts into your React Application can be breeze with the right tools.

Note: This article assumes you have a fairly decent idea about Microsoft Power BI and few related terminologies.

TL;DR

Install powerbi-report-component using your favourite package manager.

npm i powerbi-report-component --save-dev

or,

yarn add powerbi-report-component --dev

Basic usage,

import Report from "powerbi-report-component";

<Report
  embedType="report"
  tokenType="Embed"
  accessToken=""
  embedUrl=""
  embedId=""
  permissions="All"
  style={myStyleObject}
/>

Now, for the those who stayed :)

Embedding a Power BI report into your React Application can be a pain for a beginner. Even though the Microsoft's documentation on the topic is pretty neat.

I'm just gonna tell you what's need from a React developer's perspective and not go into the details of implementation or architecture.

There are two approaches that you can take to embed your Power BI Report:

User Owns Data
App Owns Data

The main difference is:

User Owns Data sample is for Embedding for your organisation, the embedded reports readers can be Power BI Pro or free users in your organisation. Users have to log-in with their PBI account. Power BI Premium license is required. (i.e, Users who are part of your AD)

App Owns Data sample is for Embedding for your customers, the embedded report readers can be your own customers(say you're an ISV application provider). So no log-in. Power BI Embedded license is required.(i.e, Users outside your AD)

Source: https://community.powerbi.com/t5/Developer/App-vs-User-Owns-Data/td-p/300729

You have to choose who will be using your application that's gonna contain your embedded report i.e, Internal users(AD User) vs. External users(Non AD).

Now that you've decided on which approach you're gonna choose.

Hopefully, You have your report ready and are able to view it in https://powerbi.microsoft.com.

Now, navigate to your report under your workspaces your URL should look something like this:

https://app.powerbi.com/groups/{workspace-id}/reports/{report-id}

for dashboards you might have something like this:

https://app.powerbi.com/groups/{workspace-id}/dashboards/{dashboard-id}

To Embed your report you'll need the following:

Report ID: from the URL
Workspace ID: also, from the URL
Token: AAD or Embed Token (For authetication))

Note: AAD token is used while taking the User Owns Data Approach and Embed token is used when taking App Owns Data Approach.

Embed Url: (Will consist of Report ID and Workspace ID)

https://app.powerbi.com/reportEmbed?reportId=report-id&groupId=workspace-id

There are mainly two ways you can proceed with embedding the report into your react application.

Using an iframe
Using Power BI JS API provided by Microsoft

Using an iframe is pretty straightforward but, this doesn't provide the flexibility that a React component would provide, like callbacks or event triggers.

You can use the generated URL to embed using iframe like this,

<iframe
  width="800"
  height="600"
  src="http://myserver/reports/powerbi/Sales?rs:embed=true"
  allowfullscreen="true"
>
</iframe>

But, naturally as JS developers we tend to go with the more flexible JS API.

You can take a look at Microsoft's demo page

They have a very clear explanation and demo in Vanilla JS which uses their Javascript API.

You might be wondering, the demo is in Vanilla JS so if I have to make it a React Component and use it in my app.hmm, that might take a while 🤔

powerbi-report-component to the rescue! ✨

Check out the package.

Usage,

import Report from "powerbi-report-component";

<Report
  embedType="report" // or "dashboard"
  tokenType="Embed" // or "Aad"
  accessToken="" // accessToken goes here
  embedUrl="" // embedUrl goes here
  embedId="" // Report or Dashboard ID goes here
  permissions="All" // or "View"
  style={myStyleObject}
/>

Currently supported features:

Custom styling by passing style to your embedded report component.
The component also lets you pass callbacks to trigger on events like:

Page Change

onPageChange={(data) =>
  console.log(`Page name :{data.newPage.displayName}`)
}

Load

onLoad={(report) => {
      console.log('Report Loaded!');
      this.report = report;
// Read docs to know how to use the report object that is returned
    }
}

Data Element Clicked

onSelectData={(data) =>
  console.log(`You clicked on chart: {data.visual.title}`)
}

Use 'report' object returned to parent component for:

Fullscreen

setFullscreen = () => this.report.fullscreen()

Print Report

printReport = () => this.report.print()

Change report mode, show/hide visual headers, filters(set, get, remove)

Change Mode

// mode can be "view" or "edit"

changeMode = mode => this.report.switchMode(mode)

Show or Hide Visual Headers

toggleAllVisualHeaders = bool => {
  const newSettings = {
    visualSettings: {
      visualHeaders: [
        {
          settings: {
            visible: bool,
          },
        },
      ],
    },
  }
  this.report
    .updateSettings(newSettings)
    .then(function() {
      console.log(`Visual header was toggled to {bool}`)
    })
    .catch(function(errors) {
      console.log(errors)
    })
}

Set Filters

//example filter object from Microsoft's demo page

    const filter = {
      $schema: "http://powerbi.com/product/schema#basic",
      target: {
        table: "Store",
        column: "Chain"
      },
      operator: "In",
      values: ["Lindseys"]
    };

    // using event handlers

    setFilter = (filter) =>
    this.report.setFilters([filter]).catch(function (errors) {
        console.log(errors);
    });

    // during load of report

    onLoad = (report) => {
      report.setFilters([filter]).catch(function (errors) {
        console.log(errors);
      });
      this.report = report;
    }
  }

Get Filters

getFilter = () =>
  this.report
    .getFilters()
    .then(function(filters) {
      console.log(filters)
    })
    .catch(function(errors) {
      console.log(errors)
    })

Remove Filters

removeFilters = () =>
  this.report.removeFilters().catch(function(errors) {
    console.log(errors)
  })

More features coming soon! ⚡️

Links: Demo site, GitHub

I would love to hear your thoughts and feedback (also any request for new features at https://github.com/akshay5995/powerbi-report-component/issues).