README.md in shopify-sinatra-app-0.0.5 vs README.md in shopify-sinatra-app-0.0.6

- old
+ new

@@ -28,17 +28,19 @@ This will create a new skeleton shopify-sinatra-app. The generator will create several default files for you rather than having them bundled in the sinatra extension - its worthwhile to read this section to understand what each of these files is for. `config/database.yml` --> The database config for active record. Initially this is setup to use sqlite3 for development and testing which you may want to change to mimic your production database. +`.gitignore` --> tells git which files to ignore, namely `.env` you may find more things you want to add to this file. + `.env` --> a hidden file not tracked by source control for storing credentials etc. to be set as environment variables `config.ru` --> Rackup file - describes how to run a rack based app `Gemfile` --> manages the dependencies of the app -`lib/app.rb` --> This file is the skeleton app file. More details on how to use the methods provided by this extension are given in the following section. +`lib/app.rb` --> This file is the skeleton app file. More details on how to use the methods provided by this extension are given in the following section. There are more comments inside this file explaining the skeleton app. `Procfile` --> Specific for deploying to Heroku, this file tells heroku how to run the app `public/icon.png` --> This icon file is used by the Shopify Embedded App SKD and is shown in the menu bar of your embedded app @@ -53,46 +55,47 @@ ### Setting the app to use your Shopify API credentials You'll need to create a Shopify Partner Account and a new application. You can make an account [here](http://www.shopify.ca/partners) and see this [tutorial](http://docs.shopify.com/api/the-basics/getting-started) for creating a new application. -Note - The shopify-sinatra-app creates an embedded app! You need change the embedded setting to enabled in the [Shopify Partner area](https://app.shopify.com/services/partners/api_clients) for your app. If you don't want your app to be embedded then remove the related code in `layout/application.erb` and delete the `layout/_top_bar.erb` file and the references to it in the other views. +Note - The shopify-sinatra-app creates an embedded app! You need change the embedded setting to `enabled` in the [Shopify Partner area](https://app.shopify.com/services/partners/api_clients) for your app. If you don't want your app to be embedded then remove the related code in `layout/application.erb` and delete the `layout/_top_bar.erb` file and the references to it in the other views. After creating your new application you need to edit the `.env` file and add the following lines: ``` SHOPIFY_API_KEY=<your api key> SHOPIFY_SHARED_SECRET=<your shared secret> SECRET=<generate a random string to encrypt credentials with> ``` +If your app has any other secret credentials you should add them to this file. Shopify::Methods ---------------- -`shopify_session` - The main method of the framework, most of your routes will use this method to acquire a valid shopify session and then perform api calls to Shopfiy. The method activates a Shopify API session for you and accepts a block inside of which you can use the ShopifyAPI. Here is an example endpoint that displays products: +**shopify_session** - The main method of the framework, most of your routes will use this method to acquire a valid shopify session and then perform api calls to Shopfiy. The method activates a Shopify API session for you and accepts a block inside of which you can use the ShopifyAPI. Here is an example endpoint that displays products: ```ruby get '/products.json' do shopify_session do products = ShopifyAPI::Product.all(limit: 5) products.to_json end end ``` -`webhook_session` - This method is for an endpoint that recieves a webhook from Shopify. Webhooks are a great way to keep your app in sync with a shop's data without polling. You can read more about webhooks [here](http://docs.shopify.com/api/tutorials/using-webhooks). This method also takes a block of code and makes the webhook data available as a hash (note only works for json webhooks, don't use xml). Here is an example that listens to a order creation webhook: +**webhook_session** - This method is for an endpoint that recieves a webhook from Shopify. Webhooks are a great way to keep your app in sync with a shop's data without polling. You can read more about webhooks [here](http://docs.shopify.com/api/tutorials/using-webhooks). This method also takes a block of code and makes the `webhook_data` available as a hash (note only works for json webhooks, don't use xml). Here is an example that listens to an order creation webhook: ```ruby post '/order.json' do webhook_session do |webhook_data| # do something with the data end end ``` -`webhook_job` - Its impossible to control the flow of webhooks to your app from Shopify especially if a larger store installs your app or if a shop has a flash sale. To prevent your app from getting overloaded with webhook requests it is usually a good idea to process webhooks in a background queue and return a 200 to Shopify immediately. This method provides this functionality using redis and resque. This method takes the name of a job class whose perform method expects a `shop_name`, `shop_token` and the webhook data as a hash. The session method is useful for prototpying and experimenting but production apps should use `webhook_job`. Here is an example: +**webhook_job** - Its impossible to control the flow of webhooks to your app from Shopify especially if a larger store installs your app or if a shop has a flash sale. To prevent your app from getting overloaded with webhook requests it is usually a good idea to process webhooks in a background queue and return a `200` to Shopify immediately. This method provides this functionality using redis and resque. This method takes the name of a job class whose perform method expects a `shop_name`, `shop_token` and the `webhook_data` as a hash. The session method is useful for prototpying and experimenting but production apps should use `webhook_job`. Here is an example: ```ruby post '/order.json' do webhook_job(OrderWebhookJob) end @@ -104,19 +107,19 @@ # do something with the data end end ``` -`install` - This is a private method provided with the framework that gets called when the app is authorized for the first time. You should fill this method in with anything you need to initialize on install, for example webhooks and services on shopify or any other database models you have created specific to a shop. +**install** - This is a private method provided with the framework that gets called when the app is authorized for the first time. You should fill this method in with anything you need to initialize on install, for example webhooks and services on Shopify or any other database models you have created specific to a shop. -`logout` - This method clears the current session data in the app +**logout** - This method clears the current session -`current_shop` - Returns the name of the current shop (format: example.myshopify.com) +**current_shop** - Returns the name of the current shop (format: example.myshopify.com) -`base_url` - This returns the url of the app +**base_url** - This returns the url of the app -shopify-sinatra-app also includes `rack-flash3` and the flash messages are forwarded to the Shopify Embedded App SDK. Flash messages are useful for signalling to your users that a request was successful without changing the page. The following is an example of how to use a flash message in a route: +shopify-sinatra-app also includes `rack-flash3` and the flash messages are forwarded to the Shopify Embedded App SDK (see the code in `views/layouts/application.erb`). Flash messages are useful for signalling to your users that a request was successful without changing the page. The following is an example of how to use a flash message in a route: ``` post '/flash_message' do flash[:notice] = "Flash Message!" redirect '/' @@ -135,13 +138,13 @@ ``` foreman run bundle exec rackup config.ru ``` -Note - we use `foreman run ...` not foreman start because we only want to start the single process that is our app. This means if you add a debugger in your app it will trigger properly in the command line when the debugger is hit. If you don't have any debuggers feel free to use `foreman start -p 4567`. +Note - we use `foreman run ...` not `foreman start ...` because we only want to start the single process that is our app. This means if you add a debugger in your app it will trigger properly in the command line when the debugger is hit. If you don't have any debuggers feel free to use `foreman start -p 4567`. -To debug your app simply add `require 'byebug'` at the top and then type `byebug` where you would like to drop into an interactive session. You may also want to try out Pry. +To debug your app simply add `require 'byebug'` at the top and then type `byebug` where you would like to drop into an interactive session. You may also want to try out [Pry](http://pryrepl.org/). While running the app locally you'll be able to test the install and other routes because your browser is aware of your local application but if you want to test a route that listens to a webhook this will not work because Shopify cannot talk to your local web application. You could expose your local application to the web but an easier solution is to use a tool called [Ngrok](https://ngrok.com/). Download Ngrok and run it on port 4567 (or whichever port you are using): ``` ./ngrok 4567 @@ -151,10 +154,10 @@ Deploying --------- -This template was created with deploying to Heroku in mind. Heroku is a great cloud based app hosting provider that makes it incredibly easy to get an application into a product environment. +This template was created with deploying to Heroku in mind. Heroku is a cloud based app hosting provider that makes it easy to get an application into a product environment. Before you can get started with Heroku you need to create a git repo for you application: ``` git init