Installation

npm install aico-image-editor

npm run dev

Dependencies

aico-image-editor requires you to add these two libraries before adding script from the package Add these two lines before adding link to the package.

1. fabric.js which is for doing canvas based operations very efficiently
2. fabriceraser.js which is taken as an addon to the fabric for having the eraser functionality.

<script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.0/fabric.min.js"></script>

<script src="{{ url('js/fabriceraser.js') }}" ></script>

3. In addition to above, package requires you to have these libraries to be present at window(global) level as they were used as a peerDependencies in the package. These libraries are bootstrap, alpinejs and @alpinejs/persist. So check whether these are present and if not please add them manually.

Usage

After running above commands in installation step, it will basically publish folder named aico-image-editor/output in the public directory.

You can get the umd version of the package from there. Please note that you need to add data-app-url and data-openai-api-key attributes along with the script to inform the library about your application url with workspace if any so that it can create public path (link to images and other assets like fonts etc...) starting from that url. and api key for open ai platform for ai related operations.

For example, this is how it is used in laravel

script src="{{ url('aico-image-editor/output/js/index.js') }}" data-app-url="{{ config('app.url') }}" data-openai-api-key="{{ env('OPENAI_KEY') }}"></script>

Within the html.

Once all of the above scripts have been added, you can initialize on the element like this. imageModalToggle is the name of alpine data which you will be using to pass apiConfig object to configure the canvas configurator.

    div x-data="imageModalToggle({
        apiUrl: '{{ config('app.url') }}',
        apiToken: '{{ $apiToken }}',
        configuratorId: '{{ $configuratorId }}',
        productId: '{{ $productId }}',
        locale: '{{$currentLanguage}}',
        productMainImage: '{{$productMainImage}}',
        eventId: '{{$eventId}}'
    })" @click="updateConfigurator()">
</div>

Let's understand each and every parameter step by step which needs to be passed as the apiConfig object.

• apiUrl: this should be your workspace url same as data-app-url attribute in the script.
• apiToken: this is the token which is used for authentication im the header along with the request.
• configuratorId: this is the id for which you would want to reload configuration that you saved earlier.
• productId: this is the id for which new configuration will be created. if configuratorId is not there and productId is present, new configurator will be auto created for that productId when you save.
• locale: currently active locale for translation. Only two values are allowed for now which en_US and de_CH.
• productMainImage: this should be the path to the main image (which will appear in the first pictured tab) which you need to update every time you open the configurator.
• eventId: this should be unique id associated with the component so that event with this name can be triggered after save.

Once you initialized the configurator on any element this way, you can get the bundle image from it when you hit save button by using event which is named using this convention: @bundle-image-processed-<eventId>.window. It will create bundleFile which can be obtained using event.detail.bundleFile.

e.g. in laravel livewire, this is how it can be used to upload the file to component using $wire.upload syntax in alpine js.

@bundle-image-processed-{{$eventId}}.window="($event) => {
    if($event.detail.bundleFile) {
        $wire.upload('uploadedImage', $event.detail.bundleFile)
    }
}"

In the script which consumes library.

const {prepareEditorHTML, productPicturesData, updateEditorConfig} = window.aicoEditor

window.aicoEditor provides us theese three information which is needed. So we are destructring and storing them in individual variables.

• prepareEditorHTML - It is one button html which package will add inside your given/passed element.
• productPicturesData - It is the plain object version of the mainPictures alpine data. You need to pass this to Alpine.reactive method to be able to modify it.
• updateEditorConfig - It is the function which updates the configuration of editor everytime just before the configurator modal opens. It expects $store and apiConfig as parameters. so that it can loads the configuration with updated values after configuratorId changes

document.addEventListener('alpine:init', function() {
    Alpine.data('imageModalToggle', (apiConfig = {}) => ({
        init() {
            prepareEditorHTML(this.$el);
        },
        
        updateConfigurator() {
            updateEditorConfig(this.$store, apiConfig)

            const productPictures = Alpine.reactive(productPicturesData);
            productPictures.mainPictures = [];

            if(apiConfig?.productMainImage) {
                let url = apiConfig?.productMainImage;

                productPictures.mainPictures.push({
                    id: `main-image-${apiConfig.productId}`,
                    url: url,
                    label: url.substring(url.lastIndexOf("/") + 1, url.lastIndexOf("."))
                })

            }
        },
        
    }))
})

This way, when element is initialized, library will append button element inside element. and then you can create function like updateConfigurator above to update configuration each time someone clicks the button to open the modal using updateEditorConfig function obtained from the package. This sends $store and apiConfig information necessary for function to work.

You can also empty older mainPictures by resetting array to empty and then again populating new values for productPictures.mainPictures which is what this code is for. If you want to add subPictures you need to push to productPictures.subPictures.

const productPictures = Alpine.reactive(productPicturesData);
productPictures.mainPictures = [];

if(apiConfig?.productMainImage) {
    let url = apiConfig?.productMainImage;

    productPictures.mainPictures.push({
        id: `main-image-${apiConfig.productId}`,
        url: url,
        label: url.substring(url.lastIndexOf("/") + 1, url.lastIndexOf("."))
    })
}

id, url and label are needed for the mainPicture object to push to the existing array of mainPictures.

Note that we have generated label by extracting the file's name information from productMainImage itself but you can use any other label string which suits you. label is necessary for searching through that label in searchbox.

[!TIP]: We have already created component which can be directly used by using the above way in livewire. If productId and configuratorId both are null then this editor can just be used to get image output as a bundleFile via the event.

<div>
    <livewire:pim::pages.bundles.image-combiner-modal
            :configuratorId="<configuratorId>"
            :productId="<productId>"
            :eventId="<eventId>"
            :productMainImage="<productMainImagePath>"
            :modalEl="'<modalElementId>'"
            wire:key="<Unique_livewire_key>"
    />
</div>

and then we can get the final file using event we illustrated earlier.