Commits

Steven Kryskalla  committed bce198b

docs: moving "app code" section to the top for quickstart

and some fixes/edits

  • Participants
  • Parent commits 3a77f62

Comments (0)

Files changed (1)

File docs/quickstart.rst

 From scratch
 ------------
 
+To integrate ``itemshop`` into your app, you need to add the ``ItemBP``
+blueprint to your application, and create some templates with a bit of
+javascript to handle the form:
+
+* application code
+
+  * instantiate an :class:`ItemBP` object with: a unique name, a
+    ``stripe.Charge`` (one-time) or ``stripe.Customer`` (recurring)
+    payment, and some default arguments for the payment (e.g. the
+    price)
+  * mount the item blueprint on your app using
+    ``app.register_blueprint(item._blueprint, **options)``
+
 * HTML and JS
 
   * create a template called "``itemshop/default_index.html``", which contains a
     form with credit card fields and one hidden field called "``stripe_token``"
   * wire up the ``stripe.js`` API with this form, so that when the user submits
     the form, their credit card is processed with ``stripe.js``, and your
-    ``stripe_token`` hidden field is populated with the key returned by stripe
+    ``stripe_token`` hidden field is populated with the token returned by stripe
   * create a template called "``itemshop/default_process.html``", which will be shown
     to the user after their purchase is complete
 
-* application code
-
-  * instantiate an :class:`ItemBP` object with: a unique name, a ``stripe.Charge`` (one-time) or ``stripe.Customer`` (recurring) payment, and some default arguments for the payment (e.g. the price)
-  * mount the item blueprint on your app using ``app.register_blueprint(item._blueprint, **options)``
-
 The sections below will go into more detail about each of these steps. You can
 also re-use the `demo code`_ found in the source repo.
 
 
 Then, to integrate one of the demos into your app:
 
-1. copy over the static CSS, JS, images (from ``demos/static``) into your app's ``static`` directory
+1. copy over the static CSS, JS, images from ``demos/static`` into your app's ``static`` directory
 2. copy over the templates in the "itemshop" directory to your app's ``template`` directory
 3. copy over the code in ``app.py`` that instantiates the :class:`ItemBP`, then mount the blueprint on your app
 
 From scratch, step-by-step
 ==========================
 
+App code: skeleton
+------------------
+
+``itemshop`` was designed to be integrated into an existing app, so let's grab
+the sample app from `flask's home page`__.
+
+__ http://flask.pocoo.org/
+
+.. code-block:: python
+
+    from flask import Flask
+
+    app = Flask(__name__)
+
+    @app.route("/")
+    def hello():
+        return "Welcome to my item shop."
+
+    if __name__ == "__main__":
+        app.run(use_debugger=True, use_reloader=True)
+
+App code: ItemBP
+----------------
+
+.. sidebar:: Public/private keys
+
+    Note: this is my testing private key. It corresponds to the public key we
+    will set in the Javascript. You can get your own keys `here`__.
+
+__ https://manage.stripe.com/#account/apikeys
+
+Now, at the top of ``app.py``, we need to import the ``stripe`` library, the ``itemshop`` library, and set the stripe API key:
+
+.. code-block:: python
+
+    import itemshop
+    import stripe
+    stripe.api_key = 'UwK0UE4tdPGNJckqfiu5UbzUJxHClRjW'
+
+Now let's instantiate the :class:`ItemBP` object by passing in three arguments:
+
+.. code-block:: python
+
+    item = itemshop.ItemBP('my_item', stripe.Charge, dict(
+        amount=1500,
+        currency='usd',
+    ))
+
+1. First, a unique ID ``'my_item'``
+2. Next, we pass in the stripe payment object to use:
+
+  * ``stripe.Charge`` is used for one-time payments, all it needs is an ``amount``
+    to charge
+  * ``stripe.Customer`` is used for recurring payments, it needs a ``plan``
+    argument, which is created through the stripe web interface (e.g.
+    ``plan='silver'`` might correspond to a monthly charge of $10.00)
+
+3. Finally, we pass in a dict of default values that will be used to
+   instantiate the stripe payment. In this case, we pass in the ``amount`` (``1500`` in
+   cents = $15.00) and the currency 'usd'. Any other values, like the
+   ``stripe_token`` will come from the form data. You can also use this dict to pass 
+   in an ``api_key``, which will override the global ``stripe.api_key``.
+
+After that, all you need to do is mount the blueprint on your app using ``register_blueprint``:
+
+.. code-block:: python
+
+    app.register_blueprint(item._blueprint)
+
+By default, this will mount the blueprint onto the root of your app ("/").
+Let's mount the blueprint somewhere else, so we don't override the existing view
+at "/". To do this, use ``url_prefix``:
+
+.. code-block:: python
+
+    app.register_blueprint(item._blueprint, url_prefix="/shop")
+
+Now, run your application::
+
+    $ python app.py
+     * Running on http://127.0.0.1:5000/
+     * Restarting with reloader...
+
+Go to "/shop" in your browser and you should see an error page, because the template is
+missing. That means it's time for the next step!
+
 HTML
 ----
 
-First, we need to create the credit card form page. Below is an example of
-what ``itemshop/default_index.html`` could look like.
+Now we need to create the template that contains the credit card form.
 
 In the ``<head>``, include the following Javascript:
 
 
 .. _default_index.html: https://bitbucket.org/lost_theory/flask-stripe-blueprint/src/tip/demos/001-simplest/templates/itemshop/default_index.html
 
