Syndesis is a single page application built with React.
- Syndesis
We use Lerna to streamline the development process; the most common operations, like building the project or running the development mode can be done directly from the project root.
Code is split in many packages, organized as a monorepo using Yarn's workspaces. The workspace is configured like this:
"syndesis",
"packages/*"
"typings/*"
syndesis is the main application. It handles the authentication against Syndesis's OAuth Server, and provides the main
app layout where "sub-apps" can be injected.
It also provides an API for sub-apps - in the form of a React's Context - for interact with it, eg. closing the navigation bar, or redirecting to another sub-app.
It's built with create-react-app.
$ yarn watch:appJust clear the local storage for the localhost:3000 origin. You can do it with Chrome Dev Tools opened on the running app, or you can do it from Chrome's special url chrome://settings/siteData
This package contains a collection of React Components implementing the render props pattern to ease interacting with Syndesis's Backend.
$ yarn watch:packages --scope @syndesis/apiThis package contains the Typescript definitions of the models as read from the backend.
This package contains a collection UI elements that are common across the application.
All the elements are written as React PureComponents or Stateless Functional Components. The idea is to decouple the presentation from the model that holds the data that needs to be presented to promote code reuse and easing the testing efforts.
$ yarn watch:packages --scope @syndesis/uiThis package provides a Storybook to develop and document the components in isolation.
Storybook can be launched like this:
# From the package folder
$ yarn storybookA browser tab should eventually be opened pointing on http://localhost:90001.
This package contains commonly used components of function that don't fit any of the above packages.
$ yarn watch:packages --scope @syndesis/utilsTBD.
Extra typings for pure Javascript dependencies that should eventually be pushed on DefinitelyTyped.
Yarn is the package manager required to work on the project.
To install all the dependencies:
yarn install
To build syndesis and all the packages:
yarn buildTo start the development server for syndesis and watch for changes in any of the packages:
$ yarn watchIMPORTANT: you must have successfully built all the packages before running the watch command to successfully
run this command.
IMPORTANT: this will change the syndesis-ui POD to point to your development server. To
restore the POD to the original state, you will have to manually run yarn minishift:restore
To start the development server only for syndesis:
$ yarn watch:appThe development server for the app will not be available at http://localhost:3000
IMPORTANT: you must have successfully built all the packages before running the watch command to successfully
run this command.
IMPORTANT: this will change the syndesis-ui POD to point to your development server. To
restore the POD to the original state, you will have to manually run yarn minishift:restore
To start the development server only for the packages:
$ yarn watch:packagesTo start the development server for a specific package you can pass the package name to the previous command:
$ yarn watch:packages --scope @syndesis/package-nameTo run the test suite:
$ yarn testTo run the test suite for a specific package you can pass the package name to the previous command:
$ yarn test --scope @syndesis/package-nameWe are using the react-i18next library for internationalization (i18n). You can find documentation about this library at react.i18next.com.
The syndesis package is the only package where we are using this i18n library. To make this i18n library available in the syndesis package, the syndesis/package.json file was edited as follows:
- added dependency to i18next - the core library that handles all the translation functionality.
- added a dependency to i18next-browser-languagedetector - detects the browser's locale and sets it as the default locale for translations.
- added dependency to react-i18next - built on top of the core library and provides functionality specific to React.
- added
@types/i18nexttodevDependencies. - added
@types/i18next-browser-languagedetectortodevDependencies.
If packages other than the syndesis package require translations, the already translated text should be passed into those packages using the custom properties of the component. Do not modify those packages' package.json to add dependencies to the i18n framework! We are doing it this way to facilitate testing and to remove the impact of changing the i18n library if ever we need to do that. Here is an example of how you would do that:
export interface ILinkProps {
linkRoute: string;
i18LinkText: string;
}
export class MyLink extends React.Component<ILinkProps> {
public render() {
return (
<Link
to={this.props.linkRoute}
className={'btn btn-primary'}
>
{this.props.i18LinkText}
</Link>
);
}
}
In order to get internalization working in our app, a specific i18next instance needs to be configured. We do this in the syndesis/src/i18n folder. Here is how that folder is organized:
index.ts- configures our i18next instance. You can find more information abouti18nextsettings at i18next.com and thereact-i18nadditional settings at react.i18next.com.locales/- a folder that sets up the i18n namespaces and contains the translations shared within thesyndesis/srccodebase.locales/index.ts- contains references to all the app translations files.locales/shared-translations.en.json- contains the shared English translations and placeholders for the namespaces provided from withinsyndesis/src.locales/shared-translations.it.json- contains the shared Italian translations and placeholders for the namespaces provided from withinsyndesis/src.
Now that we have our i18n instance configured, we can start i18n-ing our code. This is done by adding a locales/ folder at the root of the code that you want to have its own, non-shared translations. This folder defines your translations and your namespace. Now, all that is left to do is to add specific calls to the i18n framework from you code.
Important: Adding new namespaces does require changes to be made to the i18n instance described above.
Note: All namespaces are actually always available by qualfiying the translation key with the namespace.
When a method returns a React element or fragment (like render() does), and translations are needed, the NamespacesConsumer class is used. Using the NamespacesConsumer class in the method gives that method access to the i18n framework. It does this by exposing the t, or translation function. An array of namespaces, which are setup by your i18n instance, is used by the NamespacesConsumer to perform the translations. The first namespace in the array does not require its keys to be qualified. However, any subsequent namespaces do require their keys to be qualified. An example of internationalizing a method like this can be found here.
When translations are needed but you are not in a method that returns a React element, or you are in code that is not a method at all, the NamespacesConsumer cannot be used. Instead, the i18n instance itself is used. For instance you can translate some text in a const that is constructing an instance of an interface. See this example.
The following sections give you examples on how to i18n things.
To internationalize a render() method, do the following:
- Add this import statement
import { NamespacesConsumer } from 'react-i18next';
- Wrap what normally would be returned with a
NamespacesConsumertag. You need to set the array of namespaces you will be using. The first namespace is the default and does not need to be used when referencing a translation key. Translation keys not found in the default namespace need to be qualified. See this for examples of using namespaces in translations.
public render() {
return (
<NamespacesConsumer ns={['your-default-namespace', 'additional-namespaces']}>
{t => (
// include the code that you would normally return
)}
</NamespacesConsumer>
);
}
- Add translations into your translation files.
- Use the
tfunction in therender()method wherever a translation is needed. Here you will find examples of how to use thetfunction.
To internationalize text in a const, do the following:
- Add this import statement:
import i18n from 'relative-path-to-syndesis/src/i18n';
- Add translations into your translation files.
- Use the
i18n.tfunction to perform the translations. Here you will find examples of how to use thetfunction.
const sortByName = {
id: 'name',
isNumeric: false,
title: i18n.t('shared:Name'),
} as ISortType;
Some examples taken from i18next.com documentation.
- translation file
{
"errorMsg": "An error occurred.",
}- usage
{ t('erroMsg') }
- outputs: "An error occurred."
- usage
{ t('Connections') } -> uses default namespace translation files
{ t('shared:Name') } -> uses 'shared' namespace translation files
{ t('integrations:topIntegrations') } -> uses 'integrations' namespace translation files
- translation file
{
"lastNumberOfDays": "Last {{numberOfDays}} Days",
"favorite": "{{this}} is my favorite {{thing}}",
}- usage
{ t('lastNumberOfDays', { numberOfDays: 30 }) }
{ t('favorite', { this: 'Apple', thing: 'fruit' }) }
- outputs: "Last 30 Days" and "Apple is my favorite fruit"
- translation file
{
"nesting1": "1 $t(nesting2)",
"nesting2": "2 $t(nesting3)",
"nesting3": "3",
}- usage
{ t('nesting1') }
- outputs: "1 2 3"
- translation file
{
"key1": "hello world",
"key2": "say: {{val}}"
}```
- usage
```react
{ t('key2', { val: '$t(key1)' }) }- outputs: "say: hello world"
- translation file
{
"numberOfItems": "{{count}} item",
"numberOfItems_plural": "{{count}} items",
}- Extend the build system for the packages to extract any CSS file referenced in the project and make it available in the dist folder.
- Implement syndesis-context
- ...so many things!