Skip to main content

The Browser object

The Browser object can be used to control browser. Here are some use-cases:

  • Showing modals, alerts, popups.
  • Retrieving browser info, current URL.
  • Accessing local storage, cookies.
  • Navigation, routing.

Showing alert inside browser#

First, you'll need to modify initializeDraymanFramework function inside public/index.html. Add browser commands function and alert function as shown below:

public/index.html
...
<script>  initializeDraymanFramework({    browserCommands: () => ({      alert: async ({ text }) => {        alert(text);      },    }),  });</script>
...

Functions defined inside browserCommands will be executed by your browser. In our example we have added alert function which shows an alert inside browser when Drayman component asks to do so. And here is how Drayman component can do this:

src/components/home.tsx
export const component: DraymanComponent = async ({ Browser }) => {  return () => {    return (      <button        onclick={async () => {          await Browser.alert({ text: "Hello, world!" });        }}      >        Alert!      </button>    );  };};

We have exposed Browser object and told Drayman to execute alert function when user clicks a button.

Retrieving data from browser#

Functions defined inside browserCommands also can return some useful data:

public/index.html
...
<script>  initializeDraymanFramework({    browserCommands: () => ({      getCurrentUrl: async () => {        return window.location.href;      },    }),  });</script>
...

Now this function can be used inside Drayman component:

src/components/home.tsx
export const component: DraymanComponent = async ({ Browser }) => {  const currentUrl = await Browser.getCurrentUrl();
  return () => {    return <h3>You are now here: {currentUrl}</h3>;  };};

In result user will see something like this:

http://localhost:3033

You are now here: http://localhost:3033/

Executing callbacks#

You can also execute callbacks inside browserCommands. This can be useful if you are creating some interactive views (modals) and you need to wait for some user interaction.

Let's modify our previous alert example:

public/index.html
...
<script>  initializeDraymanFramework({    browserCommands: (emit) => ({      alert: async ({ text, onClose }) => {        alert(text);        emit(onClose);      },    }),  });</script>
...

Pay attention on how emit parameter of browserCommands was introduced. It is used to tell Drayman to execute passed callbacks. In our case we are executing onClose callback after alert is executed. Now modify home.tsx component:

src/components/home.tsx
export const component: DraymanComponent = async ({ Browser, forceUpdate }) => {  let closed = false;
  return () => {    return (      <>        <button          onclick={async () => {            await Browser.alert({              text: "Hello, world!",              onClose: async () => {                closed = true;                await forceUpdate();              },            });          }}        >          Alert!        </button>        {closed && <h3>You have closed an alert!</h3>}      </>    );  };};

Now when user clicks a button, an alert will be shown. After closing an alert, a text "You have closed an alert!" will be shown on page:

http://localhost:3033

You have closed an alert!

And remember, instead of showing a text, you are free to execute any server-side code (for example, saving some data to database).

Referencing elements#

Sometimes UI interactivity like focusing elements, opening modals and drag-and-dropping is easier to implement on front-end side. In Drayman this can be done in three steps:

  1. Mark elements that need to be referenced with ref attribute and any unique name.
  2. Define some browser command which will do something with referenced element. Element references will be passed as the second parameter of the browser command.
  3. Execute browser command function by passing an array of required element references.

Let's, for example, see how this can be done if we want to focus some element:

src/components/home.tsx
export const component: DraymanComponent = async ({ Browser }) => {  return () => {    return (      <>        <input          type="text"          // set up reference          ref="my-input"        />        <button          id="focus-btn"          onclick={async () => {            // execute Browser function with referenced element            await Browser.focus(null, ["my-input"]);          }}        >          Focus input        </button>      </>    );  };};
public/index.html
...
<script>  initializeDraymanFramework({    browserCommands: () => ({      // your elements will appear as the second parameter of Browser function      focus: async (data, [element]) => {        element.focus();      },    }),  });</script>
...