Mycowriter Gem Documentation

Mycowriter is a Rails engine that provides intelligent taxonomic autocomplete for genus and species names, powered by MycoBank data.

Installation

1. Add to your Gemfile

gem 'mycowriter'

2. Install the gem

bundle install
rails generate mycowriter:install

3. Set up your database

Mycowriter expects an mb_lists table with MycoBank taxonomic data:

create_table "mb_lists" do |t|
  t.string "taxon_name"
  t.string "rank_name"
  t.timestamps
end

4. Use in your text fields

<div data-controller="inline-autocomplete"
     data-inline-autocomplete-genus-url-value="<%= mycowriter.genera_autocomplete_path %>"
     data-inline-autocomplete-species-url-value="<%= mycowriter.species_autocomplete_path %>"
     data-inline-autocomplete-min-value="4">

  <%= f.text_area :body,
      data: {
        inline_autocomplete_target: "textarea",
        action: "input->inline-autocomplete#onInput keydown->inline-autocomplete#onKeydown"
      },
      class: "form-textarea" %>

  <div data-inline-autocomplete-target="dropdown" class="hidden"></div>
</div>

Features

🔍 Real-time Autocomplete

Instant suggestions as users type genus and species names

✍️ Inline Text Autocomplete

Autocomplete at cursor position in textareas while writing

⚡ Debounced Search

150ms debounce for optimal performance

🎯 Two-Stage Completion

Select genus first, then get species suggestions for that genus

📊 MycoBank Data

Integrated with MycoBank's comprehensive taxonomic database

🔧 Configurable

Customizable minimum characters, case sensitivity, and results limit

Configuration

Customize Mycowriter in config/initializers/mycowriter.rb:

Mycowriter.configure do |config|
  # Minimum characters before autocomplete triggers (default: 3)
  config.min_characters = 3

  # Case-sensitive search (default: false)
  config.case_sensitive = false

  # Maximum results to return (default: 20)
  config.results_limit = 20
end

Usage Examples

Basic Usage in Forms

<div data-controller="inline-autocomplete"
     data-inline-autocomplete-genus-url-value="<%= mycowriter.genera_autocomplete_path %>"
     data-inline-autocomplete-species-url-value="<%= mycowriter.species_autocomplete_path %>"
     data-inline-autocomplete-min-value="4">

  <%= f.text_area :body,
      data: {
        inline_autocomplete_target: "textarea",
        action: "input->inline-autocomplete#onInput keydown->inline-autocomplete#onKeydown"
      },
      class: "form-textarea w-full h-48 p-4 border rounded",
      placeholder: "Start typing a genus name (capitalized, 4+ characters)..." %>

  <div data-inline-autocomplete-target="dropdown" class="hidden"></div>
</div>

How It Works

User types a capitalized word with 4+ characters (e.g., "Agar")
Genus dropdown appears below cursor position
User clicks a genus (e.g., "Agaricus")
Genus is inserted into text at cursor
User continues typing species name (e.g., "campes")
Species dropdown shows matches for the selected genus
User clicks species (e.g., "campestris")
Complete binomial "Agaricus campestris" appears in text as plain text

📝 Output Format

The gem inserts plain text without HTML formatting. This gives you flexibility to format binomial names as needed in your application.

To add italics: Wrap inserted text with <em> tags in your JavaScript, or apply CSS styling to your textarea.

Customizing Minimum Characters

<!-- Use 3 characters instead of default 4 -->
<div data-controller="inline-autocomplete"
     data-inline-autocomplete-genus-url-value="<%= mycowriter.genera_autocomplete_path %>"
     data-inline-autocomplete-species-url-value="<%= mycowriter.species_autocomplete_path %>"
     data-inline-autocomplete-min-value="3">
  <!-- textarea here -->
</div>