Noun Project Footer Images
Audience: Org Admin, System Admin, Support, Developer
Related documentation: Menu refresh and rendering, Meal Planner, E-ink rendering, Configuration
Purpose
Blackcap can add a compact footer of recognizable ingredient or meal icons to generated Menu and Meal Planner images. The footer is useful on a kitchen display because it gives a quick visual summary without requiring another line of small text. Noun Project provides the source icon search; Blackcap applies organization rules, prepares local monochrome assets, and reuses the cached images during rendering.
The footer is decorative and navigational context. It does not replace the source menu text, recipe ingredients, accessibility labels, or shopping-list data.
How matching works
For a Menu refresh, Blackcap captures the configured page and runs the menu text/OCR path. For a Meal Planner render, it uses the meal-plan text already available to the renderer. The organization’s Noun Project Footer rules then match words or patterns to a normalized search term.
Example rules may map:
| Source text | Search term |
|---|---|
| chicken, poultry | chicken |
| bread, toast, sandwich | bread |
| noodles, pasta | noodles |
| salad, greens | salad |
Rules can also exclude noisy words that should not create an icon. Matching should be deterministic and bounded; it is not an AI interpretation of the meal.
Placement choices
Organization configuration controls where the footer appears:
- Menu and Meal Plan;
- Menu only;
- Meal Plan only;
- None.
Additional organization settings control maximum icon count, icon size, spacing, alignment, footer height/position, and related rendering behavior. These settings live under Configuration > Organization > Noun Project Footer.
Credentials and permissions
Noun Project API credentials are platform-level provider credentials. A System Admin can configure or test them. Org Admins may manage their organization’s matching and footer behavior but should not be able to view or test the shared API secret unless they also hold the required platform permission.
Credentials must be stored through the normal encrypted connection/secret boundary, never in a feature document, browser response, organization export, or generated cache filename.
Cache model
Downloaded and processed icons are stored as local generated assets. They are converted into a predictable monochrome form suitable for generated images and e-ink rather than being fetched during every display refresh.
The default organization uses the shared noun_cache/ area. Child organizations can have organization-specific cache directories, conventionally under an organization-qualified folder. When an organization requests an icon already present in the shared/default cache, Blackcap can reuse it. Newly downloaded organization assets may be placed in both the shared and organization cache according to the current cache service rules so future renders avoid repeated provider calls.
The database stores rules and durable metadata; image files remain generated cache artifacts. A missing cache file may be regenerated if the credentials and source term remain valid.
Rendering behavior
Blackcap selects unique matched terms, limits the set to the configured maximum, resolves each icon through the cache, scales it to the configured size, and lays the icons out in the footer region. Essential icon detail must render in black or sufficiently dark pixels; thin light-gray lines are not reliable on the Type K e-ink panel.
A Noun Project error must not prevent the main Menu or Meal Planner image from rendering. Blackcap should render without the missing footer icon and surface the issue in logs/diagnostics.
Menu refresh relationship
The footer is rebuilt when the Menu source changes, when organization footer rules/settings change, when a required icon is missing, or when a forced refresh is requested. A content assignment and a scheduled source refresh are different operations: assigning Menu chooses the display mode; the Menu refresh job captures and regenerates its current image.
Meal Planner relationship
Meal Planner renders use the same organization rules and cached icon pipeline but derive match text from planned meal names/content rather than page OCR. The footer does not modify the underlying meal-plan entries.
Administration workflow
- Configure Noun Project platform credentials.
- Test the provider connection as a System Admin.
- Open the target organization’s Noun Project Footer configuration.
- Enable the desired placement.
- Add focused word/pattern-to-search-term rules and exclusions.
- Render a Menu or Meal Planner preview.
- Inspect the preview and physical e-ink result.
- Adjust term choice, icon count, size, spacing, or alignment.
Prefer a small set of high-signal icons. A crowded footer can reduce readability and increase provider/cache work without helping the kitchen user.
Privacy, licensing, and attribution
Follow the Noun Project API and asset licensing terms applicable to the configured account. Do not commit private provider credentials. Retain any attribution required by the selected license in the appropriate product or documentation surface rather than drawing unreadable attribution into the e-ink footer.
Troubleshooting
No footer appears
Check the organization placement setting, rules, matched source text, icon limit, provider connection, and cache readability. Confirm the selected display render actually supports the footer.
The wrong icon appears
Review the organization rule and normalized search term. Tighten broad matches, add an exclusion, or select a more specific Noun Project term. The renderer should not infer a different ingredient automatically.
Icons download repeatedly
Verify cache paths and permissions, organization cache identifiers, atomic file writes, and that cache keys normalize the term consistently.
The footer is clear in preview but poor on e-ink
Inspect the processed monochrome cache image and actual icon size. Choose a bolder source icon, increase size/spacing, or reduce the icon count. Avoid essential one-pixel gray detail.
Provider access is unavailable
Existing cached icons can continue to render. New terms cannot be resolved until the provider connection returns. The main display image should still be produced without new icons.
Developer rules
- Keep provider access in the Noun Project client/service boundary.
- Keep organization matching rules organization-scoped.
- Never expose platform credentials to Org Admins or generated images.
- Treat icon files as regenerable cache artifacts.
- Use explicit database columns and the centralized database service.
- Preserve rendering when the provider or one icon fails.
- Cover Menu and Meal Planner behavior, cache reuse, permissions, and e-ink rendering in tests.