diff --git a/bullet_train-api/app/helpers/api/open_api_helper.rb b/bullet_train-api/app/helpers/api/open_api_helper.rb index e1107a468..5efc2e3df 100644 --- a/bullet_train-api/app/helpers/api/open_api_helper.rb +++ b/bullet_train-api/app/helpers/api/open_api_helper.rb @@ -38,8 +38,8 @@ def automatic_paths_for(model, parent, except: []) end if custom_output - merge = deep_merge(YAML.load(output), YAML.load(custom_output)).to_yaml.html_safe - # YAML.load escapes emojis https://github.com/ruby/psych/issues/371 + merge = deep_merge(YAML.safe_load(output), YAML.safe_load(custom_output)).to_yaml.html_safe + # YAML.safe_load escapes emojis https://github.com/ruby/psych/issues/371 # Next line returns emojis back and removes yaml garbage output = merge.gsub("---", "").gsub(/\\u[\da-f]{8}/i) { |m| [m[-8..].to_i(16)].pack("U") } end diff --git a/bullet_train-api/bullet_train-api.gemspec b/bullet_train-api/bullet_train-api.gemspec index 241010288..81295e3a9 100644 --- a/bullet_train-api/bullet_train-api.gemspec +++ b/bullet_train-api/bullet_train-api.gemspec @@ -10,6 +10,15 @@ Gem::Specification.new do |spec| spec.description = spec.summary spec.license = "MIT" + # TODO: Remove some time after 1.6.27 + spec.post_install_message = " + Bullet Train is switching to separate translations for API documentation. + To automatically update existing translations, run once: + + bundle exec rake bullet_train:api:create_translations + + " + # Prevent pushing this gem to RubyGems.org. To allow pushes either set the "allowed_push_host" # to allow pushing to a single host or delete this section to allow pushing to any host. # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'" diff --git a/bullet_train-api/config/locales/en/platform/access_tokens.en.yml b/bullet_train-api/config/locales/en/platform/access_tokens.en.yml index a0774ef7f..b1b635471 100644 --- a/bullet_train-api/config/locales/en/platform/access_tokens.en.yml +++ b/bullet_train-api/config/locales/en/platform/access_tokens.en.yml @@ -20,38 +20,56 @@ en: destroy: Are you sure you want to remove %{access_token_name}? This will break any active integrations using this token and can't be undone. fields: &fields id: - heading: Access Token ID + heading: &id Access Token ID + api_title: *id + api_description: *id application_id: - heading: Application ID + heading: &application_id Application ID + api_title: *application_id + api_description: *application_id token: _: &token Token label: *token heading: *token + api_title: *token + api_description: *token expires_in: _: &expires_in Expires In label: *expires_in heading: *expires_in + api_title: *expires_in + api_description: *expires_in scopes: _: &scopes Scopes label: *scopes heading: *scopes + api_title: *scopes + api_description: *scopes last_used_at: _: &last_used_at Last Used At label: *last_used_at heading: *last_used_at + api_title: *last_used_at + api_description: *last_used_at description: _: &description Description label: *description heading: *description + api_title: *description + api_description: *description # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Created label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated label: *updated_at heading: *updated_at + api_title: *updated_at + api_description: *updated_at api: collection_actions: "Collection Actions for Access Tokens" index: "List Access Tokens" diff --git a/bullet_train-api/config/locales/en/platform/applications.en.yml b/bullet_train-api/config/locales/en/platform/applications.en.yml index e1ffe46df..adb12e7a5 100644 --- a/bullet_train-api/config/locales/en/platform/applications.en.yml +++ b/bullet_train-api/config/locales/en/platform/applications.en.yml @@ -24,32 +24,46 @@ en: name: _: &name Name label: *name - heading: Application Name + heading: &application_name Application Name + api_title: *application_name + api_description: *application_name redirect_uri: _: &redirect_uri Redirect URI label: *redirect_uri heading: *redirect_uri + api_title: *redirect_uri + api_description: *redirect_uri help: This is only required if you're building an OAuth2-powered integration for other users. uid: - heading: Client UID + heading: &uid Client UID + api_title: *uid + api_description: *uid secret: - heading: Client Secret + heading: &secret Client Secret + api_title: *secret + api_description: *secret label_string: - heading: Application Name + heading: *application_name + api_title: *application_name + api_description: *application_name # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Added label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated label: *updated_at heading: *updated_at + api_title: *updated_at + api_description: *updated_at index: section: "%{teams_possessive} Platform Applications" contexts: diff --git a/bullet_train-api/lib/tasks/bullet_train/api_tasks.rake b/bullet_train-api/lib/tasks/bullet_train/api_tasks.rake index 9021e4700..ce1786705 100644 --- a/bullet_train-api/lib/tasks/bullet_train/api_tasks.rake +++ b/bullet_train-api/lib/tasks/bullet_train/api_tasks.rake @@ -146,5 +146,103 @@ namespace :bullet_train do ) end end + + desc "Create `api_title` and `api_description` translations" + task create_translations: :environment do + # Define the root of the locales directory + locales_root = Rails.root.join("config", "locales").to_s + + # Define the backup directory + backup_dir = Rails.root.join("tmp", "locales_backup") + FileUtils.mkdir_p(backup_dir) unless Dir.exist?(backup_dir) + + original_files = Dir.glob("#{locales_root}/**/*.yml") + differing_files_count = 0 + + original_files.each do |file| + puts "Processing #{file}..." + + lines = File.readlines(file) + new_content = [] + inside_fields = false + current_field = nil + fields_indentation = 4 + api_title_exists = false + api_description_exists = false + + # Read the entire file as a string + lines.each_with_index do |line, index| + # fields are always under locale:model: + if line.start_with?("#{" " * fields_indentation}fields:") + inside_fields = true + new_content << line + next + end + + if inside_fields + current_indentation = line.index(/\S/) || 0 + if current_indentation <= fields_indentation + # We've exited the fields block + inside_fields = false + current_field = nil + elsif current_indentation == fields_indentation + 2 + # We're on a line with a field name + current_field = line.strip.split(":").first + + api_title_exists = false + api_description_exists = false + + n = 1 + until index + n >= lines.length || (lines[index + n].index(/\S/) || 0) <= fields_indentation + if lines[index + n].strip.start_with?("api_title:") + api_title_exists = true + elsif lines[index + n].strip.start_with?("api_description:") + api_description_exists = true + end + n += 1 + end + + elsif current_field && line.strip.start_with?("heading:") + heading_value = line.split(":").last&.strip + indent = " " * current_indentation + + if heading_value&.start_with?("&", "*") + new_content << line + else + heading_value = "&#{current_field} #{heading_value}" + new_content << "#{indent}heading: #{heading_value}\n" + end + + field_key = heading_value[1..]&.split(" ")&.first + new_content << "#{indent}api_title: *#{field_key}\n" unless api_title_exists + new_content << "#{indent}api_description: *#{field_key}\n" unless api_description_exists + + next + end + end + + new_content << line + end + + # Only write to file if there are changes + unless lines.join == new_content.join + differing_files_count += 1 + + # Compute the relative path manually + relative_path = file.sub(/^#{Regexp.escape(locales_root)}\/?/, "") + + backup_path = File.join(backup_dir, relative_path) + FileUtils.mkdir_p(File.dirname(backup_path)) + FileUtils.cp(file, backup_path) + puts "↳ Updating, backup created: #{backup_path}" + + # Write the updated data back to the file + File.write(file, new_content.join) + end + end + + puts "---" + puts "Total files updated: #{differing_files_count}/#{original_files.size}" + end end end diff --git a/bullet_train-integrations-stripe/config/locales/en/integrations/stripe_installations.en.yml b/bullet_train-integrations-stripe/config/locales/en/integrations/stripe_installations.en.yml index b015ae720..6baeede6e 100644 --- a/bullet_train-integrations-stripe/config/locales/en/integrations/stripe_installations.en.yml +++ b/bullet_train-integrations-stripe/config/locales/en/integrations/stripe_installations.en.yml @@ -24,16 +24,22 @@ en: _: &name Name label: *name heading: *name + api_title: *name + api_description: *name # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Added label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated label: *updated_at heading: *updated_at + api_title: *updated_at + api_description: *updated_at list: section: "Stripe Installations" contexts: diff --git a/bullet_train-integrations-stripe/config/locales/en/oauth/stripe_accounts.en.yml b/bullet_train-integrations-stripe/config/locales/en/oauth/stripe_accounts.en.yml index d762165d1..9f6a7f6b5 100644 --- a/bullet_train-integrations-stripe/config/locales/en/oauth/stripe_accounts.en.yml +++ b/bullet_train-integrations-stripe/config/locales/en/oauth/stripe_accounts.en.yml @@ -23,10 +23,14 @@ en: name: &name Name label: *name heading: *name + api_title: *name + api_description: *name # 🚅 super scaffolding will insert new fields above this line. created_at: name: &created_at Connected heading: *created_at + api_title: *created_at + api_description: *created_at index: section: '%{users_possessive} Stripe Accounts' contexts: diff --git a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/deliveries.en.yml b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/deliveries.en.yml index 004d1b51d..e6bb6fc01 100644 --- a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/deliveries.en.yml +++ b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/deliveries.en.yml @@ -24,11 +24,15 @@ en: _: &id Delivery ID label: *id heading: *id + api_title: *id + api_description: *id event_id: &event _: &event_id Event label: *event_id heading: *event_id + api_title: *event_id + api_description: *event_id placeholder: Select a Event event: *event @@ -36,24 +40,34 @@ en: _: &endpoint_url Endpoint URL label: *endpoint_url heading: *endpoint_url + api_title: *endpoint_url + api_description: *endpoint_url delivered_at: _: &delivered_at Delivered At label: *delivered_at heading: *delivered_at + api_title: *delivered_at + api_description: *delivered_at status: - heading: Status + heading: &status Status + api_title: *status + api_description: *status # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Issued At label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated label: *updated_at heading: *updated_at + api_title: *updated_at + api_description: *updated_at api: endpoint_id: Absolutely Abstract Endpoint ID collection_actions: "Collection Actions for Deliveries" diff --git a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/delivery_attempts.en.yml b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/delivery_attempts.en.yml index 2cbae9dbb..b036865b4 100644 --- a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/delivery_attempts.en.yml +++ b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/delivery_attempts.en.yml @@ -24,44 +24,62 @@ en: _: &id Delivery Attempt ID label: *id heading: *id + api_title: *id + api_description: *id response_code: _: &response_code Response Code label: *response_code heading: *response_code + api_title: *response_code + api_description: *response_code response_body: _: &response_body Response Body label: *response_body heading: *response_body + api_title: *response_body + api_description: *response_body response_message: _: &response_message Response Message label: *response_message heading: *response_message + api_title: *response_message + api_description: *response_message error_message: _: &error_message Error Message label: *error_message heading: *error_message + api_title: *error_message + api_description: *error_message attempt_number: _: &attempt_number Attempt Number label: *attempt_number heading: *attempt_number + api_title: *attempt_number + api_description: *attempt_number status: - heading: Status + heading: &status Status + api_title: *status + api_description: *status # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Attempted At label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated label: *updated_at heading: *updated_at + api_title: *updated_at + api_description: *updated_at api: delivery_id: Absolutely Abstract Delivery ID collection_actions: "Collection Actions for Delivery Attempts" diff --git a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/endpoints.en.yml b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/endpoints.en.yml index 73a70d7d6..dca93f42d 100644 --- a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/endpoints.en.yml +++ b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/endpoints.en.yml @@ -23,26 +23,36 @@ en: _: &id Endpoint ID label: *id heading: *id + api_title: *id + api_description: *id team_id: _: &team_id Team ID label: *team_id heading: *team_id + api_title: *team_id + api_description: *team_id name: _: &name Name label: *name heading: *name + api_title: *name + api_description: *name url: _: &url URL label: *url heading: *url + api_title: *url + api_description: *url api_version: _: &api_version API Version label: *api_version heading: *api_version + api_title: *api_version + api_description: *api_version options: 1: V1 @@ -50,6 +60,8 @@ en: _: &event_type_ids Event Types label: *event_type_ids heading: *event_type_ids + api_title: *event_type_ids + api_description: *event_type_ids all: All Events event_types: *event_types @@ -57,6 +69,8 @@ en: _: &scaffolding_absolutely_abstract_creative_concept_id Within Creative Concept label: *scaffolding_absolutely_abstract_creative_concept_id heading: *scaffolding_absolutely_abstract_creative_concept_id + api_title: *scaffolding_absolutely_abstract_creative_concept_id + api_description: *scaffolding_absolutely_abstract_creative_concept_id scaffolding_absolutely_abstract_creative_concept: *scaffolding_absolutely_abstract_creative_concept @@ -65,10 +79,14 @@ en: _: &created_at Added label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated label: *updated_at heading: *updated_at + api_title: *updated_at + api_description: *updated_at api: team_id: Absolutely Abstract Team ID collection_actions: "Collection Actions for Endpoints" diff --git a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/events.en.yml b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/events.en.yml index ec3f21312..d309691a0 100644 --- a/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/events.en.yml +++ b/bullet_train-outgoing_webhooks/config/locales/en/webhooks/outgoing/events.en.yml @@ -6,16 +6,22 @@ en: _: &id Event ID label: *id heading: *id + api_title: *id + api_description: *id team_id: _: &team_id Team ID label: *team_id heading: *team_id + api_title: *team_id + api_description: *team_id event_type_id: &event_type_id _: &event_type Event Type label: *event_type heading: *event_type + api_title: *event_type + api_description: *event_type event_type: *event_type_id @@ -23,38 +29,54 @@ en: _: &subject_id Subject ID label: *subject_id heading: *subject_id + api_title: *subject_id + api_description: *subject_id subject_type: _: &subject_type Subject Type label: *subject_type heading: *subject_type + api_title: *subject_type + api_description: *subject_type payload: _: &payload Payload label: *payload heading: *payload + api_title: *payload + api_description: *payload uuid: _: &uuid UUID label: *uuid heading: *uuid + api_title: *uuid + api_description: *uuid short_uuid: _: &short_uuid Short UUID label: *short_uuid heading: *short_uuid + api_title: *short_uuid + api_description: *short_uuid event_type_name: _: &event_type_name Event Type Name label: *event_type_name heading: *event_type_name + api_title: *event_type_name + api_description: *event_type_name data: _: &data Object Data label: *data heading: *data + api_title: *data + api_description: *data created_at: _: &created_at Happened At label: *created_at heading: *created_at + api_title: *created_at + api_description: *created_at diff --git a/bullet_train-super_scaffolding/lib/scaffolding/transformer.rb b/bullet_train-super_scaffolding/lib/scaffolding/transformer.rb index 2ee0c5430..59865aa93 100644 --- a/bullet_train-super_scaffolding/lib/scaffolding/transformer.rb +++ b/bullet_train-super_scaffolding/lib/scaffolding/transformer.rb @@ -895,6 +895,8 @@ def valid_#{attribute.collection_name} _: &#{attribute.name} #{attribute.title_case} label: *#{attribute.name} heading: *#{attribute.name} + api_title: *#{attribute.name} + api_description: *#{attribute.name} <% if attribute.type == "super_select" %> <% if attribute.is_required? %> diff --git a/bullet_train/config/locales/en/addresses.en.yml b/bullet_train/config/locales/en/addresses.en.yml index ca4b8c058..548f7b430 100644 --- a/bullet_train/config/locales/en/addresses.en.yml +++ b/bullet_train/config/locales/en/addresses.en.yml @@ -7,23 +7,33 @@ en: _: &address_one Address label: *address_one heading: *address_one + api_title: *address_one + api_description: *address_one address_two: _: &address_two Address cont. label: *address_two heading: *address_two + api_title: *address_two + api_description: *address_two city: _: &city City label: *city heading: *city + api_title: *city + api_description: *city region_id: ®ion _: ®ion_id State / Province / Region label: *region_id heading: *region_id + api_title: *region_id + api_description: *region_id region: *region region_name: _: ®ion_name Region name label: *region_name heading: *region_name + api_title: *region_name + api_description: *region_name admin_divisions: states: State provinces_territories: Province or Territory @@ -40,12 +50,18 @@ en: _: &country_id Country label: *country_id heading: *country_id + api_title: *country_id + api_description: *country_id country: *country postal_code: _: &postal_code Postal code label: *postal_code heading: *postal_code + api_title: *postal_code + api_description: *postal_code zip_code: _: &zip_code Zip code label: *zip_code heading: *zip_code + api_title: *zip_code + api_description: *zip_code diff --git a/bullet_train/config/locales/en/invitations.en.yml b/bullet_train/config/locales/en/invitations.en.yml index e2de971b0..53a10a639 100644 --- a/bullet_train/config/locales/en/invitations.en.yml +++ b/bullet_train/config/locales/en/invitations.en.yml @@ -17,34 +17,50 @@ en: _: &id Invitation ID label: *id heading: *id + api_title: *id + api_description: *id email: _: &email Email Address label: *email heading: *email + api_title: *email + api_description: *email uuid: name: &uuid Invitation UUID label: *uuid heading: *uuid + api_title: *uuid + api_description: *uuid from_membership_id: name: &from_membership_id Who sent ID label: *from_membership_id heading: *from_membership_id + api_title: *from_membership_id + api_description: *from_membership_id team_id: name: &team_id Team ID label: *team_id heading: *team_id + api_title: *team_id + api_description: *team_id roles: &role_ids name: &roles Special Privileges label: *roles heading: *roles + api_title: *roles + api_description: *roles role_ids: *role_ids # 🚅 super scaffolding will insert new fields above this line. created_at: name: &created_at Sent heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: name: &updated_at Updated heading: *updated_at + api_title: *updated_at + api_description: *updated_at index: section: "Invitations for %{team_name}" header: Team Member Invitations diff --git a/bullet_train/config/locales/en/memberships.en.yml b/bullet_train/config/locales/en/memberships.en.yml index bd1ab8539..a76e71771 100644 --- a/bullet_train/config/locales/en/memberships.en.yml +++ b/bullet_train/config/locales/en/memberships.en.yml @@ -26,50 +26,78 @@ en: _: &id Membership ID label: *id heading: *id + api_title: *id + api_description: *id user_id: name: &user_id User ID heading: *user_id + api_title: *user_id + api_description: *user_id team_id: name: &team_id Team ID heading: *team_id + api_title: *team_id + api_description: *team_id invitation_id: name: &invitation_id Invitation ID heading: *invitation_id + api_title: *invitation_id + api_description: *invitation_id name: name: &name Full Name heading: *name + api_title: *name + api_description: *name user_first_name: name: &user_first_name First Name label: *user_first_name heading: *user_first_name + api_title: *user_first_name + api_description: *user_first_name user_last_name: name: &user_last_name Last Name label: *user_last_name heading: *user_last_name + api_title: *user_last_name + api_description: *user_last_name user_profile_photo_id: name: &user_profile_photo_id Profile Photo label: *user_profile_photo_id heading: *user_profile_photo_id + api_title: *user_profile_photo_id + api_description: *user_profile_photo_id user_profile_photo: name: &user_profile_photo Profile Photo label: *user_profile_photo - heading: *user_profile_photo_id + heading: *user_profile_photo + api_title: *user_profile_photo + api_description: *user_profile_photo user_email: name: &user_email User Email heading: *user_email + api_title: *user_email + api_description: *user_email added_by_id: name: &added_by_id Added by User ID heading: *added_by_id + api_title: *added_by_id + api_description: *added_by_id platform_agent_of_id: name: &platform_agent_of_id Platform Agent of ID heading: *platform_agent_of_id + api_title: *platform_agent_of_id + api_description: *platform_agent_of_id platform_agent: name: &platform_agent Platform Agent heading: *platform_agent + api_title: *platform_agent + api_description: *platform_agent role_ids: name: &roles Special Privileges label: *roles heading: *roles + api_title: *roles + api_description: *roles options: default: label: Viewer @@ -84,9 +112,13 @@ en: created_at: _: &created_at Created At heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated At heading: *updated_at + api_title: *updated_at + api_description: *updated_at index: section: "%{team_name} Team Members" contexts: diff --git a/bullet_train/config/locales/en/teams.en.yml b/bullet_train/config/locales/en/teams.en.yml index 68b0addc1..39ecfec86 100644 --- a/bullet_train/config/locales/en/teams.en.yml +++ b/bullet_train/config/locales/en/teams.en.yml @@ -53,25 +53,37 @@ en: _: &id Team ID label: *id heading: *id + api_title: *id + api_description: *id name: _: &name Team Name label: *name heading: Team + api_title: *name + api_description: *name time_zone: _: &time_zone Primary Time Zone label: "Primary Time Zone" heading: *time_zone + api_title: *time_zone + api_description: *time_zone locale: _: &locale Language label: "Primary Language" heading: *locale + api_title: *locale + api_description: *locale # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Signed Up At heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated At heading: *updated_at + api_title: *updated_at + api_description: *updated_at _: &self name: label: Your Team Name diff --git a/bullet_train/config/locales/en/users.en.yml b/bullet_train/config/locales/en/users.en.yml index c83954cbb..6d7779ffc 100644 --- a/bullet_train/config/locales/en/users.en.yml +++ b/bullet_train/config/locales/en/users.en.yml @@ -38,32 +38,46 @@ en: _: &id Team ID label: *id heading: *id + api_title: *id + api_description: *id name: heading: Name first_name: _: &first_name First Name label: *first_name heading: *first_name + api_title: *first_name + api_description: *first_name last_name: _: &last_name Last Name label: *last_name heading: *last_name + api_title: *last_name + api_description: *last_name email: _: &email Email Address label: *email heading: *email + api_title: *email + api_description: *email time_zone: _: &time_zone Your Time Zone label: *time_zone heading: *time_zone + api_title: *time_zone + api_description: *time_zone profile_photo_id: _: &profile_photo_id Profile Photo label: *profile_photo_id heading: *profile_photo_id + api_title: *profile_photo_id + api_description: *profile_photo_id profile_photo: _: &profile_photo Profile Photo label: *profile_photo heading: *profile_photo + api_title: *profile_photo + api_description: *profile_photo current_password: label: Current Password password: @@ -76,18 +90,26 @@ en: _: &otp_attempt Your Verification Code label: *otp_attempt heading: *otp_attempt + api_title: *otp_attempt + api_description: *otp_attempt locale: _: &locale Language label: *locale heading: *locale + api_title: *locale + api_description: *locale help: By default the interface language will adjust based on each team's language setting, but you can set a global personal preference for your account here. # 🚅 super scaffolding will insert new fields above this line. created_at: _: &created_at Signed Up At heading: *created_at + api_title: *created_at + api_description: *created_at updated_at: _: &updated_at Updated At heading: *updated_at + api_title: *updated_at + api_description: *updated_at # this is how we define customizations to fields for a specific namespace. _: &self email: diff --git a/bullet_train/docs/field-partials.md b/bullet_train/docs/field-partials.md index a6c98563e..28408ef41 100644 --- a/bullet_train/docs/field-partials.md +++ b/bullet_train/docs/field-partials.md @@ -96,15 +96,19 @@ text_field_value: name: &text_field_value Text Field Value label: *text_field_value heading: *text_field_value + api_title: *text_field_value + api_description: *text_field_value ``` -This might look redundant at first glance, as you can see that by default the same label ("Text Field Value") is being used for both the form field label (`label`) and the heading (`heading`) of the show view and table view. It's also used when the field is referred to in a validation error message. However, having these three values defined separately gives us the flexibility of defining much more user-friendly labels in the context of a form field. In my own applications, I'll frequently configure these form field labels to be much more verbose questions (in an attempt to improve the UX), but still use the shorter label as a column header on the table view and the show view: +This might look redundant at first glance, as you can see that by default the same label ("Text Field Value") is being used for both the form field label (`label`) and the heading (`heading`) of the show view and table view, and in API `api_title` and `api_descriptions` are used for documentation purposes. It's also used when the field is referred to in a validation error message. However, having these three values defined separately gives us the flexibility of defining much more user-friendly labels in the context of a form field. In my own applications, I'll frequently configure these form field labels to be much more verbose questions (in an attempt to improve the UX), but still use the shorter label as a column header on the table view and the show view: ```yaml text_field_value: name: &text_field_value Text Field Value label: "What should the value of this text field be?" heading: *text_field_value + api_title: *text_field_value + api_description: *text_field_value ``` You can also configure some placeholder text (displayed in the field when in an empty state) or some inline help text (to be presented to users under the form field) like so: @@ -114,6 +118,8 @@ text_field_value: name: &text_field_value Text Field Value label: "What should the value of this text field be?" heading: *text_field_value + api_title: *text_field_value + api_description: *text_field_value placeholder: "Type your response here" help: "The value can be anything you want it to be!" ```