shopify_app 5.0.2 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4074fe532a9c1606f958f24ce1c9ef8f07c58fb7
-  data.tar.gz: 8d9832af0f7999c33225fb4d2e1c83c151bff70e
+  metadata.gz: 2180fbad771bc170d57ca9e9d84264db64adc578
+  data.tar.gz: 028708ad9fc92ce756fbf815468d586e2e0302ed
 SHA512:
-  metadata.gz: 00c8fffe2c5f445fe0ef959b62156d032bae66260df5704fb2fdbc566f853475f5a4f66d848733cb1233ce3c82e8e5898a997da350014bbb08716544e1ffb50e
-  data.tar.gz: a0178aeb4ac85acfd59d44d763a67de03ace96a0e426000b772db29f8f4c1e12ff3de68aac7fade16c715d335bddbdae298d7d8e76e91701ca1a8e7350d86268
+  metadata.gz: d07a8720342f16795447fd929d4fb9d5933ba7cbbe27b085f8c00663548ef3ff5bd5ef826ec5062e30e00d476ac2bea7818e1eefa61b4e06f0831027f4ce309a
+  data.tar.gz: 5c17a5290b05876ecd0bc321dc9477612d7f1d8c87689ff506d6e5ac21f0df4b2c936b1e9d28945d7d2fea0c25eacbf93fc129555fe7f47cc63400e4f80db87c

data/.gitignore

