``` ▓ ▄▓▓▓▌ ▓▓▓▓▓▌ ▓▓▓▓▓▓▓▌ ▄▓▓▓▓▓▓▓▓▓▄▄▄▄ ▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄ ▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄ ▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▓▓▓▓▓ ▓▓▓█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄▀▓▓▓▓▄ ▓▀▀ ▐▓▓▓▓██▀▀▀█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░█▓▓▓▄ ▐▓ ▀▀ █▓▓▓▓▓▓▓▓▓▓▓▓▓▌ ▓▓▓▓▄ ▓ ▀▓▓▓▓▓▓▓▓▓▓▓▓▄▓▓▓▓▓▓▓▄▄▄▄ ▓▌ ▀▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▐▌ █▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▀ ▐▌ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▀ ▐▌ ▄▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▀ ▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▓ ▓█▀▀ ▀█▓█▀ ▐▌ ▐ ▓ ▓ ▐▓ ▀▄ ▄▀ ▀▒▄▄ ▄▄▄▀▀▄▄▄▀▀ ▀▀▒▄▄▄▄▄▄▒▀▀▀ █████╗ ███████╗████████╗██████╗ ██████╗ ██╔══██╗██╔════╝╚══██╔══╝██╔══██╗██╔═══██╗ ███████║███████╗ ██║ ██████╔╝██║ ██║ ██╔══██║╚════██║ ██║ ██╔══██╗██║ ██║ ██║ ██║███████║ ██║ ██║ ██║╚██████╔╝ ╚═╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ``` # Astro An SDK that makes it easy to leverage native or web UI for building amazing iOS and Android apps. --- [![BuddyBuild - iOS](https://dashboard.buddybuild.com/api/statusImage?appID=5718187eb1a258010071c7b9&branch=develop&build=latest)](https://dashboard.buddybuild.com/apps/5718187eb1a258010071c7b9/build/latest?branch=develop) [![BuddyBuild - Android](https://dashboard.buddybuild.com/api/statusImage?appID=5718143bc75b6401001e921a&branch=develop&build=latest)](https://dashboard.buddybuild.com/apps/5718143bc75b6401001e921a/build/latest?branch=develop) --- ## Related projects - [Astro Scaffold](://github.com/mobify/astro-scaffold) - [Astro Generator](://github.com/mobify/generator-astro) - [Astro Tutorial](://github.com/mobify/astro-tutorial) ## Additional Documents - [Sandbox Project](sandbox/README.md) - [Continuous Integration](circle/README.md) ## Table of Contents - [Documentation](#documentation) - [Installing](#installing) - [How to create and ship a change](#how-to-create-and-ship-a-change) - [Testing](#testing) - [Publishing](#publishing) - [Structure](#structure) ## Documentation You can find the Astro documentation at [astro.mobify.com](http://astro.mobify.com) or you can view it locally (see [Making Changes](#making-changes)). We currently publish the documentation for all versions of Astro since v0.5. The documentation is organized by Astro release in folders. `docs/public/` contains one folder for each release of Astro plus a special `dev` folder for changes related to an unreleased version of Astro. See the [release checklist](RELEASE.md) for more information. You can create "perma-links" to the latest version of Astro documentation by using http://astro.mobify.com/latest/. ### Installation We use Harp to build our docs. Harp is an npm dependency and so is installed when you run `npm install` in the root of the Astro repo. ### Making Changes Most of our documentation is written in markdown. Changes to any tutorials or reference guides should be changed in `/docs`. To preview your changes, run the following: ```bash $ npm run docs:serve ``` Then browse to `http://localhost:9000`. ### Publishing The Astro documentation is hosted on S3 at [http://astro.mobify.com.s3-website-us-east-1.amazonaws.com](http://astro.mobify.com.s3-website-us-east-1.amazonaws.com/), which is the origin for [http://astro.mobify.com](http://astro.mobify.com). All Astro documentation is published every time a pull request is merged into the `develop` branch. Should you need to deploy the docs manually, docs, you will need permission to deploy to the astro.mobify.com S3 bucket (ask in #it on Slack). If you have the correct permissions, ensure `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables are set, and run the following to deploy the updated docs site: ```bash $ npm run docs:upload ``` ## Installing Clone the repo: `git clone git@github.com:mobify/astro.git` ### Prerequisites * We recommend using [nvm](https://github.com/creationix/nvm#installation) to manage node and npm versions. * node ^8.10.0 LTS * npm ^5.0.0 * Grunt CLI - Install via `npm install -g grunt-cli` * [Java Development Kit (JDK) 8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) * [Xcode](https://developer.apple.com/download/more/) * [Android Studio](http://developer.android.com/sdk/index.html) ### NPM dependencies 1. Install npm dependencies (push libraries) by running: ```bash npm install ``` ### Android 1. Download and install [Android Studio](https://developer.android.com/sdk/installing/studio.html). 2. Open `Android Studio`. 3. Click `Open an existing Android project`, and select the [`astro/sandbox/android`](astro/sandbox/android) folder. Android Studio will open both the Astro Android source code and the Sandbox Android app source code. 4. Create an [Android Virtual Device](https://developer.android.com/tools/devices/managing-avds.html) if you haven't already. 5. Follow [these instructions](https://developer.android.com/sdk/installing/adding-packages.html) to install SDK packages. 6. Run the Sandbox app! ### iOS 1. Download and install [Xcode](https://developer.apple.com/xcode/download/) 2. Run `open sandbox/ios/Sandbox.xcworkspace` in your Terminal. It will open both the Astro iOS source code and the Sandbox iOS app source code. 3. Run the Sandbox app! ## How to create and ship a change In order to ship a change to Astro, follow our [Contributing](./CONTRIBUTING.md) guidelines. ## Testing ### Running Tests #### JS 1. Install the dependencies needed for testing, run `npm install`. 2. To run the tests on the command line, run `npm test`. 3. To run the tests in the browser, run `open js/tests/index.html`. #### iOS 1. Start the server required for testing by running `npm run fixture-server` 2. In Xcode, select the "Astro" workspace in the workspace dropdown. 3. Go to Product -> Test (⌘U) #### Android 1. Go to Run -> Edit Configurations 2. Click on the "+" on the top left, and select "Android Tests" 3. Label it "Astro Tests", choose the module "astro", and click OK. 4. Select "Show chooser dialog" 5. In the drop down next to the green play button, select "Astro Tests" and click the play button. 6. Watch the tests run! ### Writing Tests #### Android The testing framework we use is [jUnit 3](http://junit.org/). The mocking library we use is [Mockito](http://mockito.googlecode.com/svn/branches/1.7/javadoc/org/mockito/Mockito.html). ### Test Coverage #### Android Run the following command to generate the test coverage report: cd android; ./gradlew createDebugCoverageReport Then, open the report index.html file to have a look at the coverage: open android/build/outputs/reports/coverage/debug/index.html #### iOS Currently we are not measuring test coverage in iOS :( #### JS Currently we are not measuring test coverage in JS :( ## Publishing a new version The release process for Astro (and dependent projects) is outlined in [RELEASE.md](RELEASE.md). ## Structure - `android/` - Contains the source code for the Astro Android library - `ios/` - Contains the source code for the Astro iOS library - `js/` - Contains the source code for the Astro JavaScript library - `sandbox/` - Contains the source code for the demonstration sandbox (aka Catalogue). ### JS When you're developing an Astro application, there are a few key pieces of JS to know about: 1. app.js 2. astro-base.js 3. astro-client.js 4. astro-full.js 5. webViewPlugin.js, drawerPlugin.js, and other plugins ### app.js app.js is your main entry point to developing an Astro project. This is where the main business logic of you application lives. The app logic is handled in a persistent WebView that lives throughout the lifecycle of your application (otfen referred to as "the worker"). It's also the place where you import/require modules (controllers, plugins, etc.) that you need for your application. A sample `app.js` lives inside of `sandbox/app/`. You can learn more about how to build and develop the sandbox [here](sandbox/README.md). ### astro-base.js astro-base.js is the module that allows communication between JavaScript and the native bridge. astro-client.js and astro-full.js extend from this module. In general, as a user of the Astro SDK you should never have to require this module directly. ### astro-client.js astro-client.js is the library which provides the ability for web views to communicate with app.js. ### astro-full.js astro-full.js is the library which provides the ability for app.js to communicate with native Astro components. It's the library that SDK plugin developers should import in order to create a plugin. ### Plugins #### iOS TODO #### Android TODO #### JS Most native plugins have a corresponding JavaScript plugin that you will use to instantiate and use different plugins in your app.js file. All plugins can be found inside of `android/src/main/java/com/mobify/astro/plugins`. You can learn more about how to build and develop Astro plugins [here](guides/writing-astro-plugins.md).