SLB: Notes – JS: Components: Themes: Layout Tags

By Sol in Lab


  • Insert predefined HTML
    • Core and theme-specific
  • Support dynamic content
    • Changes on per-item basis
    • Necessary to support multiple content types (e.g. images in <img> element, HTML in <div>, etc.)
  • Support attributes/options
    • Customize how tag is processed/output
  • Support user-customizable options (UI labels, formatting, etc.)

Elements (Core)

  • Content: Primary content (image, video, etc.) displayed in lightbox
    • Dynamic: HTML changes based on content type
  • Item Data: Data/attributes of current item
    • Examples: Permalink, source URI, image dimensions, title, caption, description, etc.
    • Available attributes based on item’s content type
    • Common attributes
      • Source URI (string): Direct URI to content (for display in lightbox)
        • Image source, video file, etc.
      • Permalink (string): Canonical URI for content (e.g. when viewed on its own page)
        • Video page, attachment page, image URI, Website address, etc.
      • Title (string): Item caption
        • Derived from link if not otherwise available
      • Group (obj): Group item belongs to
      • Internal (bool): Whether item is internal media or not
  • UI elements
    • Static: Does not change per-item
    • Labels: User-customizable UI content
      • Navigation text: previous/next item, start/stop slideshow, close, etc.
    • Predefined elements: HTML for building UI (close button, prev/next button, loading indicator, etc.)


  1. Dynamic Data (options)
    1. Wrap tag output with DOM element
      • Example:
        <span id="slb_tag-id" class="slb_dynamic_wrap">[tag output]</span>
      • Wrapper indicates dynamic data using DOM attributes
        • class: slb_dynamic_wrap
        • id: slb_tag[id] (Points to object with tag options)
        • Alternative: Set reference to raw tag as data on wrapper element itself
          $(el).data('slb_tag', tag);
      • + Allows dynamic replacement of content in viewer
      • Similar to current method of loading new content in lightbox (replace HTML inside of a wrapper DOM element)
      • + Allows any tag to be dynamic
      • ? Should all tags be dynamic?
        • A: No, only those accessing data (item, environment, date/time, etc.)
      • - Cannot use data within HTML tags (since tag output is wrapped in a DOM element itself)
        • Example

          <a href="{tag}">Link text</a>


          <a href="<span id="slb_tag-id">[tag output]</span>">Link text</a>
        • Solution (options)
          1. Build HTML tag using options in theme tag
            • Example
              • Link
                <a href="[tag data]">Link text</a>
              • Tag
                {tag pre='<a href="' post='">Link text</a>'}
              • Alt
                {tag format='<a href="">Link text</a>'}
                • Uses string formatting to replace %s with tag output
            • Entire output wrapped in wrapper
            • Original string format saved
            • Formatted value inserted as HTML into DOM (wrapped)
            • + Allows complex output using item data
            • + Does not impede HTML output
            • - Convoluted way to build HTML output using tag output
            • - Limited: How to use other data within link? (link text, title attribute, etc.)
          2. Register handlers for different tags
            • Similar to CNR content type field templates
            • Example: Link
              {link href="" data="item.permalink"}Link text{/link}
              • Attributes
                • href: URI format
                • data: Data to use in URI format
                • title: Link title (can be string format)
                • title_data: Data to use for Link title
                • Link text: Wrapped in tag
            • + More specific handling of output
              • Attribute data will be properly formatted (escaped for URLs, etc.)
            • + Simple: Don’t need to mess with HTML in tag attributes
            • - More complex to implement
            • + Highly flexible: any kind of output can be accomplished by tag handlers
    2. Rebuild entire layout for each item
      • Start with raw layout (with tags, etc.) every time an item is displayed
      • - Inefficient: must parse entire layout for each item (even if few dynamic tags are present)
        • Performance may suffer
      • + Will always be a certain amount of dynamic data in layout (content, etc.)
        • Parts of layout must always be rebuilt per-item anyway
      • ? Visual smoothness? Rebuilding full layout affect transition between items?
        • Likely
      • + Simple: Don’t need to wrap tags since raw layout will be used every time
  2. Tags (Default)
    • item: Access item data/properties
      • Example:{item.title} – Item title
      • Dynamic: Yes
      • Format modifiers: Yes
        • {item.title|lower|escape} (makes item title lowercase and escapes it)
    • ui: User interface output
      • Example: {ui.nav_next} – Next item navigation link
      • Dynamic: No
      • Format modifiers: No
    • Common attributes: Can be set on all default tags
      • May be implemented differently by different tags
      • class: CSS class
      • id: Unique ID
  3. Tag format (Options)
    1. Curly braces + XML-style attributes
      • Tags denoted by curly braces ({, })
      • Options/attributes set XML-style: attribute="value"
      • + Simple: Familiar to any using HTML
      • + Fairly unique: Curly braces not common in normal content
      • ? How do format modifiers fit in?
        • Simple: {tag.prop|modifier}
        • With Options
          1. XML-style attributes followed by delimited modifiers: {tag.prop attribute="value"|modifier}
            • Attributes processed first, then passed to modifiers
            • + Clear separate between modifiers and attributes
            • + Still pretty simple to write
            • - Convoluted: 2 different modes for similar information (options that modify output)
          2. Format modifier style: {tag.prop|attribute:value|modifier}
            • - Attributes not clearly separated from modifiers (hard to tell when option is an attribute or a modifier)
            • + Simple: Singular way to add options that modify output
            • + Tag handler can use supported options and pass output to global modifiers after (with processed options removed)
              • supports_modifiers flag in tag definition can determine whether output is processed by global modifiers or not
          3. One or the other (attributes or modifiers): {tag.prop attribute="value"} or {tag.prop|modifier}
            • - Limiting: May be useful to have access to properties and modifiers in tag
              • ? When? (Use cases)
                • Item: No – Modifiers only ({item.title|lower})
                • UI: No – Attributes only ({ui.nav_next class="test"})
                  • Outputs DOM element, so should not be modified by standard modifiers (lower, etc.)
                    • Formatting of values (e.g. labels) should be handled via CSS
                • Custom Tags: Possibly ({tag attr="value"|modifier})
                  • + Allows theme designer to further customize output from custom tags
    2. Double braces (curly/square) + XML-style attributes
      • Attributes same as 1
      • Tags denoted by double braces ({{/}} or [[/]])
      • + More unique: double braces even less common than single braces in content
      • - More characters to type for every tag
      • - Increases visual “noise” in layout
    3. Other established format
      • Liquid, Smarty, etc.
      • Need to look into options
  4. Registering External Tag Handlers (options)
    1. Client file registration (via other plugins)
      • Allow additional files to be registered with internal client files
      • Use same structure: [handle, file, etc.]
      • - Will need to expand file parser to handle external files
        • + Not too difficult since external files should have full path rather than relative path (just look for presence of path constants)
      • + Allows simple inclusion of JS files after internal files loaded
        • JS file can register tags, etc.
      • Use dependencies to determine order of loading external files
        • + Also controls whether external file is loaded (if dependent on internal file that is not loaded, external file with not be loaded, etc.)
    2. WP Hooks
      • Fire hooks before/after various operations
      • Events
        • slb_head/slb_admin_head: Header files loaded
        • slb_footer/slb_admin_footer: Footer files loaded
        • slb_client_init: Client JS initialized
      • + Allows external code to add files/code in proper location
        • Ensures SLB’s files are loaded before external code is executed
      • ? How to confirm necessary files have been loaded?
        • Hooks will always fire, but different files are loaded based on various conditions (context, callbacks, etc.)
        • A Use SLB functions in external code to determine if external file should be loaded
          • PHP
            /* External Plugin */
            add_action('slb_head', 'ext_load_head_files');
            function ext_load_head_files() {
            	if ( slb_is_enabled() && slb_is_context('public') ) {
            		//Load files...
          • JS (object detection)
            /* Confirm SLB loaded */
            if ( !SLB || !SLB.View )
            	return false;
            /* Run code */
      • ? How to fire hook after files loaded?
        • File loading is handled by WP enqueue/registration API (No direct loading)
        • AAdd hook to trigger SLB hook
          //Low priority hook
          add_action('wp_head', 'call_slb_head', 99);
          function call_slb_head() {
          	//Fire internal hook
  5. Tag Handlers
    • Properties
      • id (string): Tag ID
      • build (function): Function to build tag output
      • attrs (object): Default attributes/values
      • dynamic (bool): Tag rebuilt for each item or not
      • supports_modifiers (bool): Determines if modifiers can be used on tag output