@@ -4,4 +4,7 @@ Gemfile.lock
 pkg/*
 .DS_Store
 .yardoc
-doc/
+doc/
+*.log
+*.sqlite3
+test/tmp/*

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+
+rvm:
+  - 2.0.0
+
+gemfile:
+  - Gemfile
+
+script: "bundle exec rake test"

data/CHANGELOG

@@ -1,5 +1,16 @@
+6.0.0
+-----
+* Re-written as a proper rails engine
+* New modular generators
+* generates embedded apps by default
+* can bootstrap your app with a standard shop table and model
+* code now lives as concerns in the engine which are included in your controllers
+  feel free to override anything you need in your app
+
+Historical
+----------
 * re-styled with Twitter Bootstrap css framework and updated docs [warren]
 * Require shopify_api gem via proper railtie setup [willem]
 * Don't require shopify.yml when using environment variables [cody]
 * Renamed instances of current_shop to shop_session to maintain logic
-* Replace old LoginController with a RESTful SessionsController
+* Replace old LoginController with a RESTful SessionsController

data/README.md

@@ -1,18 +1,30 @@
-# Shopify App
+Shopify App      [![Build Status](https://travis-ci.org/Shopify/shopify_app.png)](https://travis-ci.org/Shopify/shopify_app)
+===========
 
-[![Build Status](https://travis-ci.org/Shopify/shopify_app.png)](https://travis-ci.org/Shopify/shopify_app)
+Shopify Application Rails engine and generator
 
-Shopify application generator for Rails 3.1 and Rails 4.0
 
-## Description
+Description
+-----------
+This gem includes some common code and generators for writing Rails applications using the Shopify API.
 
-This gem makes it easy to get a Rails 3.1 or Rails 4.0 app up and running with the Shopify API.
+*Note: It's recommended to use this on a new Rails project, so that the generator won't overwrite/delete some of your files.*
 
-The generator creates a basic SessionsController for authenticating with your shop and a HomeController which displays basic information about your products, orders and articles.
 
-*Note: It's recommended to use this on a new Rails project, so that the generator won't overwrite/delete some of your files.*
+Becoming a Shopify App Developer
+--------------------------------
+If you don't have a Shopify Partner account yet head over to http://shopify.com/partners to create one, you'll need it before you can start developing apps.
+
+Once you have a Partner account create a new application to get an Api key and other Api credentials. To create a development application set the Application Callback URL to
+
+	http://localhost:3000/login
+
+This way you'll be able to run the app on your local machine.
+
 
-## Installation
+Installation
+------------
+To get started add shopify_app to your Gemfile and bundle install
 
 ``` sh
 # Create a new rails app
@@ -24,59 +36,72 @@ $ echo "gem 'shopify_app'" >> Gemfile
 $ bundle install
 ```
 
-## Usage
+Now we are ready to run any of the shopify_app generators. The following section explains the generators and what they can do.
 
-``` sh
-$ rails generate shopify_app your_app_api_key your_app_secret
+
+Generators
+----------
+
+### Install Generator
+
+```sh
+$ rails generate shopify_app:install
+
+# or optionally with arguments:
+
+$ rails generate shopify_app:install -api_key=<your_api_key> -secret=<your_app_secret>
 ```
 
-If you don't have an API key yet, create a Shopify Partner account at http://shopify.com/partners and create an app. You can also create test shops once you're logged in as a partner.
+Other options include:
+* `scope` - the Oauth access scope required for your app, eg 'read_products, write_orders'. For more information read the [docs](http://docs.shopify.com/api/tutorials/oauth)
+* `embedded` - the default is to generate an [embedded app](http://docs.shopify.com/embedded-app-sdk), if you want a legacy non-embedded app then set this to false, `-embedded false`
 
-When you create your app in the Shopify Partner Account, set the Application Callback URL to
+You can update any of these settings later on easily, the arguments are simply for convenience.
 
-	http://localhost:3000/login
+The generator creates a basic SessionsController for authenticating with your shop and a HomeController which displays basic information about your products using the ShopifyAPI. The generated controllers include concerns provided by this gem - in this way code sharing is possible and if some of these core methods are updated everyone can benefit. It is completely safe to override any of the methods provided by this gem in your application.
 
-You can also create a private application that only works for your shop by visiting https://YOUR-SHOP.myshopify.com/admin/apps/private.
+After running the `install` generator you can start your app with `bundle exec rails server` and install your app by visiting localhost.
 
-### Example
 
-``` sh
-$ rails generate shopify_app edffbb1bb793e2750686e6f4647a384a fed5bb18hde3e2750686e6f4647a781a
+### Shop Model Generator
+
+```sh
+$ rails generate shopify_app:shop_model
 ```
 
-This will create a LoginController and a HomeController with their own views.
+The install generator doesn't create any database models for you and if you are starting a new app its quite likely that you will want one (most our internally developed apps do!). This generator creates a simple shop model and a migration. It also create a model called `SessionStorage` which interacts with `ShopifyApp::SessionRepository`. Check out the later section to learn more about `ShopifyApp::SessionRepository`
 
-## Configuring Shopify App
+*Note that you will need to run rake db:migrate after this generator*
 
-It's possible to set your API key and secret key from different sources:
+### Controllers, Routes and Views
 
-* `SHOPIFY_APP_API_KEY` and `SHOPIFY_APP_SECRET` environment variables
-* Configuration in a Rails `<environment>.rb` config file
+The last group of generators are for your convenience when you want to start overriding code included as part of the Rails engine. For example by default the engine provides a simple SessionController, if you run the `rails generate shopify_app:controllers` generator then this code gets copied out into your app so you can start adding to it. Routes and views follow the exact same pattern.
 
-``` ruby
-config.shopify.api_key = 'your api key'
-config.shopify.secret = 'your secret'
-```
 
-* Configuration loaded from `<environment>` key in `shopify_app.yml`
+### Default Generator
+
+If you just run `rails generate shopify_app` then all the generators will be run for you. This is how we do it internally!
+
 
-``` yaml
-development:
-  api_key: your api key
-  secret: your secret
-```
 
-* Configuration loaded from common key in `shopify_app.yml`
+Managing Api Keys
+-----------------
 
-``` yaml
-common:
-  api_key: your api key
-  secret: your secret
+The `install` generator places your Api credentials directly into the shopify_app initializer which is convient and fine for development but once your app goes into production **your api credentials should not be in source control**. When we develop apps we keep our keys in environment variables so a production shopify_app initializer would look like this:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.api_key = ENV['SHOPIFY_CLIENT_API_KEY']
+  config.secret = ENV['SHOPIFY_CLIENT_API_SECRET']
+  config.scope = 'read_customers, read_orders, write_products'
+  config.embedded_app = true
+end
 ```
 
-## Set up your ShopifySessionRepository.store
+ShopifyApp::SessionRepository
+-----------------------------
 
-`ShopifySessionRepository` allows you as a developer to define how your sessions are retrieved and
+`ShopifyApp::SessionRepository` allows you as a developer to define how your sessions are retrieved and
 stored for a shop. This can simply be your `Shop` model that stores the API Token and shop name. If
 you are using ActiveRecord, then all you need to implement is `self.store(shopify_session)` and
 `self.retrieve(id)` in order to store the record on disk or retrieve it for use at a later point.
@@ -88,98 +113,38 @@ Your ActiveRecord model would look something like this:
 ```ruby
 class Shop < ActiveRecord::Base
   def self.store(session)
-    shop = Shop.new(domain: session.url, token: session.token)
+    shop = self.new(domain: session.url, token: session.token)
     shop.save!
     shop.id
   end
 
   def self.retrieve(id)
-    if shop = Shop.where(id: id).first
+    if shop = self.where(id: id).first
       ShopifyAPI::Session.new(shop.domain, shop.token)
     end
   end
 end
 ```
 
-By default you will have an in memory store but it really won't work on multi-server environments since
+By default you will have an in memory store but it **won't work** on multi-server environments since
 they won't be sharing the static data that would be required in case your user gets directed to a
 different server by your load balancer.
 
 The in memory store also does not behave well on Heroku because the session data would be destroyed
 when a dyno is killed due to inactivity.
 
-Changing the `ShopifySessionRepository.storage` can simply be done by editing
+Changing the `ShopifyApp::SessionRepository.storage` can simply be done by editing
 `config/initializers/shopify_session_repository.rb` to use the correct model.
 
 ```ruby
-ShopifySessionRepository.storage = 'Shop'
-```
-
-## Set your required API permissions
-
-Before making API requests, your application must state which API permissions it requires from the shop it's installed in. These requested permissions will be listed on the screen the merchant sees when approving your app to be installed in their shop.
-
-Start by reviewing the documentation on API permission scopes: http://docs.shopify.com/api/tutorials/oauth
-
-When you know which ones your app will need, add a scope line to the `config/initializers/omniauth.rb` file.
-
-### Example
-
-Make this change to request write access to products and read access to orders:
-
-``` ruby
-Rails.application.config.middleware.use OmniAuth::Builder do
-    provider :shopify, 
-       ShopifyApp.configuration.api_key, 
-       ShopifyApp.configuration.secret,
-       :scope => "write_products,read_orders",
-       :setup => lambda {|env| 
-                   params = Rack::Utils.parse_query(env['QUERY_STRING'])
-                   site_url = "https://#{params['shop']}"
-                   env['omniauth.strategy'].options[:client_options][:site] = site_url
-                 }
-end
-```
-
-*Note that you can change your API permission scopes on the fly, but the merchant will have to approve each change and your computed API password will change.*
-
-## After running the generator
-
-First, start your application:
-
-``` sh
-$ rails server
-```
-
-Now visit http://localhost:3000 and install your application in a Shopify store. Even if Rails tells you to visit your app at http://0.0.0.0:3000, go to http://localhost:3000.
-
-After your application has been given whatever API permissions you requested by the shop, you're ready to start experimenting with the Shopify API.
-
-## Rails 3.0 (as in before 3.1) Support
-
-Rails 3.0 (as in before the big changes in 3.1) is supported on a branch of our github repo: https://github.com/Shopify/shopify_app/tree/rails_3.0_support
-
-## Common problems
-
-If you are getting the following error:
-
-```
-Faraday::Error::ConnectionFailed error when accessing app.
-```
-    
-It probably means that the CA certificate on your computer is out of date. A simple solution on the Mac is to install XCode.
-
-If you are getting the following error:
-
-```
-ActiveResource::ForbiddenAccess in HomeController#index
-Failed.  Response code = 403.  Response message = Forbidden.
+ShopifyApp::SessionRepository.storage = 'Shop'
 ```
 
-It means that you have not set appropriate permissions in your `config/initializers/omniauth.rb` file for what you are trying to do in your HomeController#index action. Example: you set your permissions to 'write_content' because that's what your app will do, but your HomeController#index still has that default code generated by shopify_app which attempts to read products and orders, neither being covered by the 'write_content' scope.
+If you run the `shop_model` generator it will create the required code to use the generated Shop model as the SessionRepository and update the initializer.
 
-## Questions or problems?
 
+Questions or problems?
+----------------------
 http://api.shopify.com <= Read up on the possible API calls!
 
 http://ecommerce.shopify.com/c/shopify-apis-and-technology <= Ask questions!

data/Rakefile

@@ -2,7 +2,6 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.libs << 'lib/shopify_app'
   t.libs << 'test'
   t.test_files = FileList['test/**/*_test.rb']
   t.verbose = true

