{"id":19451012,"url":"https://github.com/variar/grav-plugin-unitegallery","last_synced_at":"2025-07-19T16:33:25.876Z","repository":{"id":48604881,"uuid":"85477740","full_name":"variar/grav-plugin-unitegallery","owner":"variar","description":"Grav plugin to create image galleries with unitegallery js library","archived":false,"fork":false,"pushed_at":"2021-07-18T16:11:34.000Z","size":423,"stargazers_count":19,"open_issues_count":20,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T15:44:39.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/variar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-19T13:24:52.000Z","updated_at":"2024-01-26T18:03:26.000Z","dependencies_parsed_at":"2022-09-10T09:01:27.041Z","dependency_job_id":null,"html_url":"https://github.com/variar/grav-plugin-unitegallery","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/variar%2Fgrav-plugin-unitegallery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/variar%2Fgrav-plugin-unitegallery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/variar%2Fgrav-plugin-unitegallery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/variar%2Fgrav-plugin-unitegallery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/variar","download_url":"https://codeload.github.com/variar/grav-plugin-unitegallery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250754495,"owners_count":21481822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T16:39:52.817Z","updated_at":"2025-04-25T04:30:20.695Z","avatar_url":"https://github.com/variar.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grav Unitegallery Plugin\n\n`Unitegallery` is a [Grav](http://github.com/getgrav/grav) Plugin that provides\n[Twig](http://github.com/twigphp/Twig) extension for creating images gallery using [Unitegallery](http://unitegallery.net)\njavascript library\n\nDemo site with default Grav installation and this plugin can be found in this [repository](https://github.com/variar/grav_example_unitegallery).\n\n# Installation\n\nInstalling the Unitegallery plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.\n\n## GPM Installation (Preferred)\n\nThe simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's terminal (also called the command line).  From the root of your Grav install type:\n\n    bin/gpm install unitegallery\n\nThis will install the Unitegallery plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/unitegallery`.\n\n## Manual Installation\n\nTo install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `unitegallery`.\nYou can find these files on [GitHub](https://github.com/getgrav/grav-plugin-unitegallery).\n\nYou should now have all the plugin files under\n\n    /your/site/grav/user/plugins/unitegallery\n\n\u003e\u003e NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), and a theme to be installed in order to operate.\n\n# Usage\n\nThe `unitegallery` provides new [Twig](http://github.com/twigphp/Twig) extension that adds function `unite_gallery`\nto be used in templates. Pass images collection as firts argument and gallery\noptions (json string) as optional second argument.\n\nThis functions goes through each image in passed collection, generates thumbnails (which are cached),\ncollects images metadata and outputs special div as required by [Unitegallery](http://unitegallery.net)\njavascript library. Also all css and js files needed for selected theme are added to page assets.\n\n\u003e\u003e NOTE: When page with the gallery is loaded first time thumbnails for each new image are generated. This can be quite time consuming process. Consider loading page manually when new images are added, so that users of your site will not encounter long page load time.\n\nTo create the gallery you should call `unite_gallery` from twig template for desired page.\nFor example add template `gallery.html.twig` inside `\u003cyour_theme\u003e/templates/modular` directory with simple content:\n```\n\u003cdiv class=\"modular-row gallery-container {{ page.header.class }}\"\u003e\n\t{{ unite_gallery(page.media.images) }}\n\u003c/div\u003e\n```\n\nThen create new subpage with name `gallery.md` inside your modular page and add some images so the structure looks like this:\n```\nuser\n|--pages\n   |--page1\n   |--page2\n   |--page_with_gallery\n      |--modular.md\n      |--_pictures\n         |--gallery.md\n         |--image01.jpg\n         |--image01.jpg.meta.yaml\n         |--image02.jpg\n         |--image02.jpg.meta.yaml\n```\n\nContent of `gallery.md` can be like this:\n```\n---\ntitle: My fancy gallery\n---\n```\n\nAnd `modular.md` simply includes child pages:\n```\n---\ntitle: My Gallery Page\n\ncontent:\n  items: @self.modular\n---\n```\n\nTo pass custom gallery parameters modify twig template and pass them as json:\n```\n// with custom options (passed directly to unitegallery js function)\n{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"tiles\", \"tiles_type\":\"justified\"}') }}\n```\n\nOutput html example:\n\n```html\n  \u003cdiv id=\"unite-gallery\" style=\"display:none;\"\u003e\n\t\t\u003cimg alt=\"Image 1 Title\" src=\"/images/6/6/8/a/2/668a2df0c6571575ae7dd9216234864a4f7c4bc0.jpg\"\n\t\t\tdata-image=\"/images/9/f/a/5/d/9fa5d6c0eb6c711fd4a9f58f9c13c3f191b66cb4.jpg\"\n\t\t\tdata-description=\"Image 1 Description\"\u003e\n\t\u003c/div\u003e\n\n  \u003cscript type=\"text/javascript\"\u003e\n    jQuery(document).ready(function(){\n      jQuery(\"#unite-gallery\").unitegallery({\"tiles_type\":\"justified\",\"gallery_theme\":\"tiles\"});\n    });\n  \u003c/script\u003e\n```\n\nGrav images [metadata files](https://learn.getgrav.org/content/media#metafiles) are used to fill title and description using following properties mapping:\n* meta.alt_text is used for alt attribute\n* meta.description is used for data-description attribute\n\nNote: the meta.alt_text is what is being displayed on the text panel being displayed if you click on a picture.\n\n# Using the various layouts of unitgallery\n\nIf you visit [unitegallery](http://unitegallery.net/) you see that they have various layouts that you can use for your albums. Below are some examples.\n\nThis generates a \"traditional\" album where you see one picture large and below the list of all pictures:\n\n```\n\u003cdiv class=\"gallery-container {{ page.header.class }}\"\u003e\n\t{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"default\",\"slider_scale_mode\": \"fit\"}') }}\n\u003c/div\u003e\n```\n\nThis generates an album where all pictures are displayed as thumbnails and the metadata alt_text is displayed as text at the bottom of the thumbnail:\n\n```\n\u003cdiv class=\"gallery-container {{ page.header.class }}\"\u003e\n\t{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"tiles\",\"tile_enable_textpanel\":true,\"tile_textpanel_title_text_align\": \"center\",\"tile_textpanel_always_on\":true}') }}\n\u003c/div\u003e\n```\n\nWith the gallery_theme parameter you can use any of the layouts/options that you find on the unitegallery page.\n\n# Issues with page caching\nThis plugin uses twig function to add assets (js and css) to the page.\nThis doesn't work very well with Grav caching system.\nThere are two workarounds:\n 1. Disable twig caching for the gallery page.\n    Adding `never_cache_twig: true` to `gallery.md` from example above should do the trick.\n 2. Enabling `assets_in_meta` parameter for this plugin (either per page) or globally.\n    This will save assets calculated during first twig processing and add them\n    each time page is processed. This parameter is enabled by default.\n    After switching it on cache for all gallery pages should be updated (either by cleaning all cache or by doing some changes to affected pages).\n    For best perfomance consider disabling this mode globally and switching it on only for gallery pages.\n    Using the example above `modular.md` should look like this:\n    ```\n    ---\n    title: My Gallery Page\n\n    content:\n      items: @self.modular\n\n    unitegallery:\n      assets_in_meta: true\n    ---\n    ```\n\n# Several galleries in one modular page\nIf several galleries are going to be used on the same page then optional third\nargument should be passed to `unite_gallery` function to create `div` elements\nwith custom ids:\n```\n// with custom div id\n{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"tiles\", \"tiles_type\":\"justified\"}', 'gallery1') }}\n{{ unite_gallery(page.media.images, '{}', 'gallery2') }}\n```\n\nAlso custom id can be set in json options:\n```\n// with custom div id in json options\n{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"tiles\", \"grav_gallery_div_id\":\"gallery1\"}') }}\n```\n\nThis allows to create galleries from several subfolders of modular page:\n\n```\nuser\n|--pages\n   |--page1\n   |--page2\n   |--page_with_gallery\n      |--modular.md\n      |--_photo1\n      |  |--gallery.md\n      |  |--image01.jpg\n      |  |--image01.jpg.meta.yaml\n      |  |--image02.jpg\n      |  |--image02.jpg.meta.yaml\n      |--_photo2\n         |--gallery.md\n         |--image01.jpg\n         |--image01.jpg.meta.yaml\n         |--image02.jpg\n         |--image02.jpg.meta.yaml\n```\n\nTo pass gallery ids from page header `gallery.html.twig` should be modified:\n```\n\u003cdiv class=\"modular-row gallery-container {{ page.header.class }}\"\u003e\n\t{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"tiles\"}', page.header.unitegallery.gallery_id) }}\n\u003c/div\u003e\n```\n\nThen in `gallery.md` files for individual galleries set gallery_id in page header:\n```\n---\ntitle: My fancy gallery\nunitegallery:\n  gallery_id: gallery1\n---\n```\n\n# Gallery in non-modular page\nWhen using gallery in non-modular page gallery theme **must** be set in page header:\n```\n---\ntitle: My fancy gallery\nunitegallery:\n  gallery_theme: tiles\n---\n```\n\nCall to unite_gallery in page template **must** either take theme from page header or not set it at all:\n```\n\u003cdiv class=\"gallery-container {{ page.header.class }}\"\u003e\n\t{{ unite_gallery(page.media.images, '{\"gallery_theme\":\"' ~ page.header.unitegallery.gallery_theme ~ '\"}') }}\n\u003c/div\u003e\n```\n\nIf there are issues with caching assest set ```assets_in_meta: true``` for this page.\n\n# Raw html output with gantry templates\nWhen using gantry gallery.html.twig should be modifed to output correct html (pay attention to `raw`):\n```\n\u003cdiv class=\"gallery-container {{ page.header.class }}\"\u003e\n\t{{ unite_gallery(page.media.images)|raw }}\n\u003c/div\u003e\n```\n\n# Config Defaults\n\n```\nenabled: true\nassets_in_meta: true\ngallery_theme: default\ngallery_div_id: unite-gallery\nthumb_width: 600\nthumb_height: 600\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvariar%2Fgrav-plugin-unitegallery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvariar%2Fgrav-plugin-unitegallery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvariar%2Fgrav-plugin-unitegallery/lists"}