LINKUWANT COMMON REPLACEMENT FIELD NORMALIZATION STANDARDS ========================================================== PURPOSE ------- These standards define how common replacement fields used in linkUwant email and text templates will eventually be normalized. The common communications generator will be responsible for normalization. COMMON FIELDS ------------- [first_name] [last_name] [company_name] [email] [phone] [address] [city] [state] [domain_name] [submission_id] [date] [time] [date_time] [year] GENERAL NORMALIZATION --------------------- Before a database value is inserted into a communication: 1. Trim leading whitespace. 2. Trim trailing whitespace. 3. Database NULL becomes an empty string. 4. Empty values remain an empty string. 5. Never output literal values such as: NULL null undefined 6. Do not create unnecessary separators around empty values. 7. Preserve legitimate punctuation. 8. Encode/escape values appropriately for the communication type. 9. HTML email output must be safely HTML-escaped where appropriate. 10. SMS/Text output remains plain text. [first_name] ------------ Purpose: Person's first name. Rules: - Trim leading/trailing whitespace. - NULL becomes empty. - Preserve legitimate punctuation. - Do not automatically alter capitalization unless later required. Examples: " James " becomes "James" "Mary-Jane" becomes "Mary-Jane" NULL becomes "" [last_name] ----------- Purpose: Person's last name. Rules: Same general name rules as [first_name]. Examples: " Smith " becomes "Smith" "O'Brien" becomes "O'Brien" NULL becomes "" [company_name] -------------- Purpose: Company or organization. Rules: - Trim leading/trailing whitespace. - Preserve legitimate internal spaces and punctuation. - NULL becomes empty. - Do not substitute a person's name when company is empty. Example: " ABC Plumbing, Inc. " becomes "ABC Plumbing, Inc." [email] ------- Purpose: User/customer email address. Rules: - Trim leading/trailing whitespace. - Email should be validated before use where required. - NULL becomes empty. - Replacement contains the email address only. Example: " james@example.com " becomes "james@example.com" [phone] ------- Purpose: User/customer telephone number. Rules: For recognizable U.S./Canadian 10-digit numbers: 3175551212 becomes (317) 555-1212 317-555-1212 becomes (317) 555-1212 For an 11-digit North American number beginning with 1: 13175551212 becomes (317) 555-1212 Extensions should be preserved when available. Example: 3175551212 ext 45 becomes (317) 555-1212 ext 45 International or uncertain numbers should NOT be reformatted by guessing. Example: +44 20 7946 0958 remains +44 20 7946 0958 NULL becomes empty. [address] --------- Purpose: Combined address1 and address2. [address] is a generated common field. STANDARD RULE: When address1 AND address2 contain values: [address] = address1 + " - " + address2 Example: address1: 123 Main Street address2: Suite 200 [address]: 123 Main Street - Suite 200 When address1 exists and address2 is empty: [address]: 123 Main Street When address1 is empty and address2 exists: [address]: Suite 200 When both are empty: [address]: "" NEVER produce: 123 Main Street - or: - Suite 200 The " - " separator is inserted ONLY when both values exist. [city] ------ Purpose: City. Rules: - Trim whitespace. - NULL becomes empty. - Preserve submitted spelling unless a validated linkUwant city record supplies a standardized value. Examples: " Indianapolis " becomes "Indianapolis" "St. Petersburg" remains "St. Petersburg" [state] ------- Purpose: State, province, or region. Rules: - Trim whitespace. - NULL becomes empty. - Prefer a standardized linkUwant value where available. - Do not automatically convert names to abbreviations unless a specific template requires it. Examples: " Indiana " becomes "Indiana" "IN" remains "IN" [domain_name] ------------- Purpose: Domain associated with the submission. Rules: - Trim whitespace. - Remove protocol when supplied. - Remove leading www. where appropriate. - Remove trailing slash. - Remove URL paths/query strings. - Normalize domain to lowercase. - Prefer validated linkUwant domain data when a domain ID exists. Examples: " ExampleDomain.com " becomes "exampledomain.com" "https://www.ExampleDomain.com/" becomes "exampledomain.com" [submission_id] --------------- Purpose: Unique primary-key ID of the form submission. Rules: - Use actual database-generated submission ID. - Do not add commas. - Do not add decimal formatting. - Never invent a submission ID. - Normally available only after successful database insertion. Example: Database ID: 1254 [submission_id]: 1254 [date] ------ Standard display: August 15, 2026 Example database timestamp: 2026-08-15 08:42:17 Result: August 15, 2026 [time] ------ Standard display: 8:42 AM Rules: - 12-hour display. - Include AM/PM. - No leading zero on hour. Examples: 08:42:17 becomes 8:42 AM 15:07:00 becomes 3:07 PM [date_time] ----------- Standard display: August 15, 2026 at 8:42 AM Example: 2026-08-15 08:42:17 becomes August 15, 2026 at 8:42 AM DATE/TIME SOURCE ---------------- Communication dates/times should be generated from actual stored timestamps. The application's configured timezone controls display formatting. Do NOT silently replace a missing database timestamp with the current date/time unless that particular communication explicitly requires the current time. Invalid or NULL timestamps become empty replacement values. [year] ----------- Standard display: 2026 YEAR SOURCE ---------------- Communication year from current date and time EST. EMPTY FIELD HANDLING -------------------- Missing replacement values normally resolve to: "" Do NOT leave unresolved common fields in a completed communication. Incorrect: Company: [company_name] Phone: NULL Acceptable: Company: Phone: A future generator may optionally support removing an entire line when its replacement field is empty. DATABASE FIELD NAMES -------------------- Friendly template fields do NOT have to match database column names. Example: Database: do_first_name Template: [first_name] The future communications generator maps the two. FORM-SPECIFIC FIELDS -------------------- Individual forms may define additional fields. Example Domain Offer fields: [domain_id] [user_id] [offer_amount] [message] [created] ADMIN ACTION FIELDS ------------------- Administrator templates may define generated URLs such as: [view_offer_url] [view_domain_history_url] [edit_offer_url] [mark_junk_url] [respond_url] These URLs are generated by future application logic. They are NOT raw database values. ALL protected administrator links require authenticated administrator login. IMPORTANT --------- Templates contain content and replacement fields only. Normalization, database lookup, security, recipient selection, sending, logging, and authentication belong to future common application code.