data/app/controllers/sessions_controller.rb

@@ -0,0 +1,3 @@
+class SessionsController < ApplicationController
+  include ShopifyApp::SessionsController
+end

data/app/views/sessions/new.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Install Page</title>
+</head>
+<body>
+
+  <h2>Install the application</h2>
+
+  <form method="GET" action="login">
+    <label>Type shop name:</label>
+    <input type="text" name="shop" placeholder="blabla.myshopify.com"/>
+    <button type='submit'>Install</buttom>
+  </form>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,10 @@
+if ShopifyApp.configuration.routes_enabled?
+  ShopifyApp::Engine.routes.draw do
+    controller :sessions do
+      get 'login' => :new, :as => :login
+      post 'login' => :create, :as => :authenticate
+      get 'auth/shopify/callback' => :callback
+      get 'logout' => :destroy, :as => :logout
+    end
+  end
+end

data/lib/generators/shopify_app/controllers/controllers_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class ControllersGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../../..", __FILE__)
+
+      def create_controllers
+        controllers.each do |controller|
+          copy_file controller
+        end
+      end
+
+      private
+
+      def controllers
+        files_within_root('.', 'app/controllers/*.*')
+      end
+
+      def files_within_root(prefix, glob)
+        root = "#{self.class.source_root}/#{prefix}"
+
+        Dir["#{root}/#{glob}"].sort.map do |full_path|
+          full_path.sub(root, '.').gsub('/./', '/')
+        end
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/install/install_generator.rb

