Crysicia / ntq-excelsior

NtqExcelsior

Ntq excelsior simplifie l'import et l'export de vos données.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add ntq_excelsior

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install ntq_excelsior

Usage

Export

# Exporter class
class UserExporter < NtqExcelsior::Exporter

  styles ({
    blue: {
      fg_color: "2F5496",
    }
  })

  schema ({
    name: 'Utilisateurs',
    extra_headers: [
      [
        {
          title: "Utilisateurs",
          width: -> (context) { context[:current_user].can?(:access_to_email, User) ? 4 : 3 },
          # width: 4,
          styles: [:bold]
        }
      ],
    ],
    columns: [
      {
        title: 'Name',
        resolve: -> (record) { [record.first_name, record.last_name].join(' ') },
        styles: [:bold, :blue]
      },
      {
        title: 'Email',
        header_styles: [:blue],
        resolve: 'email',
        visible: -> (record, context) { context[:current_user].can?(:access_to_email, User) }
      },
      {
        title: 'Birthdate',
        resolve: 'birthdate',
        visible: true # Optional
      }
      {
        title: 'Address (nested)',
        resolve: ['address', 'address_one']
      },
      {
        title: 'City (nested)',
        resolve: ['address', 'city']
      },
      {
        title: 'Age',
        resolve: 'age',
        type: :number
      },
      {
        title: 'Civilité', 
        list: ['M', 'Ms', 'Autres']
      },
      {
        title: 'Active',
        resolve: -> (record) { record.active ? 'Oui' : 'Non' }
        # See axlsx example at https://github.com/caxlsx/caxlsx/blob/master/examples/list_validation_example.md for more options
        list: {
          options: ['Oui', 'Non'],
          show_error_message: true,
          error_title: 'Active', # Optional
          error: 'Authorized value: Oui non',
          errorStyle: :stop, # :informations, :warning
          showInputMessage: true,
          prompt: 'Choose a value'
        }
      },
    ]
  })

end

exporter = UserExporter.new(@users)
# Optional : Context can be passed to exporter
exporter.context = { current_user: current_user }
stream = exporter.export.to_stream.read

# In ruby file
File.open("export.xlsx", "w") do |tmp|
  tmp.binmode
  tmp.write(stream)
end

# In Controller action
send_data stream, type: 'application/xlsx', filename: "filename.xlsx"

Multiple workbooks export

  user_exporter = UserExporter.new(@user_data)
  product_exporter = ProductExporter.new(@product_data)

  exporter = NtqExcelsior::MultiWorkbookExporter.new([export1, export2])

  # In ruby file
  File.open("export.xlsx", "w") do |tmp|
    tmp.binmode
    tmp.write(stream)
  end
  
  # In Controller action
  send_data stream, type: 'application/xlsx', filename: "filename.xlsx"

Import

class UserImporter < NtqExcelsior::Importer

  model_klass "User"

  primary_key :email

  ## if set to save, the record will not be save automatically after import_line
  ## Errors have to be added to the @errors hash manually
  # autosave false

  structure [{
    header: "Email",
    description: "Email de l'utilisateur a créer ou modifier",
    required: true,
  }, 
  {
    header: "Actif",
    description: "Utilisateur activé",
    required: true,
    values: [
      {
        header: "True",
        description: "Activé",
      }, {
        header: "False",
        description: "Inactivé",
      }
    ]
  }, {
    header: "Prénom",
    required: true,
  }, {
    header: "Nom",
    required: true,
  }]

  sample_file "/import_samples/users.xlsx"

  schema({
    email: 'Email',
    first_name: /Prénom/i,
    last_name: {
      header: /Nom/i,
      required: true
    },
    active: {
      header: /Actif.+/i,
      humanized_header: 'Actif', # (Optional) if provided, will be displayed instead regex in missing headers
      required: false
    }
  })

  def import_line(line, save: true)
    super do |record, line|
      record.email = line[:email]
      record.first_name = line[:first_name]
      record.last_name = line[:last_name]
    end
  end
end

importer = UserImporter.new
importer.file = file
result = importer.import
# { success_count: 2, error_lines: [] }

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ntq_excelsior. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the NtqExcelsior project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.