Shipments documentation #2353
Shipments documentation #2353
Conversation
guides/shipments/split-shipments.md
Outdated
| ``` | ||
|
|
||
| If you want to add different splitters for each of your `Spree::StockLocation`s, | ||
| you can decorate the `Spree::Stock::Coordinator` class and override the |
There was a problem hiding this comment.
I think this is an old reference and should be updated to Spree::Stock::SimpleCoordinator.
There was a problem hiding this comment.
I have, again, nits. There is still some stuff from the old guides in here that flat out would not work in a current Solidus store ("Calculators take an array of line items").
I think those bits should either be deleted or significantly revised, but that can be done in subsequent PRs. Hence: 👍
| `Spree::Order`'s' state is set to `delivery`. This occurs before the customer | ||
| has completed their order at checkout. | ||
|
|
||
| The simple coordinator deletes any existing shipments for an order and then |
There was a problem hiding this comment.
That's technically not correct. The coordinator only builds shipments for an order, the deletion happens in code that calls the coordinator.
Maybe instead:
The SimpleCoordinator takes an order and builds as many shipments as are necessary to fulfill it.
| The simple coordinator performs a number of tasks in order to create shipment | ||
| proposals: | ||
|
|
||
| 1. The coordinator calculates the availability of the ordered items. |
There was a problem hiding this comment.
It doesn't calculate, just checks.
| In order to split shipments, Solidus runs a series of splitters in sequence. The | ||
| first splitter in the sequence takes the array of packages from the order, | ||
| splits the order into packages according to its rules, then passes the packages | ||
| on to the next splitter in the sequence. |
There was a problem hiding this comment.
For each shipment that is thus generated, a shipping method is chosen. (this is to clarify that the splitting does not have anything to do with how the shipment is packed or shipped, instead the shipment is actually split in two separately fulfillable entities).
| - [Shipping category splitter][shipping-category-splitter]: Splits an order into | ||
| packages based on a product's shipping categories. This means that each | ||
| package only has items that belongs to the same shipping category. | ||
| - [Weight splitter][weight-splitter]: Splits an order into packages based on a |
There was a problem hiding this comment.
Thanks for this!
| package only has items that belongs to the same shipping category. | ||
| - [Weight splitter][weight-splitter]: Splits an order into packages based on a | ||
| weight | ||
| threshold. This means that each package has a maximum weight: if a new item |
| weight | ||
| threshold. This means that each package has a maximum weight: if a new item | ||
| is added to the order and it causes a package to go over the weight threshold, | ||
| a new package is created. All packages need to weigh less than the threshold. |
There was a problem hiding this comment.
s/package/shipment.
While in the code, the thing is called a package, the end result is a new shipment. Package sounds like we're referring to the boxes inside the shipment, but we're not.
There was a problem hiding this comment.
I wasn't 100% clear on this distinction until you brought up Spree::Stock::Package in a comment. I've made a to-do so that this article would clearly make a distinction between packages and shipments. Thanks so much for your reviews.
|
|
||
| <!-- TODO: | ||
| Give more context to the code block above. Would you/how would you | ||
| practically use this in your app? --> |
There was a problem hiding this comment.
Maybe just remove this section for now. solidus_active_shipping is a beast, and hard to customize or understand...
There was a problem hiding this comment.
I ended up removing most of the content under the "Match the delivery service's provided name", but do you mean this whole article?
|
|
||
| ## Custom calculator requirements | ||
|
|
||
| Your calculator should accept an array of `LineItem` objects that are associated |
There was a problem hiding this comment.
The calculator takes a Spree::Stock::Package object, not an Array of line items. That object has access to the package.order and through that to all other stuff in the order.
However, when dealing with the contents of the package (that really is a shipment), as a developer you must deal with the package.contents array. If your store does split shipments, you will otherwise quote the entire order when you only want to quote the contents of one shipment of many.
| "USPS Bogus First Class International" | ||
| end | ||
|
|
||
| def available?(order) |
There was a problem hiding this comment.
This is old code that would not work in current solidus versions. The available? method now takes a Spree::Stock::Package.
| cost and add tracking codes when editing an order. They can also perform other | ||
| tasks, such as splitting a single shipment into multiple shipments. | ||
|
|
||
| In the Solidus demo store, edit any order (from the `/admin/orders` URL) and go |
There was a problem hiding this comment.
For completed orders, the shipments tab is the default interface. It might feel confusing to users if they think they have to navigate.
benjaminwil
force-pushed
the
shipments_documentation
branch
2 times, most recently
from
eab5fd9
to
b4026c6
Compare
I intend to split the shipments guide into multiple articles. This would be the first of many infrastructural changes to the Solidus guides.
This article revises the documentation for split shipment management in Solidus, which changed as of Solidus v2.4.0. See solidusio#2199 for more information.
This commit removes the "Advanced shipping methods" article from the shipments overview and replaces it with a more focused article about creating custom shipping calculators. The other information that appeared under the advanced shipping methods umbrella will still appear in the overview article -- they'll just be moved around a bit.
Adds short introductions to inventory units and cartons. Also adds an article stub where we should go into more detail about carton usage.
benjaminwil
force-pushed
the
shipments_documentation
branch
from
b4026c6
to
2288678
Compare
|
|
||
| This article provides a summary of shipping concepts. If you are interested in | ||
| reading about example Solidus shipment setups see | ||
| [Shipment setup examples](shipment-setup-examples.html.markdown). |
There was a problem hiding this comment.
This link is broken, or am I missing something?
There was a problem hiding this comment.
Thanks for catching this @afdev82. Should be shipment-setup-examples.md. I will push an update soon.
| address, what shipping method is being used, and so on. | ||
|
|
||
| If your store has complex shipping needs, you may find one of Solidus's existing | ||
| shipping extensions, like [`solidus_active_shipping`][solidus-active-shipping] |
There was a problem hiding this comment.
Also this link seems to be broken
benjaminwil
force-pushed
the
shipments_documentation
branch
from
2288678
to
81c5a03
Compare
benjaminwil
force-pushed
the
shipments_documentation
branch
from
81c5a03
to
bf9f9bd
Compare
I am taking the shipping guide documentation merged in #1966 and I am breaking it into several articles about shipments. My goals are to:
This PR splits the
guides/shipping.mdarticle into multipleguides/shipments/*.mdarticles. Much of the content has been rewritten and all of it has been reformatted.The most remarkable changes are the the "Shipment setup examples" and "Split shipments" articles. I wanted to create more realistic shipment setups, and as of #2199 (Solidus v2.4.0) split shipments use the
Spree::Stock::SimpleCoordinatorinstead of using coordinators, adjusters, packers, etc.This is part a larger project to improve Solidus's documentation. See this gist with the high-level table of contents. Where and how this documentation will exist is still up for discussion.