solidusio / edgeguides Goto Github PK

How tax calculation works in Solidus, how to integrate with a custom tax calculation service etc.

• https://guides.solidus.io/developers/customizations/customizing-attributes.html

• https://guides.solidus.io/developers/returns/overview.html
• https://guides.solidus.io/developers/returns/customer-returns.html
• https://guides.solidus.io/developers/returns/reimbursement-types.html
• https://guides.solidus.io/developers/returns/reimbursements.html
• https://guides.solidus.io/developers/returns/return-authorizations.html
• https://guides.solidus.io/developers/returns/return-items.html

• https://guides.solidus.io/developers/shipments/overview.html
• https://guides.solidus.io/developers/shipments/cartons.html
• https://guides.solidus.io/developers/shipments/custom-shipping-calculators.html This should go in the Advanced Solidus section.
• https://guides.solidus.io/developers/shipments/shipment-setup-examples.html This may not be necessary to include.
• https://guides.solidus.io/developers/shipments/shipping-method-filters.html: not sure, this may be either in YARD document or in the guides.
• https://guides.solidus.io/developers/shipments/solidus-active-shipping-extension.html This should be eliminated entirely.
• https://guides.solidus.io/developers/shipments/split-shipments.html: this may be a mix of guides and YARD documentation.
• https://guides.solidus.io/developers/shipments/user-interface-for-shipments.html should be eliminated altogether.

• https://guides.solidus.io/developers/users/addresses.html
• https://guides.solidus.io/developers/users/custom-authentication.html will be moved to Advanced Solidus.

• https://guides.solidus.io/developers/preferences/add-model-preferences.html
• https://guides.solidus.io/developers/preferences/app-configuration.html
• https://guides.solidus.io/developers/preferences/class-extension-points.html This one is already explained in the core customization guide.

• https://guides.solidus.io/developers/assets/asset-management.html
• https://guides.solidus.io/developers/assets/override-solidus-assets.html

code snippet title paths replace _ for : (e.g.: app/models/spree:user.rb instead of app/models/spree_user.rb)

OS: Windows 10
Broweser: Chrome, Firefox

• How to use solidus_dev_support to generate and maintain an extension.
• Best practices around versioning, changelogs, configuration management.
• Using "private" extensions to encapsulate your store's customizations.
• Best practices for customization: don't customize the frontend, limit the use of Deface and prependetc.
• Using the event bus to emit custom events.
• https://guides.solidus.io/developers/extensions/writing-extensions.html
• https://guides.solidus.io/developers/extensions/testing-extensions.html

The "Menu Items" and "Search Forms" paragraphs in the current guides can be ported to the new backend customization guide: https://guides.solidus.io/developers/customizations/customizing-admin.html.

• https://guides.solidus.io/developers/locations/overview.html (this one may even go in the Users Guide, not sure)
• https://guides.solidus.io/developers/locations/countries-and-states.html
• https://guides.solidus.io/developers/locations/zones.html (this one may even go in the Users Guide, not sure)

Hello! 👋 If you're here, it means you want to contribute to the new version of the Solidus Developer Guides. That's awesome, and I want to give you a few pointers on where to start!

Gitbook integration

This repository is linked to a Gitbook project and deployed at https://edgeguides.solidus.io. Each push to the master branch will trigger a deployment of the guides.

For writing, you can use Markdown and you can leverage all of Gitbook's custom features such as hints and tabs. In fact, you're strongly encouraged to use both hints and tabs in order to better organize the content.

If you need some inspiration, look at some of the existing guides in this repository.

How to contribute

There are different ways to contribute to the new guides:

• By writing the missing guides. Just pick a piece of content that is missing and go for it! If you want to propose adding a new chapter or moving chapters around, please open an issue first, as we put a lot of work into the new table of contents.
• By reviewing and testing the existing content. We're pushing out a lot of documentation and it's easy to screw up. Reviewing the content that's already been written to make sure it's up-to-date and working is one of the most important things you can do.
• By improving the YARD documentation. We're in the process of moving content from the old guides to here, but much of the old content is actually better suited for YARD documentation than actual guides. The work we're doing is two-fold: on one hand, we're completing the new guides; on the other, we're moving everything that doesn't belong in the guides to the YARD documentation of the core gems. (A list of what we think should go into the YARD documentation will come soon.)

We need help in all three of these areas, so don't be shy!

I'm stuck! What do I do?

Ping @aldesantis here on GitHub or @alessandro in the Solidus Slack workspace.

• How to write your own promotion rule
• How to write your own promotion action
• Gotchas in the promotion system (promotion chooser, rule evaluation etc.)

A lot of content can be taken from https://guides.solidus.io/developers/promotions/overview.html.

• https://guides.solidus.io/developers/payments/overview.html
• https://guides.solidus.io/developers/payments/payment-methods.html
• https://guides.solidus.io/developers/payments/payment-processing.html
• https://guides.solidus.io/developers/payments/payment-service-providers.html
• https://guides.solidus.io/developers/payments/payment-sources.html
• https://guides.solidus.io/developers/payments/payments.html
• https://guides.solidus.io/developers/payments/refunds.html

• https://guides.solidus.io/developers/inventory/overview.html
• https://guides.solidus.io/developers/inventory/inventory-units.html
• https://guides.solidus.io/developers/inventory/stock-items.html
• https://guides.solidus.io/developers/inventory/stock-movements.html

https://guides.solidus.io/developers/adjustments/overview.html

