jfinn
/
edan_f0
Watch 1
Star 0
Fork 0
Code Issues 0 Pull Requests 0 Releases 0 Wiki Activity
Browse Source

Document the new US sample site 

- Rework the page on applying taxes in the US
- Update the release notes
- Update the "sandbox" page with details of the new site
master
David Winterbottom 11 years ago
parent
0e287cc3b9
commit
04d3ca0e5f
3 changed files with 98 additions and 59 deletions
Unified View Show Diff Stats
  1. 21
    19
      docs/source/howto/how_to_handle_us_taxes.rst
  2. 65
    40
      docs/source/internals/sandbox.rst
  3. 12
    0
      docs/source/releases/v0.8.rst

+ 21
- 19
docs/source/howto/how_to_handle_us_taxes.rst View File

19 
 Adjust checkout views to apply taxes once they are known
 19 
 Adjust checkout views to apply taxes once they are known
20 
 --------------------------------------------------------
 20 
 --------------------------------------------------------
21
21
22 
-Second, the :class:`~oscar.apps.checkout.views.PaymentDetailsView`
23 
-checkout view should be overridden within your project to calculate taxes on
24 
-the basket within the
25 
-:func:`~oscar.apps.checkout.views.PaymentDetailsView.build_submission` method.
22 
+Second, the :class:`~oscar.apps.checkout.session.CheckoutSessionMixin`
23 
+should be overridden within your project to apply taxes
24 
+to the submission.
26
25
27 
 .. code-block:: python
 26 
 .. code-block:: python
28
27
29 
-    from oscar.apps.checkout import views
28 
+    from oscar.apps.checkout import session
30
29
31 
     from . import tax
 30 
     from . import tax
32
31
33 
-    # Override the core Oscar view class
34 
-    class PaymentDetailsView(views.PaymentDetailsView):
35 
-
36 
-        # Override build_submission to ensure taxes are applied before
37 
-        # attempting to place an order
32 
+    class CheckoutSessionMixin(session.CheckoutSessionMixin):
33 
+
38 
         def build_submission(self, **kwargs):
 34 
         def build_submission(self, **kwargs):
39 
-            submission = super(PaymentDetailsView, self).build_submission(**kwargs)
35 
+            submission = super(CheckoutSessionMixin, self).build_submission(
36 
+                **kwargs)
40
37
41 
-            # Apply taxes (in place)
42 
-            tax.apply_to_submission(submission)
38 
+            if submission['shipping_address']:
39 
+                tax.apply_to(submission)
43
40
44 
-            # Recalculate order total to ensure we have a tax-inclusive total
45 
-            submission['order_total'] = self.get_order_totals(
46 
-                submission['basket'],
47 
-                shipping_method=submission['shipping_method'])
41 
+                # Recalculate order total to ensure we have a tax-inclusive total
42 
+                submission['order_total'] = self.get_order_totals(
43 
+                    submission['basket'],
44 
+                    shipping_method=submission['shipping_method'])
48
45
49 
             return submission
 46 
             return submission
50
47
54
51
55 
     from decimal import Decimal as D
 52 
     from decimal import Decimal as D
56
53
57 
-    def apply_tax_to_submission(submission):
54 
+    def apply_to(submission):
58 
         # Assume 7% sales tax on sales to New Jersey  You could instead use an
 55 
         # Assume 7% sales tax on sales to New Jersey  You could instead use an
59 
         # external service like Avalara to look up the appropriates taxes.
 56 
         # external service like Avalara to look up the appropriates taxes.
