Discuss on Discord
Open a GitHub issue
Tags
Available tags
To help you integrate Simple Commerce into your Antlers templates, Simple Commerce provides various tags:
Form Tags
Some Simple Commerce tags output <form> elements that submit to Simple Commerce endpoints. There's a couple of optional parameters you can add to form tags.
-
redirect- the URL where you'd like to redirect the user after a successful form submission. -
error_redirect- the URL where you'd like to redirect the user after any validation errors are thrown by the form. -
request- the name of the Form Request you wish to use for validation of the form.
1{{ sc:cart:addItem redirect="/cart" }}2 <input type="hidden" name="product" value="{{ id }}">3 <input type="hidden" name="quantity" value="1">4 <button class="button-primary">Add to Cart</button>5{{ /sc:cart:addItem }}Hot Tip: I'd highly recommend disabling the button after the user submits the form to prevent them from submitting it multiple times.
When Simple Commerce builds the HTML for your form, any of the optional parameters you provide will be encrypted for additional protection (so you're users can't mess with redirects/requests by editing your HTML).
However, if you wish to use static caching or submit SC's forms via AJAX, you'll probably want to disable this behaviour. You may do so by adding the following to your configuration file:
1// config/simple-commerce2 3'disable_form_parameter_validation' => true,Field Whitelisting
When using Form Tags, Simple Commerce will now require you to specify any additional fields you wish to be editable via front-end forms.
For example: you may wish for customers to fill in the shipping_note field via the {{ sc:cart:update }} form but you wouldn't want them filling the is_paid field.
With 'field whitelisting', you must specify the fields you wish to allow in the Simple Commerce config file.
1/* 2|-------------------------------------------------------------------------- 3| Field Whitelist 4|-------------------------------------------------------------------------- 5| 6| You may configure the fields you wish to be editable via front-end forms 7| below. Wildcards are not accepted due to security concerns. 8| 9| https://simple-commerce.duncanmcclean.com/tags#field-whitelisting10|11*/12 13'field_whitelist' => [14 'orders' => [15 'shipping_name', 'shipping_address', 'shipping_address_line2', 'shipping_city', 'shipping_region',16 'shipping_postal_code', 'shipping_country', 'use_shipping_address_for_billing', 'billing_name', 'billing_address',17 'billing_address_line2', 'billing_city', 'billing_region', 'billing_postal_code', 'billing_country',18 ],19 20 'line_items' => [],21],Validation
Like noted above, you can use the request parameter when creating form tags to specify a Form Request to be used for validation purposes. You can either tell it the full class name (including the namespace) or without it.
1{{## Form Request: app\Http\Requests\CheckoutInformationRequest ##}}2 3{{ sc:cart:update request="CheckoutInformationRequest" }}4 5{{ /sc:cart:update }}Although you can specify the request parameter on any form tag, not all of them will actually use it. Here's a list of the forms that do:
-
{{ sc:cart:addItem }} -
{{ sc:cart:updateItem }} -
{{ sc:cart:update }} -
{{ sc:customer:update }} -
{{ sc:checkout }}
Blade support
At the moment, I've not got any plans to introduce first-party support for Blade (or any similar templating languages for that metter).
Alias
If you'd prefer not to use the shorthand of sc in your tags, you can also use simple-commerce which will work the same way.
This could be used to give more context of the tag in use to make it clear it's dealing with Simple Commerce.
1{{ simple-commerce:countries }}