Gallery2:Themes:Reference:Blocks - Gallery Codex
Personal tools

Gallery2:Themes:Reference:Blocks

From Gallery Codex

Modules can provide blocks that can be placed anywhere in your Gallery layout. Think of Lego bricks, you can build your own layout by arranging blocks any way you want.

Usage

Usage: {g->block type=blockType [block-specific parameters]}

  • g->block inserts a Gallery block in a template. This is similar to the blocks that are configured for albums, photos, etc through the Site Admin interface
  • Examples of g->block in use can be found in the source code of the templates that come with Gallery, for example in the Floatrix theme

Blocks

  • albumselect.AlbumSelect
    • Show album list in a select box
  • albumselect.AlbumTree
    • Show album list in a dynamic tree
  • cart.ShowCart
    • Block with summary info about cart contents and a link to view cart
  • comment.ViewComments [item=..] [show=..]
    • Block to show given number of recent comments on given item
    • Item defaults to $theme.item; Show defaults to 3
  • comment.AddComment [item=..]
    • Block to show Add Comment form
    • Item defaults to $theme.item
  • core.BreadCrumb [separator=..]
    • Show links to ancestor albums
    • Data must already be loaded via 'parents' key to loadCommonTemplateData
    • Optional separator string is placed between each album name
  • core.EmergencyEditItemLink [permissions=..] [checkBlocks=..]
    • Show "Edit" link if core.ItemLinks block is not found in specified block lists and user can edit the current item
    • Permissions default to $theme.permissions
    • Old checkSidebarBlocks/checkAlbumBlocks/checkPhotoBlocks parameters are deprecated; use parameter like checkBlocks="sidebar,album" instead
  • core.GuestPreview
    • Show block to registered users to select guest preview mode
  • core.ItemInfo [item=..] [showDate=true] [showOwner=true] [showSize=true] [showViewCount=true] [showSummaries=true]
    • Block to show specified data about the given item
    • showSummaries displays all available item summary info, such as item keywords, count of comments, rating interface, etc.
  • core.ItemLinks [item=..] [links=..] [useDropdown=..] [lowercase=..]
    • Item defaults to $theme.item; Links defaults to $theme.itemLinks (loaded via loadCommonTemplateData)
    • If useDropdown=true then show multiple links in a select list
      If false or there is only one link then show all the links
    • Add lowercase=true parameter to convert all link text to lowercase
  • core.LanguageSelector
    • Show select list of available language to allow user to change language
  • core.LoginBlock
    • If user is a guest then show login form
  • core.NavigationLinks [navigationLinks=..]
    • Links to previous locations (Back to photo, etc.)
    • Note: Removed in Gallery 2.3. This block only exists in Gallery 2.0 - 2.2.
  • core.Navigator [navigator=..] [reverseOrder=..] [prefix=..] [suffix=..] [currentPage=..] [totalPages=..] [currentItem=..] [totalItems=..]
    • Use itemNavigator or pageNavigator key for loadCommonTemplateData and then pass navigator=$theme.navigator
    • Set reverseOrder=true to swap the order of next/last and first/previous sections (useful if css float is used in display)
    • Prefix = text to place before first/previous links; Suffix = text to place after next/last links
    • Include currentPage/totalPages to add Page x of y between navigator links (usually get values from $theme.currentPage and $theme.totalPages).
    • Include currentItem/totalItems to add x of y between navigator links (can use core.LoadPeers callback to get values).
  • core.Pager
    • Block with current page number and links to other pages
    • Data must already be loaded via 'jumpRange' key to loadCommonTemplateData
  • core.PeerList [item=..] [windowSize=..]
    • Links to some peer items; item defaults to $theme.item and windowSize defaults to 7
  • core.PhotoSizes
    • Block to show image sizes and links to view each size
    • Data must already be loaded via 'imageViews' key to loadCommonTemplateData
  • core.SystemLink [linkId=..]
    • If given linkId was loaded by 'systemLinks' key to loadCommonTemplateData then show the link
  • core.SystemLinks [order=..] [othersAt=..] [separator=..]
    • Show all system links; data must already by loaded via 'systemLinks' key to loadCommonTemplateData
    • Order is a space separated list of known link ids to give the order links should be displayed
    • OthersAt is the position where any links not given in the "order" value should be place (1 = first)
    • Separator is a string to include after each link
  • core.ThemeSettingsForm [formId=..] [message=..]
  • customfield.CustomFields [item=..]
    • Show 'detail' custom fields for given item (defaults to $theme.item)
  • exif.ExifInfo [item=..]
    • Show EXIF data for given item (defaults to $theme.item) with controls to select summary or detail view
  • imageblock.ImageBlock [parameters..]
    • Image block; see Site Admin -> Image Block for a list of available parameters (e.g. use blocks= instead of g2_blocks=)
    • Example: {g->block type="imageblock.ImageBlock" blocks="randomAlbum|randomImage" showDate=0 showOwner=1 showViews=1 showTitle=1 showHeading=0 useDefaults=0}
    • useDefaults=0 is required if you want to override the site defaults which are set in Site Admin -> Image Block
    • repeatBlock=.. will repeat the given blocks parameter that many times (eg. blocks=recentImage|recentImage is the same as blocks=recentImage repeatBlock=2)
  • imageframe.ImageFrame (container) [frame=..] [width=..] [height=..] [maxSize=..]
    • Render given frame type around content in this container
    • Image in content should have %CLASS% in its class attribute and %ID% for its id
    • ImageFrame definitions must already be loaded by imageframe->init() calls from modules/themes using imageframes
    • Supply width/height parameters to generate a fixed-size imageframe (this is most cross-browser compatible). Optionally add maxSize parameter to scale given dimensions to fit that size (see g->image).
    • Omit width/height to generate an imageframe that dynamically resizes to fit its content, even if the content size changes (via javascript) after the page loads. However, this type of imageframe may not render properly on Opera or Safari browsers.
  • keyalbum.KeywordLinks [forItem=..] [item=..] [onlyPublic=..] [showCloud=..] [maxCloudFontEnlargement=..]
    • Show links into Keyword Albums
    • If forItem is true (it defaults to true) then show simple list of links for keywords of given item (item defaults to $theme.item) [in some themes like "nature" this can be a neccessary condition for call to work! "{g->block type="keyalbum.KeywordLinks" forItem=false}" here is the minimum syntax needed]
    • If forItem is false then load all keywords (onlyPublic defaults to true; load keywords for public items or all items) and show a select list or keyword cloud (showCloud defaults to false)
    • maxCloudFontEnlargement is how many pixels bigger the font size should be for the most common keyword, default is 5
    • sizeLimit sets the number of keywords displayed. the filter uses most frequenct keywords first
  • members.MembersSummary
    • Block with number of members and link to members list (if user has access)
  • quotas.QuotasSummary
    • Show disk usage and quota for current user
  • rating.Rating [item=..]
    • Show rating interface for given item (defaults to $theme.item)
  • rss.RssBlock
    • Show links for RSS feeds
  • search.SearchBlock [showAdvancedLink=..]
    • Block with text input for searching the Gallery
    • Show link to advanced search unless specified (showAdvancedLink defaults to true)


