neeto-image-uploader-nano

The neeto-image-uploader-nano manages assets across neeto products. The nano exports the @bigbinary/neeto-image-uploader-frontend NPM package and neeto-image-uploader-engine Rails engine for development.

Contents

• neeto-image-uploader-nano
• Contents
• Development with Host Application
  • Engine
    • Installation
  • Frontend package
    • Installation
    • Components
      • 1. AssetLibrary (source code)
      • 2. ImageUploader (source code)
      • 3. BasicImageUploader (source code)
    • Hooks
      • 1. useImageUpload (source code)
        • Import the hook
        • Invoke the hook
        • Call uploadImage to Upload an Image
    • Upload Config
• Instructions for Publishing

Development with Host Application

Engine

The engine is used to manage assets across neeto products.

Installation

1. Add this line to your application's Gemfile:

   source "NEETO_GEM_SERVER_URL" do
      # ..existing gems
   
      gem 'neeto-image-uploader-engine'
   end
   

2. And then execute:

   bundle install
   

3. Add this line to your application's config/routes.rb file:

   mount NeetoImageUploaderEngine::Engine, at: "/neeto_image_uploader"
   

4. Add the following keys to environment variables (all 6 keys are required):

   IMAGE_KIT_PUBLIC_KEY
   IMAGE_KIT_PRIVATE_KEY
   IMAGE_KIT_URL_ENDPOINT
   
   UNSPLASH_ACCESS_KEY #(for fetching images from unsplash)
   

Frontend package

Installation

1. Install the latest neeto-image-uploader-frontend package using the below command:

   yarn add @bigbinary/neeto-image-uploader-frontend
   

Components

1. AssetLibrary (source code)

Props

• isOpen: A boolean to specify whether the modal is open or not.
• onClose: A callback function triggered when the modal is closed.
• onUploadComplete: A callback function triggered when the image upload is complete.
• uploadConfig: Configuration object for image uploads.

Usage

import React, { useState } from "react";
import { AssetLibrary } from "@bigbinary/neeto-image-uploader-frontend";

const App = () => {
  const [isAssetLibraryOpen, setIsAssetLibraryOpen] = useState(false);
  const [image, setImage] = useState({ url: TEST_IMAGE_SRC, signedId: "" });

  const handleUploadComplete = image => setImage(image);

  return (
    <AssetLibrary
      isOpen={isAssetLibraryOpen}
      onClose={() => setIsAssetLibraryOpen(false)}
      onUploadComplete={handleUploadComplete}
    />
  );
};

export default App;

2. ImageUploader (source code)

Props

• onUploadComplete: A callback function triggered when the image upload is complete.
• className: Additional classes to be applied to the component.
• src: The source URL of the image to be displayed initially.
• uploadConfig: Configuration object for image uploads.
• fixedAspectRatio: An option to maintain a specific aspect ratio for the image. Expected input format is {height: number, width: number}.
• defaultImageSize: An option to set the initial crop size of the image. Expected input format is { height: number, width: number }.
• isOptionsDisabled: An option to disable dropdown to remove the already present image, or upload a new image.
• ref: A ref that exposes an upload(file) method to programmatically trigger an upload. Useful when the file is selected outside the component (e.g., via drag-and-drop on a canvas).

Usage

import React, { useState } from "react";
import { ImageUploader } from "@bigbinary/neeto-image-uploader-frontend";

const App = () => {
  const [isAssetLibraryOpen, setIsAssetLibraryOpen] = useState(false);
  const [image, setImage] = useState({ url: TEST_IMAGE_SRC, signedId: "" });

  const handleUploadComplete = image => setImage(image);

  return (
    <ImageUploader
      className="mb-8 h-52 w-80"
      key={image.url}
      src={image.url}
      onUploadComplete={handleUploadComplete}
    />
  );
};

export default App;

3. BasicImageUploader (source code)

Props

• src: The source URL of the image to be displayed initially.
• className: Additional classes to be applied to the component.
• imageFallbackProps: Props to be passed to the ImageWithFallback component.
• onDrop: Callback function triggered when an image is dropped or selected for upload.
• isDisabled: A boolean to specify whether the uploader is disabled.
• onRemove: Callback function triggered when the "Remove" button is clicked.