@@ -0,0 +1,83 @@
+require 'rails/generators/base'
+require 'rails/generators/active_record'
+
+module ShopifyApp
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../templates', __FILE__)
+      attr_reader :opts
+
+      def initialize(args, *options)
+        @opts = Hash[options.first.join(' ').scan(/--?([^=\s]+)(?:=(\S+))?/)]
+        super(args, *options)
+      end
+
+      def create_shopify_app_initializer
+        template 'shopify_app.rb', 'config/initializers/shopify_app.rb'
+      end
+
+      def create_and_inject_into_omniauth_initializer
+        unless File.exist? "config/initializers/omniauth.rb"
+          copy_file 'omniauth.rb', 'config/initializers/omniauth.rb'
+        end
+
+        inject_into_file(
+          'config/initializers/omniauth.rb',
+          File.read(File.expand_path(find_in_source_paths('shopify_provider.rb'))),
+          after: "Rails.application.config.middleware.use OmniAuth::Builder do\n"
+        )
+      end
+
+      def create_shopify_session_repository_initializer
+        copy_file 'shopify_session_repository.rb', 'config/initializers/shopify_session_repository.rb'
+      end
+
+      def inject_embedded_app_options_to_application
+        if embedded_app?
+          application "config.action_dispatch.default_headers.delete('X-Frame-Options')"
+          application "config.action_dispatch.default_headers['P3P'] = 'CP=\"Not used\"'"
+        end
+      end
+
+      def inject_into_application_controller
+        inject_into_class(
+          "app/controllers/application_controller.rb",
+          'ApplicationController',
+          "  include ShopifyApp::Controller\n"
+        )
+      end
+
+      def create_embedded_app_layout
+        if embedded_app?
+          copy_file 'embedded_app.html.erb', 'app/views/layouts/embedded_app.html.erb'
+        end
+      end
+
+      def create_home_controller
+        template 'home_controller.rb', 'app/controllers/home_controller.rb'
+      end
+
+      def create_home_index_view
+        copy_file 'index.html.erb', 'app/views/home/index.html.erb'
+        if embedded_app?
+          prepend_to_file(
+            'app/views/home/index.html.erb',
+            File.read(File.expand_path(find_in_source_paths('shopify_app_ready_script.html')))
+          )
+        end
+      end
+
+      def add_home_index_route
+        route "root :to => 'home#index'"
+      end
+
+      private
+
+      def embedded_app?
+        opts[:embedded] != 'false'
+      end
+
+    end
+  end
+end