Consider improving 'custom fields' documentation.

[oadslug]

Please consider improving the documentation for custom fields. It took me quite awhile to figure out how to implement this. Below are some example improvements that I think would be very helpful.

To add custom fields to the data sent to ShipStation, you will need to add some event methods to your own custom business logic plugin (example below).

The custom fields are: CustomField1: FIELD_CUSTOM_FIELD_1 CustomField2: FIELD_CUSTOM_FIELD_2 CustomField3: FIELD_CUSTOM_FIELD_3 InternalNotes: FIELD_INTERNAL_NOTES CustomerNotes: FIELD_INTERNAL_NOTES Gift: FIELD_GIFT GiftMessage: FIELD_GIFT_MESSAGE

Additionally, you can override the default data sent to ShipStation, such as the order number, shipping method, etc.

Order Number: FIELD_ORDER_NUMBER Shipping Method: FIELD_SHIPPING_METHOD

You might also consider adding a better example, which includes all of the custom fields (and any others that are commonly overwritten).

Your custom event listeners should be placed in your plugins init() function.

    Event::on(
        Xml::class,
        Xml::ORDER_FIELD_EVENT,
        function (OrderFieldEvent $e) {
            $fieldName = $e->field;
            $order = $e->order;

            // set shipstation xml custom field data
            if ($fieldName === OrderFieldEvent::FIELD_ORDER_NUMBER) {
                // ex. set shipstation order number to order id, instead of default short ref number
                $e->value = $order->id;
            } elseif ($fieldName === OrderFieldEvent::FIELD_SHIPPING_METHOD) {
                // do nothing, already set by properly by shipstation-connect
            } elseif ($fieldName === OrderFieldEvent::FIELD_CUSTOM_FIELD_1) {
                // ex. store ref number
                $e->value = "Order Ref: " . $order->getShortNumber();
                $e->cdata = true;
            } elseif ($fieldName === OrderFieldEvent::FIELD_CUSTOM_FIELD_2) {
                if ($order->getShippingMethod()->handle == "useYourOwnAccount") {
                    $e->value = "Cust Shipping Method: " . $order->getFieldValue('customerShippingMethod');
                    $e->cdata = true;
                } else {
                    $e->value = "";
                    $e->cdata = true;
                }
            } elseif ($fieldName === OrderFieldEvent::FIELD_CUSTOM_FIELD_3) {
                if ($order->getShippingMethod()->handle == "useYourOwnAccount") {
                    $e->value = "Cust Shipping Account: " . $order->getFieldValue('customerShippingAccount');
                    $e->cdata = true;
                } else {
                    $e->value = "";
                    $e->cdata = true;
                }
            } elseif ($fieldName === OrderFieldEvent::FIELD_INTERNAL_NOTES) {
                $e->value = "";
                $e->cdata = true;
            } elseif ($fieldName === OrderFieldEvent::FIELD_CUSTOMER_NOTES) {
                $e->value = $order->getFieldValue('customerComments');
                $e->cdata = true;
            } elseif ($fieldName === OrderFieldEvent::FIELD_GIFT) {
                $e->value = 0;
                $e->cdata = false;
            } elseif ($fieldName === OrderFieldEvent::FIELD_GIFT_MESSAGE) {
                $e->value = "";
                $e->cdata = true;
            } else {
                // do nothing
            }
        }
    );

Information about class references would also be helpful.

In addition, depending on what you are modifying, you may need to add some of the 'shipstationconnect' class references to your primary plugin class.

use fostercommerce\shipstationconnect\controllers\OrdersController;
use fostercommerce\shipstationconnect\services\Xml;
use fostercommerce\shipstationconnect\events\OrderFieldEvent;
use fostercommerce\shipstationconnect\events\FindOrderEvent;

Just a suggestion. Thanks.

[benface]

Thank you @oadslug, we’ve taken your suggestions into consideration and improved the documentation.

[iamkeir]

Is this the only way to map a gift/delivery note?

[sjcallender]

@iamkeir - Through custom fields, yes.

[iamkeir]

@sjcallender thanks - that's ok for us as we're devs, so building this into a module is fine, however might be a feature request for people who are not so tech-savvy to be able to map custom fields via the admin UI. Worth me making another ticket?