Template Locations

The template for each block is in a standard location. As an example we'll use cart.ShowCart. The template is located in:

modules/cart/templates/blocks/ShowCart.tpl

If there's a parameter you think might exist but isn't documented above, try viewing the template to see if it does in fact exist in the template. If it does, you can go ahead and use it when you load a block.

Block Parameters

  • Required fields: description, type, default
  • Optional fields: overrides
  • Allowed types: boolean, choice, text

Text Parameter

  • Allowed values: Any text
  • Example (text here used as container for any number):
            'sizeLimit' => array(
                'description' => $gallery->i18n('Maximum number of keywords (empty for no limit)'),
                'type' => 'text',
                'default' => ''),

Boolean Parameter

  • Allowed values: 'true', 'false'
  • Example:
            'onlyPublic' => array(
                'description' => $gallery->i18n('Keywords from public items only'),
                'type' => 'boolean',
                'default' => 'true'),

Choice Parameter

  • Allows values: Any text
  • Example:
            'show' => array(
                'description' => $gallery->i18n('Number of comments'),
                'type' => 'choice',
                'default' => '2',
                'choices' => array(
                    '1' => $gallery->i18n('1 comment'),
                    '2' => $gallery->i18n('2 comments'),
                    '5' => $gallery->i18n('5 comments'),
                    '10' => $gallery->i18n('10 comments'),
                    '100' => $gallery->i18n('100 comments'))))),

Note: The array key of choices is the value that is passed to the block. The array value is the text shown to the user as a choice in the theme settings (e.g. in Site Admin -> Themes).

Overrides

  • A parameter can override other parameters. If overrides are specified, then the listed parameters will be greyed out by default. The overridden parameters can only be edited when the value of the master parameter is 'false' (unchecked checkfield).
  • Example:
            'forItem' => array(
                'description' =>
                    $gallery->i18n('Keywords for current item (uncheck to show all keywords)'),
                'type' => 'boolean',
                'default' => 'true',
                'overrides' => array('onlyPublic', 'sizeLimit')),
            'onlyPublic' => array(
                'description' => $gallery->i18n('Keywords from public items only'),
                'type' => 'boolean',
                'default' => 'true'),
            'sizeLimit' => array(
                'description' => $gallery->i18n('Maximum number of keywords (empty for no limit)'),
                'type' => 'text',
                'default' => ''),

Note: In this example, the user needs to click on the "forItem" checkbox to enable the other parameter fields.

Creating New Blocks

See How To Create Blocks