1. Evo Documentation
      1. Administration
        1. Admin Users
          1. Admin Roles And Groups
          2. Reset your Password - Unblock your User
          3. Why Admin Users, Roles and Groups
        2. Friendly URL Solutions
        3. Moving Site
        4. Taking sites down for maintenance
        5. Upgrading
        6. Web Users
          1. Creating a Web User
          2. Web User Groups and Document Groups
          3. Why Web Users and Groups
      2. Content Editing
        1. Editing Resources
          1. Creating a Resource
          2. Edit a Resource
          3. Move a Resource
          4. Publishing a Resource
          5. Select a Template
        2. Evo Tags
          1. Document Variables
        3. Terminology
        4. The Admin Interface
        5. Who Should Read This
      3. Designing
        1. Adding Chunks
        2. Adding Snippets
        3. Adding Tags
          1. Resource Fields
        4. Cross References
        5. Document Caching
        6. Modifiers
          1. @ Modifiers
        7. Template Basics
      4. Developer's Guide
        1. API Reference
          1. DBAPI
            1. delete
            2. escape
            3. getInsertId
            4. query
            5. select
            6. update
          2. Document Object
          3. DocumentParser Object
            1. addEventListener
            2. changeWebUserPassword
            3. documentContent
            4. documentGenerated
            5. documentIdentifier
            6. documentListing
            7. documentMethod
            8. documentObject
            9. evalSnippet
            10. getAllChildren
            11. getCachePath
            12. getChildIds
            13. getDocumentChildren
            14. getDocumentChildrenTVarOutput
            15. getDocumentChildrenTVars
            16. getLoginUserID
            17. getLoginUserName
            18. getLoginUserType
            19. getManagerPath
            20. getParent
            21. getParentIds
            22. getUserData
            23. hasPermission
            24. isBackend
            25. isFrontend
            26. logEvent
            27. maxParserPasses
            28. minParserPasses
            29. regClientCSS
            30. runSnippet
            31. table_prefix
            32. tstart
            33. webAlert
        2. Chunks
        3. Modules
          1. How to create and run a module from within the Admin Interface
          2. Managing module dependencies
          3. Setting up configuration parameters
          4. Writing the module code
        4. Plugins
        5. Snippets
        6. Template Variables
          1. @ Bindings
            1. (at)CHUNK
            2. (at)DIRECTORY
            3. (at)DOCUMENT
            4. (at)EVAL
            5. (at)FILE
            6. (at)INHERIT
            7. (at)SELECT
            8. What are (at) Bindings
          2. Creating a Template Variable
          3. What are Template Variables
          4. Widgets
            1. DataGrid Widget
            2. Floater Widget
            3. Hyperlink Widget
            4. Marquee Widget
            5. Misc. Widget
            6. RichTextBox Widget
            7. Ticker Widget
            8. Viewport Widget
            9. What are Widgets
      5. Getting Started
        1. About Evo
        2. Basic Installation
    2. Evo Extras
      1. AjaxSearch
      2. AnythingRating
      3. Breadcrumbs
      4. directResize
      5. Ditto
        1. Examples
        2. Extenders
        3. Parameters
        4. Placeholders
      6. DocLister
        1. Examples
        2. Filters
        3. Main Parameters
        4. Notes for Developers
        5. Output Parameters
        6. Processing Before Output
      7. Easy 2 Gallery
      8. eForm
      9. EvoGallery
      10. FirstChildRedirect
      11. Jot
      12. MaxiGallery
      13. multiTV
        1. Examples
        2. Extras
        3. Installation
        4. Module
        5. Snippet
        6. Template Variable
      14. PHx
        1. Custom Modifiers
      15. Quill
      16. tagLinks
      17. TinyMCE
      18. TvTagCloud
      19. Wayfinder
        1. Examples
      20. Weblogin
      21. WebLoginPE
        1. API
        2. Parameters
        3. Placeholders
        4. Typical Errors
        5. Views (Templates)
        6. Working with Forms
      22. YAMS
        1. Configuration
        2. How To
          1. YAMS + Breadcrumbs
          2. YAMS + Ditto
          3. YAMS + Ditto + PHx
          4. YAMS + eForm
          5. YAMS + Jot
          6. YAMS + Snippets
          7. YAMS + Wayfinder
          8. YAMS Custom Multilingual TVs, Chunks, Snippets
          9. YAMS Language Dependent Layout
          10. YAMS Language Flag List
          11. YAMS Language Select Landing Page
          12. YAMS Mime-type Dependent Alias Suffixes
          13. YAMS Multilingual Weblinks
          14. YAMS XML Sitemap
        3. Installation
        4. Language Modes
        5. Language Settings
        6. Placeholders
        7. Setup
        8. Snippet
        9. Technical Details
    3. Evo Tutorials
      1. Extras - How To
        1. Ditto Tutorials
          1. Add Ditto Pagination
          2. Basic RSS feed
          3. Category Tagging with Ditto
          4. Create a Custom Ditto Template
          5. Custom Placeholders
          6. Dropdown Menu with Ditto
          7. Dynamically Show Related Posts
          8. Promote to Home Page
          9. Sort by a date tv
          10. Tagged blogging with Ditto (ex.1)
          11. Tagged blogging with Ditto (ex.2)
          12. Tagging Screencast

