neeto-themes-nano

The neeto-themes-nano allows us to build and use themes within neeto applications. This nano exports @bigbinary/neeto-themes-frontend NPM package and neeto-themes-engine Rails engine.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Usage
   • Frontend package
     • Installation
     • Instructions for development
     • Usage
2. Instructions for Publishing

Development with Host Application

Engine

Installation

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

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

2. And then execute:

   bundle install
   

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

    mount NeetoThemesEngine::Engine, at: "/neeto_themes"
   

4. Add required migrations in the db/migrate folder. Run the following commands to copy the migrations from the engine to the host application.

   bundle exec rails neeto_themes_engine:install:migrations
   bundle exec rails db:migrate
   

5. Add the following line to models/organization.rb file.

   has_many :themes, class_name: "NeetoThemesEngine::Theme", as: :owner
   

6. Configure model to add below association to attach theme.

   has_one :theme_entity, as: :themeable, class_name: "NeetoThemesEngine::ThemeEntity", dependent: :destroy
   has_one :theme, through: :theme_entity, class_name: "NeetoThemesEngine::Theme"
   

Usage

1. Create an engine initializer

   Create a file named neeto_themes_engine.rb in the config/initializers folder.

2. Customize theme schema

   The engine supports customizing theme schemas based on the needs of the host application. This schema will be used in the frontend to render the theme properties. Eg:

    NeetoThemesEngine.theme_properties_schema = [
      { kind: "color", key: "primary_color", default_value: "#2D36D4" },
      { kind: "color", key: "secondary_color", default_value: "#ECF4FF" },
    ]
   

   Each object in the array should have the following keys:

   • key: The unique identifier for the theme property.

   • kind: The kind of the theme property.

   Optional keys that can be included:

   • default_value: Sets a default value when creating a new theme.

   • hidden: This boolean prop helps to hide the property from the UI but allows to use it as CSS variable.

   • depends_on: Provides a dependency on other properties. If a key is provided, it will check for its value and only appear in the UI if the dependent property is present.

   • parent_class: This key needs to be added for custom css feature to work properly. See more on custom css feature.

   • use_default_image_size: Used to apply defaultImageSize prop passed to ImageUploader component.

   • default_image_size: Used to pass defaultImageSize prop passed to ImageUploader component. Should be an object with width and height properties.

   • fixed_aspect_ratio: Used to pass fixedAspectRatio prop passed to ImageUploader component. Should be an object with width and height properties.

   • max_image_size_in_mb: Maximum size of the uploaded image in MB for an image kind property. Accepts decimals, eg: 0.1. Defaults to 1.

3. Provide a css variable prefix

   This value will be used to prefix all CSS variables. Eg:

     NeetoThemesEngine.css_variable_prefix = "neeto-cal"
   

   variable generated for the theme property primary_color will be --neeto-cal-primary-color.

4. Provide the entities to which the theme property is attached

   This value will be used to determine the entity to which the theme property is attached. We can provide multiple entities. Eg:

     NeetoThemesEngine.valid_themeable_types = ["Meeting", "Booking"]
   

5. Provide a default theme name (Optional)

   This provided value will be used to identify the default theme. If not provided, the default theme will be named "Plain blue".

     NeetoThemesEngine.default_theme_name = "My theme"
   

Frontend package

Installation

1. Add the neeto-themes-frontend package to the package.json

   yarn add @bigbinary/neeto-themes-frontend
   

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Usage

Components

1. Import the NeetoThemesBuilder component from @bigbinary/neeto-themes-frontend:

   import React from "react";
   import { NeetoThemesBuilder } from "@bigbinary/neeto-themes-frontend";
   
   const App = () => (
     <NeetoThemesBuilder
       entityId={meeting?.id}
       entityType="Meeting"
       thumbnail={Thumbnail}
     >
       <Preview />
     </NeetoThemesBuilder>
   );
   
   export default App;
   

   Props:

   • entityId (required): The ID of the entity to which the theme is attached.
   • entityType (required): The type of the entity (e.g., "Meeting", "Booking").
   • thumbnail (required): A React component to display as the theme thumbnail.
   • children (required): The preview component to render.
   • onPropertiesChange (optional): Callback function triggered when theme properties change.
   • defaultImageSize (optional): Default image size for image uploads. Should be an object with width and height properties.
   • fixedAspectRatio (optional): Fixed aspect ratio for image uploads. Should be an object with width and height properties.
   • helpDocUrl (optional): URL to the help documentation.
   • isTemplateThemesEnabled (optional): Boolean to enable template themes feature. Default: false.
   • pageTitle (optional): Custom page title for the theme builder.
   • onApplyThemeSuccess (optional): Callback function triggered when a theme is successfully applied.
   • onUpdateThemeSuccess (optional): Callback function triggered when a theme is successfully updated.
   • onApplyGlobalThemeSuccess (optional): Callback function triggered when a global theme is successfully applied.
   • helpPopoverProps (optional): Props to pass to the help popover component.
   • enabledFeatures (optional): Object to control which features are enabled. Default: { customCSS: true }. Set { customCSS: false } to disable the Custom CSS feature.
   • proFeatures (optional): Object to specify which features should be marked as "pro" features. Example: { customCSS: true } will mark Custom CSS as a pro feature.

hooks

1. Import useThemeUtils hook from "@bigbinary/neeto-themes-frontend"

   import { useThemeUtils } from "@bigbinary/neeto-themes-frontend";
   
   const { setTheme, previewingTheme, currentTheme } = useThemeUtils();
   

• setTheme: This method is used to set the theme for the entity.

• previewingTheme: This object contains the currently previewing theme.

• currentTheme: This object contains the current theme which is applied to the entity.

Custom CSS

neeto-themes-nano will inject custom css into your application as part of a theme. You can provide enabledFeatures={{ customCSS: false }} in NeetoThemesBuilder to manually hide the CustomCSS feature. You can pair it with proFeatures={{ customCSS: true }} to show it disabled in non-enabled cases.

This feature requires the initializer to be set with the additional property { kind: "custom_css", key: "custom_css", default_value: "", parent_class: "neeto-form-eui" }. The parent_class key will be used as a parent to inject styles and for CSS nesting. This ensures that styles are not injected on pages where you do not want it and also ensures that style rules targeting elements outside this class will not be applied. Please ensure that the value provided toparent_classis present in your application as a wrapper CSS class. For example:neeto-form-eui in neetoForm is present in all external pages where theme needs to be applied. . It also provides a code editor with syntax highlighting which depends on Monaco editor as a peer dependency. Please install it in the host application for proper working.

Instructions for Publishing

TBD

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