Merge pull request #32 from adafruit/tylerdcooper-patch-1

docs: text template update

Author: lorennorman

app/blocks/text/template.js

@@ -6,79 +6,211 @@ export default {
   colour: 180,
   inputsInline: true,
   description: `
-    Render a text template.
-
     ::: v-pre
-    Special forms surrounded by {{ curly_braces }}
-    will be replaced with their current value during the action run.
-
-    These templates use the Liquid templating language, from Shopify, and many
-    helpful functions come built-in. See the
-    [Liquid Documentation](https://shopify.github.io/liquid/basics/introduction/)
-    to learn more.
-
-    ### Template Variables:
-
-    \`{{ variables.var_name }}\` - get the value of a variable you have defined
-    with name 'var_name'
-
-    \`{{ vars.var_name }}\` - shorthand for same as above
-
-    \`{{ variables['var name'] }}\` - get the value of a variable you have
-    defined with name 'var name' (allows spaces in variable names
-
-    \`{{ vars['var name'] }}\` - shorthand for same as above
-
-    \`{{ user.name }}\` - your user's name
-
-    \`{{ user.username }}\` - your user's username
-
-    \`{{ feeds['group_key.feed_key'].name }}\` - access a feed with key
-    'group_key.feed_key' and get its name
-
-    \`{{ feeds[...].key }}\` - ...get its key
-
-    \`{{ feeds[...].value }}\` - ...get its last value
+    Create dynamic, personalized messages by combining static text with live data from your IoT system. Perfect for intelligent notifications like "Hello {{ user.name }}, your temperature sensor read {{ feeds['sensors.temperature'].value }}°F" or automated reports that include current sensor values, user information, and real-time data. Uses the powerful Liquid templating language for advanced formatting and logic.
+    
+    ## What is a Text Template?
+    
+    Think of a text template like a form letter where you leave blanks to fill in with specific information. Instead of writing "Dear _____", you write "Dear {{ user.name }}" and the system automatically fills in the actual name when the message is sent.
+    
+    ## How It Works
+    
+    This block renders (processes) a text template, replacing special placeholders with actual values.
+    Anything surrounded by {{ double curly braces }} gets replaced with real data when your action runs.
+    
+    For example:
+    - Template: "Hello {{ user.name }}!"
+    - Becomes: "Hello John!"
+    
+    These templates use the Liquid templating language from Shopify, which includes many helpful built-in functions.
+    Learn more: [Liquid Documentation](https://shopify.github.io/liquid/basics/introduction/)
+    
+    ## Template Variables Reference
+    
+    ### User Information
+    - \`{{ user.name }}\` - Your full name (e.g., "John Smith")
+    - \`{{ user.username }}\` - Your username (e.g., "jsmith123")
+    
+    ### Custom Variables
+    - \`{{ variables.var_name }}\` - Get value of variable named 'var_name'
+    - \`{{ vars.var_name }}\` - Shorthand version (same as above)
+    - \`{{ variables['var name'] }}\` - Use brackets for names with spaces
+    - \`{{ vars['my special var'] }}\` - Shorthand with spaces
+    
+    ### Feed Data (Sensors & Devices)
+    - \`{{ feeds['group_key.feed_key'].value }}\` - Current value from a feed
+    - \`{{ feeds['group_key.feed_key'].name }}\` - Feed's display name
+    - \`{{ feeds['group_key.feed_key'].key }}\` - Feed's unique key
+    - \`{{ feeds['group_key.feed_key'].updated_at }}\` - Last update timestamp
+    
+    ## Real-World IoT Examples
+    
+    ### 🌡️ Temperature Alerts
+    **Basic Alert:**
+    \`"Temperature Alert: {{ feeds['sensors.temp'].value }}°F detected!"\`
+    Output: "Temperature Alert: 85°F detected!"
+    
+    **Detailed Alert with Location:**
+    \`"⚠️ HIGH TEMP WARNING
+    Location: {{ feeds['sensors.temp'].name }}
+    Current: {{ feeds['sensors.temp'].value }}°F
+    Time: {{ feeds['sensors.temp'].updated_at }}
+    Please check your {{ vars.device_location }} immediately!"\`
+    
+    ### 📊 Daily Status Reports
+    **Simple Report:**
+    \`"Daily Report for {{ user.name }}:
+    • Temperature: {{ feeds['home.temp'].value }}°F
+    • Humidity: {{ feeds['home.humidity'].value }}%
+    • Battery: {{ vars.battery_level }}%"\`
+    
+    **Comprehensive Home Report:**
+    \`"Good morning {{ user.name }}! Here's your home status:
+    
+    🌡️ Climate Control:
+    - Living Room: {{ feeds['climate.living_temp'].value }}°F
+    - Bedroom: {{ feeds['climate.bedroom_temp'].value }}°F
+    - Humidity: {{ feeds['climate.humidity'].value }}%
+    
+    🔋 Device Status:
+    - Door Sensor Battery: {{ feeds['security.door_battery'].value }}%
+    - Motion Detector: {{ vars.motion_status }}
+    - Last Activity: {{ feeds['security.last_motion'].updated_at }}
+    
+    Have a great day!"\`
+    
+    ### 🚪 Security Notifications
+    **Door Alert:**
+    \`"🚪 {{ feeds['security.front_door'].name }} is {{ feeds['security.front_door'].value }} 
+    Time: {{ feeds['security.front_door'].updated_at }}
+    User: {{ user.name }}"\`
+    
+    ### 🌱 Garden Monitoring
+    **Watering Reminder:**
+    \`"Hey {{ user.name }}, your {{ vars.plant_name }} needs attention!
+    Soil Moisture: {{ feeds['garden.moisture'].value }}%
+    Last Watered: {{ vars.last_water_date }}
+    Recommendation: Water {{ vars.water_amount }}ml"\`
+    
+    ### 🔔 Smart Doorbell Messages
+    **Visitor Notification:**
+    \`"{{ user.name }}, someone is at your door!
+    Camera: {{ feeds['doorbell.camera'].name }}
+    Motion Level: {{ feeds['doorbell.motion'].value }}
+    Time: {{ feeds['doorbell.motion'].updated_at }}"\`
+    
+    ## Advanced Liquid Features
+    
+    ### Conditional Logic
+    Use if/else statements for smart messages:
+    \`"{% if feeds['sensors.temp'].value > 80 %}
+      🔥 It's hot! {{ feeds['sensors.temp'].value }}°F
+    {% else %}
+      ❄️ Nice and cool: {{ feeds['sensors.temp'].value }}°F
+    {% endif %}"\`
+    
+    ### Formatting Numbers
+    Round numbers or add decimal places:
+    \`"Temperature: {{ feeds['sensors.temp'].value | round: 1 }}°F"
+    "Battery: {{ vars.battery | round }}%"\`
+    
+    ### Date Formatting
+    Format timestamps for readability:
+    \`"Last updated: {{ feeds['sensor.temp'].updated_at | date: '%B %d at %I:%M %p' }}"\`
+    Output: "Last updated: January 15 at 03:45 PM"
+    
+    ### Math Operations
+    Perform calculations in templates:
+    \`"Temperature in Celsius: {{ feeds['sensors.temp'].value | minus: 32 | times: 5 | divided_by: 9 | round: 1 }}°C"\`
+    
+    ## Common Patterns & Tips
+    
+    ### 1. Fallback Values
+    Provide defaults when data might be missing:
+    \`"Temperature: {{ feeds['sensors.temp'].value | default: 'No reading' }}"\`
+    
+    ### 2. Multiple Feed Access
+    Combine data from multiple sources:
+    \`"Indoor: {{ feeds['home.inside_temp'].value }}°F
+    Outdoor: {{ feeds['home.outside_temp'].value }}°F
+    Difference: {{ feeds['home.inside_temp'].value | minus: feeds['home.outside_temp'].value }}°F"\`
+    
+    ### 3. Status Indicators
+    Use emoji based on values (keep in mind emoji will not work with displays):
+    \`"Battery: {{ vars.battery_level }}% 
+    {% if vars.battery_level < 20 %}🔴{% elsif vars.battery_level < 50 %}🟡{% else %}🟢{% endif %}"\`
+    
+    ### 4. Time-Based Greetings
+    \`"{% assign hour = 'now' | date: '%H' | plus: 0 %}
+    {% if hour < 12 %}Good morning{% elsif hour < 17 %}Good afternoon{% else %}Good evening{% endif %}, {{ user.name }}!"\`
+    
+    ## Troubleshooting Common Issues
+    
+    ### Problem: Variable shows as blank
+    **Solution:** Check that:
+    - Variable name is spelled correctly (case-sensitive!)
+    - Feed key matches exactly (including group.feed format)
+    - Variable has been set before this template runs
+    
+    ### Problem: Template shows raw {{ }} text
+    **Solution:** Make sure:
+    - You're using double curly braces {{ }}
+    - No extra spaces inside braces
+    - Feed keys use square brackets and quotes: feeds['key']
+    
+    ### Problem: Timestamp looks weird
+    **Solution:** Format dates using Liquid filters:
+    \`{{ feeds['sensor'].updated_at | date: '%Y-%m-%d %H:%M' }}\`
+    
+    ## Best Practices
+    
+    1. **Keep it readable**: Use line breaks and spacing for multi-line messages
+    2. **Test with sample data**: Try your template with different values
+    3. **Use meaningful variable names**: 'kitchen_temp' is better than 'temp1'
+    4. **Add context**: Include units (°F, %, etc.) and location names
     :::
   `,
-
   connections: {
     mode: "value",
     output: [ "expression", "string" ],
   },
-
   template: "{{ %TEMPLATE",
-
   inputs: {
     TEMPLATE: {
+      description: `
+        ::: v-pre
+        Create your template text with static content and dynamic {{ variable }} placeholders.
+
+        Examples:
+        - 'Alert: {{ feeds['temp.kitchen'].value }}°F detected'
+        - 'Daily Report for {{ user.name }}: Battery at {{ vars.battery_level }}%'
+
+        Use {{ }} to insert live data into your message.
+        :::
+      `,
       check: "expression",
       shadow: 'io_text_multiline'
     }
   },
-
   generators: {
     json: (block, generator) => {
       const
         template = generator.valueToCode(block, 'TEMPLATE', 0) || null,
-
         blockPayload = JSON.stringify({
           textTemplate: {
             template: JSON.parse(template)
           },
         })
-
       return [ blockPayload, 0 ]
     }
   },
-
   regenerators: {
     json: (blockObject, helpers) => {
       const
         { template } = blockObject.textTemplate,
         inputs = {
           TEMPLATE: helpers.expressionToBlock(template, { shadow: "io_text" })
         }
-
       return { type: 'text_template', inputs }
     }
   }

src/definitions/block_definition.js

@@ -191,7 +191,10 @@ BlockDefinition.parseRawDefinition = function(rawBlockDefinition, definitionPath
     ? niceTemplate(rawBlockDefinition.description)
     : ""
   blockDef.ioPlus = rawBlockDefinition.ioPlus
-  blockDef.tooltip = blockDef.description.split("\n")[0]
+  // take the first line of the description
+  // blockDef.tooltip = blockDef.description.split("\n")[0]
+  // take the first sentence of the description
+  blockDef.tooltip = blockDef.description.split(/\.(\s|$)/)[0] + "."
   blockDef.disabled = !!rawBlockDefinition.disabled
   blockDef.connections = rawBlockDefinition.connections
   blockDef.template = rawBlockDefinition.template

src/docs/render_block_inputs.js

@@ -36,7 +36,7 @@ const
       if(input.type === 'label') { return }
 
       lines.push(`### \`${ capitalize(inputName) }\``)
-      lines.push(input.description)
+      if(input.description) { lines.push(niceTemplate(input.description)) }
     })
 
     return lines.join("\n\n")