When we migrated to the new guides, it looks like we lost an update to the documentation on customizing image sizing for product/variant and taxon images.

This change solidusio/solidus#4245 made an update to the legacy guides which describes how to use the provided configuration to override the default sizes for predefined image variants.

Solidus Version:
N/A

To Reproduce

1. View the guides on customizing image sizes - https://guides.solidus.io/advanced-solidus/images-and-image-processing/#customizing-image-sizes
2. These guides still suggest introducing decorators to specify new sizes - https://github.com/solidusio/edgeguides/blob/main/docs/advanced-solidus/images-and-image-processing.mdx?plain=1#L48-L68
3. Since solidusio/solidus#4062 we have configuration for these settings for both product/variant images - https://github.com/solidusio/solidus/blob/6a732e2711d834656ed1d9072abf0a8130f0c265/core/lib/spree/app_configuration.rb#L541-L544 and for taxon images https://github.com/solidusio/solidus/blob/6a732e2711d834656ed1d9072abf0a8130f0c265/core/lib/spree/app_configuration.rb#L564-L571
4. This was fixed in the Legacy guides (in this PR solidusio/solidus#4245) and we should port that over https://legacy-guides.solidus.io/developers/products-and-variants/product-images#image-settings

• https://guides.solidus.io/developers/customizations/customizing-mailers.html

• https://guides.solidus.io/developers/calculators/overview.html
• https://guides.solidus.io/developers/calculators/promotion-calculators.html
• https://guides.solidus.io/developers/calculators/shipping-calculators.html
• https://guides.solidus.io/developers/calculators/tax-calculator.html

• https://guides.solidus.io/developers/promotions/overview.html
• https://guides.solidus.io/developers/promotions/promotion-actions.html
• https://guides.solidus.io/developers/promotions/promotion-handlers.html
• https://guides.solidus.io/developers/promotions/promotion-rules.html

Once we are done with the "basic" guides, we should probably work on creating a cookbook with different tutorials on how to implement certain features or customizations with Solidus. The recipes can be anything: we could advise people to roll their own implementation, use an extension or even provide both options when possible.

Here's a few ideas I collected:

• GDPR/CCPA compliance
• BI tool integration (Tableau, Looker, Blazer)
• Replatform from X
• Content management
• Marketplace/multitenancy
• Global commerce (going international)
• Sending emails with MailChimp, Klaviyo etc.
• Using Solidus with the Citadel architecture
• Using caching properly

• https://guides.solidus.io/developers/orders/overview.html
• https://guides.solidus.io/developers/orders/display-total-methods.html
• https://guides.solidus.io/developers/orders/order-state-machine.html
• https://guides.solidus.io/developers/orders/payment-states.html
• https://guides.solidus.io/developers/orders/update-orders.html

https://guides.solidus.io/developers/users/custom-authentication.html

There is a typo in customizing the backend documentation:

how to set it upeckout/address) to accomplish tha

https://github.com/solidusio/edgeguides/blame/a6e649fe001028c7c4bb00d08c3f5f76c99b3cbc/docs/customization/customizing-the-backend.mdx#L106

I don't know what should be written there.

https://guides.solidus.io/developers/customizations/state-machines.html

To Reproduce

Open this pages:

• https://guides.solidus.io/advanced-solidus/promotions-system
• https://guides.solidus.io/advanced-solidus/promotions-system/
• https://guides.solidus.io/advanced-solidus/promotions-system/index.html

go to the link at the bottom of the page pointing toward How to use a custom promotion adjuster

sometimes it will generate a url relative to /advanced-solidus rather than the root:

https://guides.solidus.io/how-tos/how-to-use-a-custom-promotion-adjuster/

vs.

https://guides.solidus.io/advanced-solidus/how-tos/how-to-use-a-custom-promotion-adjuster

Screenshots

Additional context

Reported by a user and reproduced, although not consistently.

• https://guides.solidus.io/developers/products-and-variants/overview.html
• https://guides.solidus.io/developers/products-and-variants/multi-currency-support.html
• https://guides.solidus.io/developers/products-and-variants/product-images.html
• https://guides.solidus.io/developers/products-and-variants/product-properties.html
• https://guides.solidus.io/developers/products-and-variants/products.html
• https://guides.solidus.io/developers/products-and-variants/taxonomies-and-taxons.html
• https://guides.solidus.io/developers/products-and-variants/variants.html

Ref: https://github.com/kennyadsl/solidus-searchkick-example/commits/main
cc @kennyadsl

• https://guides.solidus.io/developers/taxation/overview.html: should be a mix of YARD documentation and guides.
• https://guides.solidus.io/developers/taxation/custom-tax-calculators.html can be removed altogether, doesn't seem like it provides much value.
• https://guides.solidus.io/developers/taxation/displaying-prices.html not particularly useful.
• https://guides.solidus.io/developers/taxation/example-tax-setups.html can be removed.
• https://guides.solidus.io/developers/taxation/value-added-tax.html may go in the guides, or can be removed.

See solidusio/solidus#4791

• Basic intro to CanCan(Can)
• How to write your own permission set
• How to make roles dynamic (solidus_user_roles?)
• https://guides.solidus.io/developers/customizations/customizing-permissions.html

We should provide an overview of all the possible customizations around 3PL/logistics/stock management, including pointers for developers who want to integrate with a custom 3PL and best practices (e.g. if you rely on external APIs to calculate shipping rates, have a fallback in place so your checkout doesn't explode if something goes wrong in the API call).

How the search API works, how to write your custom search etc.