Quick Start
You don’t need be a developer to set up Avalanche, you just need to be an adventurous nerd. Just as Rock pays dividends to your efforts, Avalanche does take some effort. That effort is what opens up possibilities. This guide is to get you up and running with a very basic app. Where you go from there is up to your imagination.
While the goal is to get you started with an hour’s worth of work, this doesn’t include the time it takes to download and set up the tools you will need. That being said, we’ll tell you about those tools and how to use them.
There are few tools in your belt you will need to get started. Don’t get scared, they aren’t too bad. You will need a running copy of Rock. Let’s not play around on your production server just yet. Either a test server or a local copy running in Visual Studio will do. You will need to use a Windows computer to build the Rock plugin. Eventually, when you start building for iOS you will need to use macOS, but you can test on Android with just Windows for now.
Visual Studio is required to build the plugin and app, but you can use the free Community Edition. You should also be very familiar with Rock and know how to manually install a plugin. Use Rock 1.7.5 or newer, you may need to update your references depending on which version you use. The Rockit SDK will not work correctly.
Avalanche has two parts: the Rock plugin and the app itself. The app calls home to Rock and the plugin tells the app what to display. Both parts will have to be built and deployed separately.
We are going to set up the plugin first. Open a copy of Rock in Visual Studio and make sure it succeeds when if you right click on the Rock solution and then click “Build Solution”.
Download a fresh copy of Avalanche from: https://github.com/secc/Avalanche Next we will add the plugin to our solution so we can build it.
The folder Plugin contains the project of Avalanche.
Build the Avalanche project.
If you are running Rock on a test server, you will need to add the newly created Avalanche.dll to RockWeb/bin, the files from the Plugins folder in to RockWeb/Plugins/YourChurchName folder and the Theme folder to RockWeb/Themes folder.
If you are running Rock from Visual Studio you will only need to add the files to the Plugins and Themes. The DLL will automatically be installed on build.
Launch Rock and go to Admin > CMS Configuration > Sites. Then click the plus to add a new site. Name the site Avalanche (the name actually doesn’t matter) and set it to the theme “Avalanche”.
Optionally you can add custom page attributes. It is suggested to add an attribute to set the background color.
After clicking save select the “Pages” tab and make note of the page that Rock created for you. You will need this Id.
Next go to Admin > General Settings > Global Attributes. A new attribute should be waiting for you. “Avalanche Home Page” points Rock to know which site manages your app. Enter the page id of your new site’s home page as the value.
Okay we’re getting closer. That was a lot of configuration, but we’re getting there. Let’s now go to our new site. http://{{RockWebAddress}}/page/{{Page Id}}. Before we get to adding any blocks let’s make sure the page’s settings are correct. Use the Layout “Simple”
Add a Markdown Detail block to the Main zone. Since Avalanche uses native controls it doesn’t understand HTML like a web browser. Instead it uses Markdown to format blocks of text. Configuring this block gives us a great opportunity to say nice things about the framework.
After saving your changes we can check our work by changing our browser to http://{{RockWebAddress}}/api/avalanche/home and you should see something like this:
Congratulations you have completed the most tedious part. You are in the home stretch. All we need now is to set up the app and point it to our copy of Rock. The app portion of Avalanche is written with Xamarin Forms. Xamarin Forms is a Microsoft owned technology which allows us to use C# to write apps that work in iOS and Android.
Before starting trying to build Avalanche for iOS or Android, it is recommended that you build and deploy a test app. This way you can make sure you are able to build something simple before attempting a more complicated one. There is a great quick start guide here: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/get-started/hello-xamarin-forms/quickstart
Note: Microsoft has a Xamarin live player app which is pretty cool. Unfortunately it doesn’t support some of the things we are doing in Avalanche. Bummer.
Once you are somewhat confident in your ability to build a basic app, load the solution file that is in the App folder of the Avalanche source. There is one only one line to configure to get started. The file Avalanche> Utilities> Constants.cs contains the string serverUrl. Change the value of this string to that of your rock webserver. Example: http://rocksolidchurchdemo.com
IMPORTANT If you are running Rock off of Visual Studio, using http://localhost:6229 will not work. The Android emulator/iOS simulator is usually considered an external connection and will probably be blocked by your firewall and IIS Express. There is a great solution for this problem: ngrok.io. It allows you to tunnel into your computer on a specific port. It’s free and super helpful. Ngrok will provide you with a URL that you can use in place of localhost.
Now we are ready for the moment of truth. Hit the play button and in a minute or two you should be greeted with this:
Congratulations! You can now check out the other features of Avalanche. Let your imagination run wild.
* Ok let’s face it. That probably took you more than an hour. We are looking for people to help us improve Avalanche –including making it easier to get up and running.