Usage

import React, { useState } from "react";
import { noop } from "neetocist";
import { BasicImageUploader } from "@bigbinary/neeto-image-uploader-frontend";

const App = () => {
  const [image, setImage] = useState({ url: TEST_IMAGE_SRC, signedId: "" });

  return (
    <BasicImageUploader
      className="h-52 w-80"
      src={image.url}
      uploadProgress={0}
      onDrop={noop}
      onRemove={() => setImage({ url: "", signedId: "" })}
    />
  );
};

export default App;

4. ImageForm (source code)

Props

• onChange: Callback function triggered when any form field changes.
• imageUploaderProps: Additional props to be passed to the ImageUpload component.
• className: Additional classes to be applied to the component.
• names: Object specifying field names for form integration:
  • image: Name of the image field in the form (e.g., "properties.imageUrl")
  • height: Name of the height field in the form (e.g., "height")
  • alignment: Name of the alignment field in the form (e.g., "alignment")
• logoHeight: Object specifying height constraints for the logo slider:
  • default: Default height value for the slider (default: 64)
  • min: Minimum height value for the slider (default: 64)
  • max: Maximum height value for the slider (default: 100)
• logoSizeVariableName: CSS variable name for controlling logo size (required)
• showAlignmentBlock: Boolean to control whether the alignment block is displayed (default: true)
• showAltTextBlock: Boolean to control whether the alt text input block is displayed (default: true)
• isLabelEnabled: Boolean to control whether the label is displayed in the image upload block (default: true)
• entityName: String to customize the entity name used in labels, placeholders, and tooltips (default: "Logo"). This allows host applications to override the hardcoded "Logo" text with custom entity names.

Usage

import { Formik } from "formik";
import { ImageForm } from "@bigbinary/neeto-image-uploader-frontend";

const App = () => {
  const handleUpdate = (fieldName, value) => {
    console.log(`Field ${fieldName} changed to:`, value);
  };

  return (
    <Formik
      initialValues={{
        properties: {
          imageUrl: "",
          height: 64,
          alignment: "left",
        },
        altText: "",
      }}
    >
      <ImageForm
        className="logo-form"
        imageUploaderProps={{ maxSize: 1048576 }}
        names={{
          image: "properties.imageUrl",
          height: "height",
          alignment: "alignment",
        }}
        logoSizeVariableName="--my-app-logo-size"
        entityName="Image"
        onChange={handleUpdate}
      />
    </Formik>
  );
};

export default App;

Hooks

1. useImageUpload (source code)

• The useImageUpload hook is a React custom hook that simplifies the process of uploading images in your application. It handles both development and production scenarios, tracks upload progress, and provides a clean interface for image uploading.
• Usage in neetoAuth.

Returns

• uploadImage: Function to initiate image upload. It takes two parameters:
  • file: The image file to be uploaded.
  • onUploadComplete: Callback function called when the upload is complete.
• uploadProgress: Number representing the upload progress (0-100).
• isUploading: Boolean indicating whether an upload is in progress.

Usage

Import the hook

import { useImageUpload } from "@bigbinary/neeto-image-uploader-frontend";

Invoke the hook

const { uploadImage, uploadProgress, isUploading } = useImageUpload();

Call uploadImage to Upload an Image

const handleImageUpload = async file => {
  uploadImage(file, uploadedImageData => {
    // Handle the uploaded image data
  });
};

Upload Config

The "Upload Config" section describes the default upload configuration. This configuration can be overridden by passing the uploadConfig prop.

{
  "maxImageSize": globalProps.endUserUploadedFileSizeLimitInMb,
  "allowedImageTypes": {
    "image/png": [".png"],
    "image/jpg": [".jpg", ".jpeg"],
    "image/gif": [".gif"],
    "image/svg+xml": [".svg"]
  }
}

Example: Overriding upload config in neetoForm.

Keys

• maxImageSize: The maximum size allowed for uploaded images.
• allowedImageTypes: An object specifying the allowed image types and their corresponding file extensions.

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.