-We are using the stripe API library, jQuery, a ``demo.js`` file we'll define
+We are using the stripe.js API library, jQuery, a ``demo.js`` file we'll define
 in a bit, and setting our Stripe account's public key. The key in that example
 (``pk_uo5...``) is my test key, please try to use your own if you have one.
 
 
 .. code-block:: html
 
-    <div id="fail" style="display: none;">
+    <div id="fail" style="display: none; color: red;">
         Sorry, we could not process your credit card: <span id="fail_reason"></span>.
         <br/><br/>
         Please correct the form and try again.
 Two important things to note:
 
 1. The very first field is the hidden field for "``stripe_token``".
-   We will use this element to store the key obtained from the ``stripe.js`` API call.
+   We will use this element to store the token obtained from the ``stripe.js`` API call.
 2. None of the credit card fields (card number, CVC, expiration month, or expiration
    year) have a ``name`` attribute. This means that even if the form gets submitted
    without javascript, the credit card fields will not be sent to your backend. This
             }, amount, stripeResponseHandler);
 
             // prevent the form from submitting with the default action
-           return false;
+            return false;
         });
     });
 
 we first disable the submit button (to prevent repeated form submissions going
 through), and re-hide the failure message ``div`` (in case it was already
 showing). We then make the ``stripe.js`` API call, ``Stripe.createToken``.
-Note that the values are pulled out of the form fields using CSS classes
-(``.card-number``, ``.card-cvc``, etc.), not with ``name`` attributes. We set
+Note that the values are pulled out of the form fields using CSS element IDs
+(``#card-number``, ``#card-cvc``, etc.), not with ``name`` attributes. We set
 the amount to ``0`` when we create the token, because we will pass the real value
 from the server-side code. The ``stripeResponseHandler`` function is a
 callback, which we will define next. Finally, we ``return false`` to prevent
   which will POST the form data to the flask app.
 
 * If anything other than 200 status was returned, then there was an error, so
-  we pull out the error   out of the repsonse at ``response.error.message``,
-  stuff it into the ``#fail_reason`` span, show   the ``#fail`` ``div``, then
+  we pull the error out of the repsonse at ``response.error.message``,
+  stuff it into the ``#fail_reason`` span, show the ``#fail`` ``div``, then
   re-enable the submit button so the user can correct the form and try again.
 
-Next, we add the :class:`ItemBP` blueprint to our app.
-
-App code: ItemBP
-----------------
-
-.. sidebar:: Public/private keys
-
-    Note: this is my testing private key. It corresponds to the public key we set in the Javascript. You can get your own keys `here`__.
-
-__ https://manage.stripe.com/#account/apikeys
-
-At the top of your app, you need to set the stripe API key:
-
-.. code-block:: python
-
-    stripe.api_key = 'UwK0UE4tdPGNJckqfiu5UbzUJxHClRjW'
-
-To instantiate the :class:`ItemBP` object we pass in three arguments:
-
-.. code-block:: python
-
-    item = ItemBP('cool_item', stripe.Charge, dict(
-        amount=1500,
-        currency='usd',
-    ))
-
-1. First, a unique ID ``'cool_item'``
-2. Next, we pass in the stripe payment object to use:
-
-  * ``stripe.Charge`` is used for one-time payments, all it needs is an ``amount``
-    to charge
-  * ``stripe.Customer`` is used for recurring payments, it needs a ``plan``
-    argument, which is created through the stripe web interface (e.g.
-    ``plan='silver'`` might correspond to a monthly charge of $10.00)
-
-3. Finally, we pass in a dict of default values that will be used to
-   instantiate the stripe payment. In this case, we pass in the amount (1500 in
-   cents, $15.00) and the currency 'usd'. Any other values, like the
-   ``stripe_token`` will come from the form data. You can also use this dict to pass 
-   in an ``api_key``, which will override the global ``stripe.api_key``, so you could
-   have a different ``api_key`` for an item.
-
-After that, all you need to do is mount the blueprint on your app using ``register_blueprint``:
-
-.. code-block:: python
-
-    app.register_blueprint(item._blueprint)
-
-By default, this will mount the blueprint onto the root of your app ("/"). To mount the blueprint somewhere else, use the ``url_prefix`` argument:
-
-.. code-block:: python
-
-    app.register_blueprint(item._blueprint, url_prefix="/shop")
-
-Now you're read to start making some (test) money!
+Now you're ready to start making some (test) money!
 
 Test it out
 -----------
 
-Run your application::
-
-    $ python app.py
-     * Running on http://127.0.0.1:5000/
-     * Restarting with reloader...
-
-Go to ``http://127.0.0.1:5000/`` and use the following test values:
+Go back to ``http://127.0.0.1:5000/shop`` and use the following test values on the form:
 
 * Credit card: ``4242-4242-4242-4242``
 * CVC: any 4 digit number
 * Expiration date: any date in the future
 
-You should get the "Thank you" page. Go to your stripe dashboard, switch to
+You should get the "Thank you" page. Go to your `stripe dashboard`_, switch to
 test mode, and you should see the charge recorded.
 
+.. _stripe dashboard: https://manage.stripe.com/#dashboard
+
 Also try with some bad values (blank fields, invalid credit card, past
 expiration date), to see what errors are shown on the form.
 
-Congrats! You've earned your first (test) dollars!
+Congrats! You've earned your first (test) dollar!
 
 Where to go from here? `Clone the repository`_ and check out `the demos`_ for
-more advanced usage.
+more advanced usage (multiple items, receipt codes, retrieving payments from
+the stripe API, etc.).
 
 .. _Clone the repository: https://bitbucket.org/lost_theory/flask-stripe-blueprint/src
 .. _the demos: https://bitbucket.org/lost_theory/flask-stripe-blueprint/src/tip/demos/