60 
         STATE_TAX_RATES = {
 57 
         STATE_TAX_RATES = {
67 
             line_tax = calculate_tax(
 64 
             line_tax = calculate_tax(
68 
                 line.line_price_excl_tax_incl_discounts, rate)
 65 
                 line.line_price_excl_tax_incl_discounts, rate)
69 
             unit_tax = (line_tax / line.quantity).quantize(D('0.01'))
 66 
             unit_tax = (line_tax / line.quantity).quantize(D('0.01'))
70 
-            line.stockinfo.price.tax = unit_tax
67 
+            line.purchase_info = unit_tax
71
68
72 
         # Note, we change the submission in place - we don't need to
 69 
         # Note, we change the submission in place - we don't need to
73 
         # return anything from this function
 70 
         # return anything from this function
78 
         def calculate_tax(price, rate):
 75 
         def calculate_tax(price, rate):
79 
             tax = price * rate
 76 
             tax = price * rate
80 
             return tax.quantize(D('0.01'))
 77 
             return tax.quantize(D('0.01'))
78 
+
79 
+.. tip::
80 
+
81 
+   Oscar's repository contains a sample Oscar site customised for the US.  See
82 
+   :ref:`us_site` for more information.

+ 65
- 40
docs/source/internals/sandbox.rst View File

2 
 Sample Oscar projects
 2 
 Sample Oscar projects
3 
 =====================
 3 
 =====================
4
4
5 
-Oscar ships with two sample projects: a 'sandbox' site, which is a vanilla
6 
-install of Oscar using the default templates and styles, and a fully featured
5 
+Oscar ships with three sample projects: a 'sandbox' site, which is a vanilla
6 
+install of Oscar using the default templates and styles, a sample US site which
7 
+customises Oscar to use US style taxes, and a fully featured
7 
 'demo' site which demonstrates how Oscar can be re-skinned and customised to
 8 
 'demo' site which demonstrates how Oscar can be re-skinned and customised to
8 
 model a domain.
 9 
 model a domain.
9
10
30
31
31 
 The sandbox is, in effect, the blank canvas upon which you can build your site.
 32 
 The sandbox is, in effect, the blank canvas upon which you can build your site.
32
33
33 
-The demo site
34 
--------------
35 
-
36 
-The demo site is *the* reference Oscar project as it illustrates how Oscar can
37 
-be redesigned and customised to build an realistic e-commerce store. The demo
38 
-site is a sailing store selling a range of different product types.
39 
-
40 
-The customisations on top of core Oscar include:
41 
-
42 
-* A new skin
43 
-* A variety of product types including books, clothing and downloads
44 
-* Payment with PayPal Express using django-oscar-paypal_.
45 
-* Payment with bankcards using Datacash using django-oscar-datacash_.
46 
-
47 
-.. _django-oscar-paypal: https://github.com/tangentlabs/django-oscar-paypal
48 
-.. _django-oscar-datacash: https://github.com/tangentlabs/django-oscar-datacash
49 
-
50 
-.. note::
51 
-
52 
-    Both the sandbox and demo site have the Django admin interface wired up.
53 
-    This is done as a convenience for developers to browse the model instances.
54 
-
55 
-    Having said that, the Django admin interface is *unsupported* and will fail
56 
-    or be of little use for some models. At the time of writing, editing
57 
-    products in the admin is clunky and slow, and editing categories is
58 
-    not supported at all.
59 
-
60 
 Browse the external sandbox site
 34 
 Browse the external sandbox site
61 
-================================
35 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
36
63 
 An instance of the sandbox site is build hourly from master branch and made
 37 
 An instance of the sandbox site is build hourly from master branch and made
64 
 available at http://latest.oscarcommerce.com
38 
 available at http://latest.oscarcommerce.com
68 
     It is possible for users to access the dashboard and edit the site content.
 42 
     It is possible for users to access the dashboard and edit the site content.
69 
     Hence, the data can get quite messy.  It is periodically cleaned up.
 43 
     Hence, the data can get quite messy.  It is periodically cleaned up.
70
44
71 
-Browse the external demo site
72 
-=============================
73
45
74 
-An instance of the demo site is built periodically (but not automatically) and
75 
-available at http://demo.oscarcommerce.com. It is typically updated when new
76 
-versions of Oscar are released.
77 
-
78 
-Running the sandbox locally
79 
-===========================
46 
+Run the sandbox locally
47 
+~~~~~~~~~~~~~~~~~~~~~~~
80
48
81 
 It's pretty straightforward to get the sandbox site running locally so you can
 49 
 It's pretty straightforward to get the sandbox site running locally so you can
82 
 play around with Oscar.
 50 
 play around with Oscar.
112 
     email: superuser@example.com
 80 
     email: superuser@example.com
113 
     password: testing
 81 
     password: testing
114
82
115 
-Running the demo locally
116 
-========================
83 
+.. _us_site:
84 
+
85 
+The US site
86 
+-----------
87 
+
88 
+The US site is a relatively simple Oscar that makes a few key customisations in
89 
+order to mimic how sites in the US work. Specifically, it:
90 
+
91 
+- Overrides the partner app to supply a new strategy selector which ensures all
92 
+  prices are return without taxes.
93 
+
94 
+- Overrides the checkout app in order to apply taxes to submissions once the
95 
+  shipping address is known.
96 
+
97 
+To browse the US site locally run:
98 
+
99 
+.. code-block:: bash
100 
+
101 
+   (oscar) $ make us_site
102 
+   (oscar) $ sites/us/manage.py runserver
103 
+
104 
+and the US site will be browsable at http://localhost:8000
105 
+
106 
+The demo site
107 
+-------------
108 
+
109 
+The demo site is *the* reference Oscar project as it illustrates how Oscar can
110 
+be redesigned and customised to build an realistic e-commerce store. The demo
111 
+site is a sailing store selling a range of different product types.
112 
+
113 
+The customisations on top of core Oscar include:
114 
+
115 
+* A new skin
116 
+* A variety of product types including books, clothing and downloads
117 
+* Payment with PayPal Express using django-oscar-paypal_.
118 
+* Payment with bankcards using Datacash using django-oscar-datacash_.
119 
+
120 
+.. _django-oscar-paypal: https://github.com/tangentlabs/django-oscar-paypal
121 
+.. _django-oscar-datacash: https://github.com/tangentlabs/django-oscar-datacash
122 
+
123 
+.. note::
124 
+
125 
+    Both the sandbox and demo site have the Django admin interface wired up.
126 
+    This is done as a convenience for developers to browse the model instances.
127 
+
128 
+    Having said that, the Django admin interface is *unsupported* and will fail
129 
+    or be of little use for some models. At the time of writing, editing
130 
+    products in the admin is clunky and slow, and editing categories is
131 
+    not supported at all.
132 
+
133 
+Browse the external demo site
134 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135 
+
136 
+An instance of the demo site is built periodically (but not automatically) and
137 
+available at http://demo.oscarcommerce.com. It is typically updated when new
138 
+versions of Oscar are released.
139 
+
140 
+Run the demo site locally
141 
+~~~~~~~~~~~~~~~~~~~~~~~~~
117
142
118 
 Assuming you've already set-up the sandbox site, there are two further services
 143 
 Assuming you've already set-up the sandbox site, there are two further services
119 
 required to run the demo site:
 144 
 required to run the demo site:

+ 12
- 0
docs/source/releases/v0.8.rst View File

15 
 Overview
 15 
 Overview
16 
 ========
 16 
 ========
17
17
18 
+Oscar now has a demo site customised for the US!
19 
+
18 
 .. _compatibility:
 20 
 .. _compatibility:
19
21
20 
 Compatibility
 22 
 Compatibility
55 
 Application instance is not necessary any more. Updated instructions are
 57 
 Application instance is not necessary any more. Updated instructions are
56 
 available in :doc:`/topics/customisation`.
 58 
 available in :doc:`/topics/customisation`.
57
59
60 
+US demo site
61 
+------------
62 
+
63 
+To help developers building sites for the US, a new example Oscar site has been
64 
+included in the repo. This customises core Oscar to treat all prices as
65 
+excluding tax and then calculate and apply taxes once the shipping address is
66 
+known.
67 
+
68 
+See :ref:`us_site` for more information.
69 
+
58 
 .. _minor_changes:
 70 
 .. _minor_changes:
59
71
60 
 Minor changes
 72 
 Minor changes

Write Preview
Loading…
Cancel
Save