Merge branch 'master' into chore/update_lcobucci/jwt

Author: dacort

README.md

@@ -1,21 +1,87 @@
-# embedding-reference-apps
-Reference applications for common web frameworks showing how to embed Metabase charts
+# Embedding Metabase dashboards: reference web apps
 
-# Running the apps
-1. Run the metabase server with `java -jar metabase.jar` from the `/metabase` directory
-2. Run the relevant reference application
+This repo contains example applications for common web frameworks to demonstrate how [Metabase](https://www.metabase.com/) dashboards can be embedded in your application.
 
-For the Django application
-`./manage.py runserver`
+This README will walk you through getting Metabase up and running, as well as a simple web app, to show you a live example of an embedded dashboard.
 
-For the Node application
-`node index.js`
+Here's a simple Metabase dashboard in action:
 
-For the rails application
-`rails server -p 3001`
-(Note that we're binding to a nonstandard port as Metabase also runs on 3000)
+![Simple Metabase dashboard embedded in Node application](/static/img/metabase_node_embed.gif)
 
-# Helpful info
-Admin login is
-user: plucky@admin.com
-password: Metabase123
+## Premium embedding
+
+Embedding Metabase charts will always be free, but we include a "Powered by Metabase" graphic when using the open source version.
+
+If you'd like to remove the "Powered by Metabase" attribution, check out our [Enterprise Edition](https://www.metabase.com/enterprise/) which lets you do so so as well as white-label the application.
+
+## Prerequisites
+
+- Java version 8.x or 11.x. [Install OpenJDK](https://openjdk.java.net/install/).
+
+## Set up Metabase
+
+We'll first need to set up a running instance of Metabase to serve the embedded dashboards.
+
+1. If you already have an instance of Metabase running on your machine, shut it down. 
+
+2. Open up a terminal and clone this repo to your machine.
+
+3. `cd` into embedding-reference-apps.
+
+3. Run the the prepare script.
+
+```shell
+./prepare.sh
+```
+
+The prepare.sh script downloads the latest version of Metabase to this repository's [metabase](/metabase) directory, changes into that directory, and runs the jar:`java -jar metabase.jar`.
+
+Metabase will log its progress in the terminal as the jar runs. Once you see the line, "Metabase Inititalization COMPLETE", open your browser to [localhost:3000](http://localhost:3000) to see that Metabase is up and running. 
+
+## Running the apps
+
+To see an embedded Metabase dashboard in action, [set up Metabase](#set-up-metabase), and follow the instructions in the README for the relevant app. If you're not sure which one to try, check out the [Node app](/node/README.md).
+
+- [Node](/node/README.md)
+
+- [Django](/django/embedded-analytics/README.md)
+
+- [Rails](/rails/embedded-analytics/README.md)
+
+- [Laravel](/laravel/embedded-analytics/README.md)
+
+## Embedding charts or dashboards
+
+There are two ways to embed charts or dashboards in web applications:
+
+### Public embeds
+
+The Public embedding method is to simply use the public URLs inside of an iframe, or really anywhere you can insert HTML. The embedded dashboard has a secure URL, so a user can only look at the contents of the dashboard being shared. An end user never has information they can use to modify the URL and gain access to any other resources on your Metabase instance.
+
+### Signed embeds
+
+With signed embedding, all embedded charts and dashboards have to be signed using a secret key. This allows you to build dynamic dashboards with a parameter that can be be locked down on the client side.  You should sign embedded charts and dashboards on your server, which allows you to embed dashboards accessible to specific organizations, accounts, or users.
+
+The web applications go into more detail about embedding, and provide examples. Start up the [Node app](/node/README.md) and explore the app.
+
+## Documentation on embeds
+
+You can also learn more about embedding dashboards by reading [Metabase's documentation](https://www.metabase.com/docs/latest/).
+
+- [Quick search: embed](https://www.metabase.com/search.html?query=embed).
+
+Article links:
+
+- [Embedding Metabase components in other applications](https://www.metabase.com/docs/latest/administration-guide/13-embedding.html)
+- [Embedding all of Metabase in your web app](https://www.metabase.com/docs/latest/enterprise-guide/full-app-embedding.html)
+- [Sharing and embedding dashboards or questions](https://www.metabase.com/docs/latest/administration-guide/12-public-links.html)
+
+## Helpful info
+Credentials for Metabase should auto-populate, but here they are for reference:
+
+- user: plucky@admin.com
+- password: Metabase123
+
+## Run into trouble?
+
+Check out the [Metabase discussion forum](https://discourse.metabase.com/) and search for your issue. If you don't find any answers, please [create an issue](https://github.com/metabase/embedding-reference-apps/issues/new/choose) for this repository.

django/embedded_analytics/README.md

@@ -0,0 +1,33 @@
+# Django app
+
+This Django application demonstrates a simple, barebones Metabase dashboard embedded in a web application.
+
+## Prerequisites
+
+- **Metabase**. You should have already completed the setup detailed in the [README](../../README.md) for this repository, which shows you how to get an instance of Metabase up and running in the [metabase](../../metabase) directory of this repository.
+
+- **Python**. You'll need to have [Python](https://www.python.org/) installed on your machine.
+
+## Set up the Django application
+
+1. In a new terminal session, `cd` into [/embedded-analytics](/embedded-analytics).
+
+2. Install the application's dependencies:
+
+```shell
+pip install -r requirements.txt
+```
+
+3. Once the dependencies are installed, start the application by running: 
+
+```shell
+./manage.py runserver
+```
+
+4. Open your browser to [localhost:8000](http://localhost:8000).
+
+Explore the app to learn more about embedding Metabase charts and dashboards in applications. You can also check out the links to more documentation in the parent repository's main [README](../../README.md).
+
+## Example embedding code
+
+You can find example code for embedding Metabase in [user_stats/views.py](user_stats/views.py).

django/embedded_analytics/requirements.txt

@@ -1,3 +1,3 @@
-Django==1.10.5
+Django==1.11.28
 django-allauth==0.30.0
 PyJWT==1.4.2

django/embedded_analytics/user_stats/templates/user_stats/signed_chart.html

@@ -23,7 +23,7 @@ <h1>Embedding charts with signed parameters</h1>
     }
 }
 
-token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256")
+token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256").decode('utf8')
 
 iframeUrl = METABASE_SITE_URL + "/embed/question/" + token + "#bordered=true"
 </pre>

django/embedded_analytics/user_stats/templates/user_stats/signed_dashboard.html

@@ -27,7 +27,7 @@ <h1>Embedding dashboards with signed parameters</h1>
         }
     }
 
-    token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256")
+    token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256").decode('utf8')
 
     iframeUrl = METABASE_SITE_URL + "/embed/dashboard/" + token + "#bordered=true"
 </pre>

django/embedded_analytics/user_stats/templates/user_stats/signed_public_dashboard.html

@@ -17,7 +17,7 @@ <h1>Signed dashboards without parameters</h1>
     }
 }
 
-token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256")
+token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256").decode('utf8')
 
 iframeUrl = METABASE_SITE_URL + "/embed/dashboard/" + token + "#bordered=true"
 </pre>

django/embedded_analytics/user_stats/views.py

@@ -7,7 +7,8 @@
 METABASE_SITE_URL = "localhost:3000"
 METABASE_SECRET_KEY = "a1c0952f3ff361f1e7dd8433a0a50689a004317a198ecb0a67ba90c73c27a958"
 
-
+def get_token(payload):
+    return jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256").decode('utf8')
 
 def index(request):
     return render(request,
@@ -21,9 +22,7 @@ def signed_public_dashboard(request):
         }
     }
 
-    token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256")
-
-    iframeUrl = METABASE_SITE_URL + "/embed/dashboard/" + token + "#bordered=true"
+    iframeUrl = METABASE_SITE_URL + "/embed/dashboard/" + get_token(payload) + "#bordered=true"
 
     return render(request,
                   'user_stats/signed_public_dashboard.html',
@@ -37,9 +36,7 @@ def signed_chart(request, user_id):
         }
     }
 
-    token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256")
-
-    iframeUrl = METABASE_SITE_URL + "/embed/question/" + token + "#bordered=true"
+    iframeUrl = METABASE_SITE_URL + "/embed/question/" + get_token(payload) + "#bordered=true"
 
     if request.user.is_superuser:
         # always show admins user stats
@@ -62,9 +59,7 @@ def signed_dashboard(request, user_id):
         }
     }
 
-    token = jwt.encode(payload, METABASE_SECRET_KEY, algorithm="HS256")
-
-    iframeUrl = METABASE_SITE_URL + "/embed/dashboard/" + token + "#bordered=true"
+    iframeUrl = METABASE_SITE_URL + "/embed/dashboard/" + get_token(payload) + "#bordered=true"
 
     if request.user.is_superuser:
         # always show admins user stats

laravel/embedded_analytics/README.md

@@ -1,7 +1,51 @@
-# README
+# Laravel app
 
-1. Install dependencies: `composer install`. The package `lcobucci/jwt` has already been added
-2. See the Example Code in `routes/web.php`
-3. See the Example View in `resources/views/welcome.blade.php`
+This Laravel application demonstrates a simple, barebones Metabase dashboard embedded in a web application.
 
-You can test it by running `php artisan serve` from the root of the Laravel application and opening http://localhost:8000.
+## Prerequisites
+
+- **Metabase**. You should have already completed the setup detailed in the [README](../../README.md) for this repository, which shows you how to get an instance of Metabase up and running in the [metabase](./metabase) directory of this repository.
+
+- **Composer**. You'll need [Composer](https://getcomposer.org/) to manage PHP packages.
+
+- **Laravel**. You'll need to have [Laravel](https://laravel.com/) installed on your machine.
+
+## Set up the Laravel application
+
+1. Start a new terminal session, change into this directory, and install the application dependencies using the command `composer install`. (The package `lcobucci/jwt` has already been added.)
+
+Note: if you just installed Composer using the default filename for Composer to this directory, you may need to run:
+
+```shell
+php composer.phar install
+```
+
+2. Generate an application key. First, create a .env file by copying the example env file.
+
+```shell
+cp .env.example .env
+```
+
+Then generate the key.
+
+```shell
+php artisan key:generate
+```
+
+This command will write the key to your new .env file.
+
+3. To start the application, run:
+
+```shell
+php artisan serve
+```
+
+4. Open your browser to [localhost:8000](http://localhost:8000) to see the app in action. 
+
+Explore the app to learn more about embedding Metabase charts and dashboards in applications. You can also check out the links to more documentation in the parent repository's main [README](../../README.md).
+
+## Example embedding code
+
+- **Code**. You can find example code for embedding Metabase in [routes/web.php](routes/web.php).
+
+- **View**. You can find an example view in [resources/views/welcome.blade.php](resources/views/welcome.blade.php).