## 1. Project Overview & Quickstart (shoutem/ui) ## File: README.md # Shoutem UI Shoutem UI is a set of styleable components that enables you to build beautiful React Native applications for iOS and Android. All of our components are built to be both composable and [customizable](http://github.com/shoutem/theme). Each component has a predefined style that is compatible with the rest of the Shoutem UI, which makes it possible to build complex components that look great without the need to manually define complex styles. ## Install These instructions are valid for React Native 0.60.0 and higher. If you're running a lower version, please use v1.X.X. ``` $ npm install --save @shoutem/ui ``` We have a `postinstall` script which will add `@shoutem/ui`'s native dependencies to your root `package.json` in order to support autolinking and pod installation. Optional: Link the font files to your iOS and Android projects using `react-native-asset`: ``` $ npx react-native-asset node_modules/@shoutem/ui/fonts ``` Not doing this will result in dismissable red screen errors about unknown font names, as well as the default system fonts being used on iOS and Android when a Shoutem UI font is meant to be used, so we suggest running this step. ## Docs All the documentation is available on the [Developer portal](http://shoutem.github.io/docs/ui-toolkit/introduction). ## Community Join [our community](https://www.facebook.com/groups/shoutem.community/) on Facebook. Also, feel free to ask a question on Stack Overflow using ["shoutem" tag](http://stackoverflow.com/tags/shoutem). ## UI Toolkit Shoutem UI is a part of the [Shoutem UI Toolkit](https://shoutem.github.io/docs/ui-toolkit/introduction) that enables you to build professional looking React Native apps with ease. It consists of three libraries: - [@shoutem/ui](https://github.com/shoutem/ui): beautiful and customizable UI components - [@shoutem/theme](https://github.com/shoutem/theme): “CSS-way” of styling entire app - [@shoutem/animation](https://github.com/shoutem/animation): declarative way of applying ready-made animations ## License [The BSD License](https://opensource.org/licenses/BSD-3-Clause) Copyright (c) 2016-present, [Shoutem](http://shoutem.github.io) --- ## File: components/ToastMessage/README.md # Shoutem UI Toasts :bread: New component used for multiple types of alerts, or simple action prompts. The component is based on the [react-native-toast-message ](https://github.com/calintamas/react-native-toast-message)package, with our wrapper implementation defining custom styled toast types > You are still free to use the react-native-toast-message show/hide methods directly, through our default export, if you so desire. ## Usage Most of the time, you will want to use one of the four standard methods of showing a toast using this package. - Toast.showInfo - Toast.showAction - Toast.showError - Toast.showSuccess - Toast.show() and Toast.hide() methods are identical to the ones in the parent library. So if you want to use your own components for alerts, you can do it just like you would normally. Each of these accepts same set or props / params, but implements different styling and color schemes, according to it's semantic significance. Below are a couple of examples of commonly used methods. ```jsx import { Toast } from '@shoutem/ui'; ... Toast.showInfo({ title: 'Hello world!', message: `This is a message!`, iconSource: { uri: 'https://townsquare.media/site/341/files/2012/05/Mr.-Trololo.jpg', }, }); ... ``` ```jsx import { Toast } from '@shoutem/ui'; ... Toast.showAction({ title: 'Stop', message: `Hammer time`, iconSource: require('../assets/actionIcon.png'), cancelButtonText: 'absolutely not', confirmButtonText: `Hammer zeit!`, onCancel: Toast.hide, onConfirm: () => { console.log('A man of culture....'); Toast.hide(); } }); ... ``` ```jsx import { Toast } from '@shoutem/ui'; ... Toast.showError({ title: 'Error', message: `We've failed to charge your credit card. Please check your CC data`, iconName: 'error', confirmButtonText: `Take me to payment details`, onConfirm: () => { navigateTo('PaymentDetailsScreen'); Toast.hide(); } autoHide: false, }); ... ``` ### Props Currently supported props mainly include "native" props from the parent library, with both, a few exclusions and a some additions. Also, you can pass any kind of custom prop you want, and it will be passed in to your custom toast component | **Name** | **Type** | **Default** | **Description** | |---------------------------------------------|-------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------| | title | String | Required | Title of the toast message | | message | String | Required | Description of the toast message | | iconName | String | Info | Name of the existing icon in the UI toolkit that will be used as a leading image | | iconSource | ImageSourceType | undefined | Standard image source ( uri object, direct require, ... ). If this prop is passed in, it will take presedence over iconName prop | | durationIndicator | Bool | true | Displays the duration indicator line below the toast, in the duration of the `visibilityTime` prop | | onConfirm | Function | undefined | Callback called when pressing the confirm button | | onCancel | Function | undefined | Callback called when pressing the cancel button | | confirmButtonText | String | undefined | | | cancelButtonText | String | undefined | | | `-- props supported from parent library --` | | | | | position | `top` or `bottom` | top | | | visibilityTime | Number | 4000 | How long is the toast displayed | | autoHide | Bool | true | Hide automatically after visibilityTime has expired | | topOffset | Number | 40 | | | bottomOffset | Number | 40 | | | keyboardOffset | Number | 10 | | | onShow | Function | | | | onHide | Function | | | | onPress | Function | | | ## BaseToast This component also exports our base component that contains all of the internal logic that understand how to compose and handle toast message. If you'd like to create a new Toast component, feel free to use the BaseToast, and inject `customToastStyle` prop that will be merged with the default styles, and / or any other prop manipualtion you require. --- ## File: html/README.md # Html ## Html component Transforms the raw HTML to the React Native components tree. Accepts these props: - `body` A raw HTML. - `renderElement(element, style, defaultRenderElement)` A function to override default `renderElement`. If this function returns `undefined` the default `renderElement` will be used to render element. - `style` A Html style. Register an element with the static `Html.registerElement(elementTag, Component)` method. Registered elements will be handled with the default `renderElement`. ### Components Components in the `html/components` folder are base implementation of common HTML elements that contain specific logic. Wrap those components with your own element implementation, and reduce the element attributes to the component props. For example, there are different ways to implement the HTML image gallery but most the most cases you can use the same React Native implementation. ## Element components Elements are React Native components used to render a parsed element. The Element will by default receives these props: - `element` An object describing element, contains `tag`, `attributes`, `childElements`, `parent` props. - `style` The [Shoutem theme](https://github.com/shoutem/theme) style passed in the Html instance style. - `renderElement` A function used to render an element with registered element component. ## 2. Official Technical Reference & Guides (shoutem/shoutem.github.io) # Shoutem Shoutem is a platform for building beautiful React Native mobile apps. The easiest way to understand what Shoutem is to think of it as the WordPress for mobile apps. Apps are divided into smaller modules, called `extensions`. On WordPress you build a website out of plugins; on Shoutem you build a mobile app out of extensions. This architecture helps us achieve big development efficiency. ## Community Join [our community](https://www.facebook.com/groups/shoutem.community/) on Facebook. Also, feel free to ask a question on Stack Overflow using ["shoutem" tag](http://stackoverflow.com/tags/shoutem). ## Feature requests We would like to know what you want to do with Shoutem extensions. Feel free to raise issues with `feature requests` and upvote the ones labeled as a `feature request`, so we can know what you need the most. We're going to put label `in progress` for the features that we decide to implement. ## React Native Shoutem app is a React Native app. We designed extensions’ architecture with the goal not to add overhead over pure React Native. If you know React Native, you will know how to write Shoutem extensions. If you're just starting with React Native, check out our [React Native School](https://school.shoutem.com/). ## Marketplace Shoutem prepared and open sourced a lot of extensions that you can use in your apps. Don’t reinvent the wheel: reuse extensions which are suitable for you, customize them or create new ones. You can find the full list of extensions [here](https://github.com/shoutem/extensions). ## Customization All our extensions are open sourced, so you can modify anything you want by simply forking them. You can also write your own ones from scratch. ## Tools and docs We've prepared tools to speed up your extension development like [Shoutem CLI](https://shoutem.github.io/docs/extensions/reference/cli), [Shoutem UI toolkit](https://shoutem.github.io/ui/) for faster component development and documented all the concepts on this [developer's portal](http://shoutem.github.io/). If you find some bug or have a suggestion on how to improve anything, feel free to contribute or raise an issue! ## Start creating your apps! If you’re not already using Shoutem, you can create your account [here](https://new.shoutem.com), and start developing beautiful mobile apps.