EvoGallery

This is a user-contributed Extra. If you find issues or would like more info or help, please contact the author.

What is EvoGallery ?

EvoGallery is a dynamic gallery extra for Evo. It allows you to quickly and easily create galleries of images by associating them with any page on your site. Galleries can be outputted in a variety of ways using a templated system.

EvoGallery does not create stand-alone, self-contained galleries that are not associated with a particular page. Every photo uploaded must be associated with a page in the site tree.

History

EvoGallery was originally written by Brian Stanback some years ago and was simply known as the Gallery Module. Jeff Whitfield later took it and rewrote all the javascript using jQuery and used the Uploadify jQuery plugin in an effort to make the uploader compatible with newer versions of Flash.

Many updates have been made since then to give it more functionality.

The name was changed later to EvoGallery in order to differentiate this add-on from many of the other "gallery" add-ons. In January 2011, development has been picked up by several community members with the intention to bring this plugin back to speed.

Install

To install EvoGallery, unzip the downloaded file and follow the following steps:

  • Create a directory called "galleries" in the assets directory of your Evo site and give it full write permissions (777).

  • Copy / Upload the "assets/modules/evogallery" directory to the "assets/modules" directory of your Evo site.

  • Copy / Upload the "assets/snippets/evogallery" directory to the "assets/evosnippets" directory of your Evo site.

  • (Optional) Copy / Upload the "assets/plugins/managermanager/functions/gallerylink.inc.php" file to the "assets/plugins/managermanager/functions" directory of your Evo site.

  • Copy / Upload the install directory to the root directory of your Evo site

  • Run the installer (http://yoursite/install/index.php) and follow the simple on-screen instructions to complete the installation.

Once you've completed the installation, be sure and remove the installer directory from your site.

Usage

EvoGallery requires the use of both a module and a snippet to achieve full functionality.

Module

The EvoGallery module allows you to manage all the photos that are associated with the various pages of your site. After clicking on the EvoGallery item under Modules, you'll be presented with a top-level list of pages from the site tree:

From there, simply click on the links to drill down to the page you wish to manage:

Uploading photos is as easy as clicking on the Select Files button and choosing the photos you want to upload. The files you select will be added to the queue:

To upload the photos, simply click on the Upload Files link below the queue. Each photo will then be uploaded and, along with each photo, a thumbnail will be created. Both photos and thumbnails are processed and resized based on the module configuration (more on that in a second):

Once a photo is uploaded, you can manage the additional properties of the image simply by hovering over an image and clicking on the edit icon. A lightbox will popup that will allow you to update the title, description, and keywords for the image as well as the ability to upload and replace the existing image with a new one:

If you need to delete an image, simply hover over the thumbnail of an image and click on the red "X". You can also reorder the order of the images simply by dragging and dropping images in the order you want and then clicking on the "Save Order" button.

Configuration

Advanced configuration options are available through module configuration:

Name Description Default Value
PHPThumb config for images in JSON (phpthumbImage) PHPThumb parameters for images (see below for details) {'w': 940, 'h': 940, 'q': 95}
PHPThumb config for thumbs in JSON (phpthumbThumb) PHPThumb parameters for thumbnails (see below for details) {'w': 175, 'h': 175, 'q': 75}
Root Document ID (docId) ID of the document root to begin listing galleries for (0 for all documents) 0
Save path (savePath) Full system path to location of product images assets/galleries
Module path (modulePath) Path to the module directory assets/modules/evogallery/
Keep original images (keepOriginal) If set to "Yes", this will keep original images when upload Yes
Random filenames (randomFilenames) If set to "Yes", this will apply generated random filenames to uploaded pictures No

Please note the following:

  1. PHPThumb config only affect images uploaded AFTER changing the settings. Or you can regenerate all images from action menu.
  2. Evo doesn't support double quotes in parameter values, so use single quote.
Some examples of PHPThumb config

Max width 940, max height 940, quality 95

{'w': 940, 'h': 940, 'q': 95}

Max width 1280, max height 1024, quality 95, apply watermark filter with filename "/assets/images/watermark.png" and position top-left

{'w': 1280, 'h': 1024, 'q': 95, 'fltr': ['wmi|/assets/images/watermark.png|TL']}

Max width 1280, max height 1024, quality 95, zoom crop, apply brightness filter with value 200, apply watermark filter with filename "/assets/images/watermark.png" and position to bottom-right

{'w': 1280, 'h': 1024, 'q': 95, 'zc': 1, 'fltr': ['brit|200', 'wmi|/assets/images/watermark.png|BR']}

Snippet

Once you've added images to some pages, you then have to output the various images and galleries to the front-end of the site. The EvoGallery snippet allows you to generate lists of your images and galleries in a variety of ways.

Display

EvoGallery has three basic display modes when calling the snippet:

  • galleries
  • images
  • single

The "galleries" mode allows you to display a list of available galleries in a container. By default, the document ID is set to the current document but can be overridden using the "docId" property.

The "images" mode allows you to display a list of images associated with a given page. By default, the document ID is set to the current document but, just like the "galleries" mode, it can be overridden using the "docId" property.

The "single" mode allows you to display a single image provided that you know the ID of it in the database. Generally, this information is determined through a separate snippet instance in "images" mode before passing it on to another instance. By default, this mode looks for a "picId" variable via a standard PHP request variable.

Types

The "type" property tells the snippet what default templates to use when outputting the list of images or galleries. If you look in the EvoGallery snippet directory (/assets/snippets/evogallery/), you notice that there is a classes folder as well as a few other folders (jquery-cycle, simple-list, and single). These correspond to the available types that can be assigned to the snippet.

If you look inside a type folder, you'll notice three files: tpl.config.txt, tpl.default.txt, and tpl.item.default.txt. These files are used to set the default templates for the given type. Other files could be used to set the default templates for the first, last, and alternate items (tpl.item.first.txt, tpl.item.last.txt, and tpl.item.alt.txt respectively).

The tpl.config.txt file allows you to set which CSS and script files to load when the gallery is called. To add a file, simply create a new line after one of the three designated file type areas: @EXTSCRIPT, @SCRIPT, or @CSS. @EXTSCRIPT is for scripts that are meant to be loaded outside of the given type directly.

This allows you to load script files using either a direct URL or a path that's root relative to your site. @SCRIPT is for script files that reside inside the given type directory. @CSS is for CSS files that reside inside the given type directory. If you create subdirectories within the type directory, be sure that the paths written for lines in the @SCRIPT and @CSS sections are relative to your root type directory.

While you may use a custom type to assign templates to the EvoGallery snippet, it's not always necessary to do so. You could leave the "type" property out and simply assign chunks to the various templates. Since the default type doesn't have any CSS or script files assigned for the tpl.config.txt, you're free to create a snippet call made up of entirely assigned chunk templates.

Other Properties

Name Description Default Value
display Have the snippet output either a list of galleries within the specified doc Id, a list of images within a gallery, or a single image based on a pic Id. Possible values: galleries, images, single images
type Output type, if specified, the snippet will automatically load the required javascript. Pre-packaged types: simple-list, single, jquery-cycle simple-list
includeAssets Register external scripts and CSS files required by the specified gallery type. If set to 0, these will need to be included manually in the document <head> 1
picId ID of specific pic to show when displaying by a single image $_REQUEST[ 'picId' ]
docId Document ID for which to display gallery (default: document from which snippet was called). Multiple document id's can be specified by commas (no spaces), or * for all documents $modx->documentIdentifier
gallerySortBy Galleries sort order (possible fields: id, pagetitle, longtitle, description, alias, pub_date, introtext, editedby, editedon, publishedon, publishedby, menutitle) or RAND() menuindex
gallerySortDir Direction to sort the galleries ASC or DESC ASC
ignoreHidden Display documents marked as hidden in the gallery listing 0
excludeDocs Prevent the specified documents from showing in the gallery listing. Multiple document id's can be specified by commas (no spaces). 0
sortBy Sort items by field (possible fields: id, content_id, filename, title, description, sortorder) or RAND() sortorder
sortDir Direction to sort the items ASC or DESC ASC
limit Limit the number of items to display null
tags Comma delimited set of tags to filter results by. Looks in the keywords field for the images. null
tagMode Search mode for tag: AND or OR AND
tpl Chunk template for the outer gallery template (defaults to tpl.default.txt for selected type). Placeholders: items $this->config['snippetPath'] . $this->config['type'] . '/tpl.default.txt'
itemTpl Chunk template for each thumbnail/image in the gallery. See below for available placeholders. $this->config['snippetPath'] . $this->config['type'] . '/tpl.item.default.txt'
itemTplFirst Chunk template for last thumbnail/image in the gallery (defaults to tpl.item.first.txt for selected type) $this->config['snippetPath'] . $this->config['type'] . '/tpl.item.first.txt'
itemTplLast Chunk template for last thumbnail/image in the gallery (defaults to tpl.item.last.txt for selected type) $this->config['snippetPath'] . $this->config['type'] . '/tpl.item.last.txt'
itemTplAlt Chunk template for alternate thumbnail/image in the gallery (defaults to tpl.item.alt.txt for selected type) $this->config['snippetPath'] . $this->config['type'] . '/tpl.item.alt.txt'
itemAltNum Modifier for the alternate thumbnail/image (defaults to every second item) 2
galleriesUrl URL to the galleries directory (should contain folders with the Id of the document, with a thumbs/ folder within each document's gallery) $modx->config[ 'base_url' ] . 'assets/galleries/'
galleriesPath Path to the galleries directory $modx->config[ 'base_path' ] . 'assets/galleries/'
snippetUrl URL to the snippet directory $modx->config[ 'base_url' ] . 'assets/snippets/evogallery/'
snippetPath Path to the snippet directory $modx->config[ 'base_path' ] . 'assets/snippets/evogallery/'
id Unique ID for this EvoGallery instance and unique URL parameters null
paginate Paginate the results set into pages of &show length 0
paginateAlwaysShowLinks Determine whether or not to always show previous next links 0
show Number of images to display in the results when pagination on 20
paginateNextText Text for next label Next
paginatePreviousText Text for previous label Previous
tplPaginatePrevious Template for the previous link <a href="[url]" class="eg_previous_link">[PaginatePreviousText]</a>
tplPaginateNext Template for the next link <a href="[url]" class="eg_next_link">[PaginateNextText]</a>
tplPaginateNextOff Template for the inside of the next link <span class="eg_next_off eg_off">[PaginateNextText]</span>
tplPaginatePreviousOff Template for the inside of the previous link <span class="eg_previous_off eg_off">[PaginatePreviousText]</span>
tplPaginatePage Template for the page link <a class="eg_page" href="[url]">[page]</a>
tplPaginateCurrentPage Template for the current page link <span class="eg_currentpage">[page]</span>

Examples

Output a list of images using the jQuery Cycle type (jquery-cycle):

[[EvoGallery? &display=`images` &type=`jquery-cycle`]]

Output a list of images using the jQuery Cycle type (jquery-cycle), sorted on the "sortorder" variable:

[[EvoGallery? &display=`images` &type=`jquery-cycle` &sortBy=`sortorder`]]

Output the galleries available in a specific container using a specific item template:

[[EvoGallery? &display=`galleries` &docId=`22` &itemTpl=`galleryListItem`]]

Template Placeholders

Depending on the display type, there are several available placeholders which you may use in the chunks for the template parameters. You can also reference a template variable by its name. These placeholders have PHx enabled, so you may use specific PHx syntax in your templates.

Placeholder Available in Outputs
total Gallery display Total amount of images within the current gallery.
images_dir Gallery, single and images display Image directory for the current gallery.
thumbs_dir Gallery, single and images display Thumbnail directory for the current gallery.
original_dir Gallery, single and images display Original image directory for current gallery.
plugin_dir Gallery, single and images display URL path of current output type
id Gallery, single and images display In gallery display, this returns the document ID for the current gallery. In images and single view, this returns the unique ID (picId) for an image.
content_id Single and images display Returns the document ID the image is linked to.
filename Gallery, single and images display The filename of the current image. In Gallery view, this is the first image of the gallery based on the sortBy and sortOrder parameters.
title Single and images display Title which has been specified in the backend.
description Single and images display Description which has been specified in the backend.
keywords Single and images display Comma delimited list of keywords for the image as specified in the backend.
sortorder Single and images display Sort number, based on the order in the backend
Resource variables Gallery display The following resource variables are available in gallery display through placeholders:
id, pagetitle, longtitle, description, alias, pub_date, introtext, editedby, editedon, publishedon, publishedby, menutitle

ManagerManager Function

Included in the distribution of EvoGallery is an optional function for the ManagerManager plugin that allows you to create a link directly to the section of EvoGallery that is related to a given page. This is a great help to content editors since they don't have to constantly click over to the EvoGallery module and drill down to manage the page they want.

To use the function, simply create a text template variable and name it whatever you want. Next, add the following call to your ManagerManager rules:

mm_galleryLink($fields, $roles, $templates, $moduleid);
  • $fields should be replaced with the field name you want to affect. If you named your template variable "gallery" you replace $fields with "gallery".
  • $roles should be replaced with the IDs of the roles that should be affected or left empty to apply the rule to all roles.
  • $templates contains the IDs of templates to apply the rule to, or can be left empty to apply to all templates.
  • $moduleid is a custom variable specific to this function. It tells the function what module ID to use. To find out the ID of a module, simply copy the link to the module in the main menu. The ID will be part of the URL itself. E.g.: /manager/index.php?a=112&id=2. In this case, the $moduleid is 2.

Since EvoGallery 1.1 in the distribution is an optional widget for the ManagerManager plugin that allows you to create a tab within document editing page

mm_widget_evogallery($moduleid, $title, $roles, $templates);
  • $moduleid is a custom variable specific to this function. It tells the function what module ID to use. To find out the ID of a module, simply copy the link to the module in the main menu. The ID will be part of the URL itself. E.g.: /manager/index.php?a=112&id=2. In this case, the $moduleid is 2.
  • $title is display name of tab.
  • $roles should be replaced with the IDs of the roles that should be affected or left empty to apply the rule to all roles.
  • $templates contains the IDs of templates to apply the rule to, or can be left empty to apply to all templates.

Suggest an edit to this page.