README.md

Cozy Bar Library

What's Cozy?

Cozy is a platform that brings all your web services in the same private space. With it, your webapps and your devices can share data easily, providing you with a new experience. You can install Cozy on your own hardware where no one's tracking you.

What's CozyBar ?

The CozyBar is a banner on the top of your application, responsible of cross-apps navigation, user facilities, intents, etc. This is a React component.

Getting started

The library requires your markup to contain an element with role=application. The DOM of the banner will be added before this element.

Installation

yarn add cozy-bar

How to use

You need to include the BarComponent into your react tree :

import { BarComponent } from 'cozy-bar'

<BarComponent />

The BarComponent will get default params into data-cozy attribute of the element role=application. You can still customize this parameter through props:

• appName: The name of the app.
• appNamePrefix: The prefix of the app. Originally used for apps maintained by Cozy Cloud teams.
• appSlug: The slug of the app.
• iconPath: The path to the app icon. Defaults to a blank GIF

There is also other parameter to adapt the bar to your app:

• isInvertedTheme: To make the icon of Cozy(icon-cozy-home.svg) compatible with an inverted theme
• isPublic: To show the public version of the Bar
• onLogout: A callback to react to the logout of the user
• disableInternalStore: Allow to disable the internal store of the Bar

Customizing the content of the bar

From within your app, you can decide to take over certain areas of the cozy-bar. This might especially be useful on mobile where the area it occupies is prime real estate — we generally don't recommend to use this option on larger screen resolutions.

The bar is divided in 4 areas that you can control individually : left, center, search and right:

To do this, you need to wrap your BarComponent into an BarProvider after your can use component to modify component inside :

import { BarLeft, BarCenter, BarRight, BarSearch } from 'cozy-bar'

// then, somewhere in a render function below the BarProvider
<BarLeft>
  <div>Hello!</div>
</BarLeft>

Access your application store in custom components

By default, the Bar has its own redux store to fetch data and manage ui state. If you are using a Redux store into your application and you need to access it into your Bar customization you need to integrate the cozy-bar store into your own.

import { barReducers } from 'cozy-bar'

const reducers = {
  ...baseReducers,
  ...barReducers,
  cozy: client.reducer()
}

const appReducer = combineReducers(reducers)

You also need to disable the internal store onto the BarComponent with the property disableInternalStore

<BarComponent disableInternalStore />

Change theme bar

It's possible to update theme on the cozy-bar with setTheme function using the bar context

import { useBarContext } from 'cozy-bar'

const { setTheme } = useBarContext()

setTheme('default')
setTheme('primary')

Migrate from previous version

If you're migrating from v7, check out the migration guide for v7. If you're migrating from an other version, check out the migration guide. If you need to find the code for v7, it is on the v7-stable branch.

Debugging

It is possible to activate the logger from the bar by activating the flag 'bar.debug'. Then you have to reload the page.

flag(bar.debug, true)

Development mode

• Then, follow these steps:

$ yarn link // in cozy-bar

$ rlink cozy-bar // in the cozy-app

$ yarn start // in cozy-bar

$ yarn start // in the cozy-app

Contribute

If you want to work on cozy-bar itself and submit code modifications, feel free to open pull-requests! See the contributing guide for more information about this repository structure, testing, linting and how to properly open pull-requests.

Community

Localization

Localization and translations are handled by [Transifex][tx], which is used by all Cozy's apps.

As a translator, you can login to [Transifex][tx-signin] (using your Github account) and claim an access to the [app repository][tx-app]. Locales are pulled when app is build before publishing.

As a developer, you just have to modify json in /src/locales. New locales will be automatically added to Transifex. If you need to pull or push manually locales, you can use Transifex CLI. If you were using a transifex-client, you must move to Transifex CLI to be compatible with the v3 API.

Get in touch

You can reach the Cozy Community by:

• Chatting with us on IRC #cozycloud on Libera.Chat
• Posting on our Forum
• Posting issues on the Github repos
• Say Hi! on Twitter

Licence

cozy-bar is developed by Cozy Cloud and distributed under the MIT.