Set up Gallery Pro

After viewing the examples in the Gallery Pro introduction, follow these steps to prepare your photos and hosting. You do not need to understand the code or type commands in a terminal; copy the supplied snippets into the specified fields. See Settings and photo information for the settings tables.

Requirements

In your hosting control panel, open the PHP settings or PHP version selector for the domain, select a version from PHP 8.3 through 8.5, and save. The screen names vary by provider. You do not need to install PHP on your Mac.

To upload photos and check folders, use your hosting provider's File Manager or your usual FTP client. This guide uses a browser-based file manager as the example. For provider-specific screens and instructions, see the official hosting guides.

Detailed server requirements

Item	Requirement or purpose
Blocs	A Bric for Blocs 6 for Mac
PHP	Supports PHP 8.3 through 8.5; operation on PHP 8.6 RC has also been confirmed
mbstring	Processes text in photo metadata
EXIF extension	Reads shooting details and identifies image formats
GD	Generates thumbnails; support for the image formats you use is also required
Write access	Creates and updates thumbs/ and the catalog cache within the photo folder
Apache	Individual photo URLs require mod_rewrite and permission to use rewrite rules in .htaccess
JavaScript	Displays and controls the gallery and lightbox in the browser

The examples below publish the gallery page at /gallery/ and store photos under /_gallery/. Blocs places the required files in includes/ and other folders when exporting or publishing. These examples do not cover installing the entire site in a subdirectory such as /portfolio/. The current initialization code references /includes/gallery-pro.php on the published site.

Whether you can use .htaccess depends on your hosting configuration. Apache requires AllowOverride FileInfo, or the corresponding AllowOverrideList setting, to permit rewrite directives. If you cannot configure this, contact your hosting administrator. See the official Apache documentation.

Setup

1. Plan your photo and file locations

This example uses works as the photo album folder and gallery as the folder for the published gallery page. These are separate settings.

(document root)/
├── .htaccess                  ← Set in Blocs Hypertext Access
├── includes/                  ← Publish uploads automatically
│   ├── gallery-pro.php
│   └── gallery-pro-ogp.php
├── js/                        ← Publish uploads automatically
│   └── gallery-pro.js
├── css/                       ← Publish uploads automatically
│   └── gallery-pro.css
├── _gallery/                  ← Create this folder
│   └── works/                 ← Create; PHP must be able to write here
│       ├── Example Photo.jpg  ← Upload your photos
│       ├── Another Photo.jpg
│       └── thumbs/            ← PHP creates automatically
│           ├── Example Photo.jpg
│           └── .catalog.json  ← Images and catalog are generated
└── gallery/
    └── index.php              ← Set page to PHP in Blocs; Publish

The highlighted rows indicate items you configure or prepare yourself. Configure .htaccess in Hypertext Access in step 4 and enable Htaccess Production Mode so that Publish uploads it. Blocs also publishes index.php after you set the page to PHP and paste the code in step 3.

The diagram shows only the relevant files on the published site. Placing the Bric automatically registers its required files in Blocs. The Gallery Pro files in includes/, js/, and css/ are then uploaded with the site during normal publishing. You do not need to create these folders or find the files inside the Bric and upload them manually.

PHP automatically creates thumbs/, its thumbnails, and .catalog.json when you open the published page. Normally, you do not need to create thumbs/ in advance or change its owner. PHP must be able to write to its parent folder, works/. If storage fails, follow the next section, “Check the photo folder and write permissions.”

You prepare /_gallery/works/ and the photos, paste the PHP into Page Settings, and configure .htaccess for photo URLs. Upload the photos separately, since Gallery Pro reads them from a folder on the server.

Upload photos directly into /_gallery/works/. The Bric does not recursively scan subfolders to create albums. Supported image formats are JPEG, PNG, GIF, and WebP. If you want to display shooting details, JPEGs that retain the required metadata make this easier to check.

The filename without its extension is also used as the photo ID. For Example Photo.jpg, the URL ends in Example-Photo. The current code converts hyphens in URLs back to spaces. Separate words in the original filename with spaces, and avoid filenames containing actual hyphens or photos whose names differ only by extension.

Check the photo folder and write permissions

Gallery Pro stores small preview images (thumbnails) and a record of the photo listing on the server. PHP therefore needs write access to the photo folder. Prepare the folder as follows.

1. Open File Manager in your hosting control panel.
2. Open the domain's document root. Common folder names include public_html and www, but use the location specified by your provider.
3. Use Create Folder or New Folder to create _gallery, then create works inside it. If these folders already exist, use them.
4. Open works and use Upload to add your photos.
5. Select works and open Properties, Permissions, or Change Permissions from its context menu or toolbar. If the newly created folder already uses your provider's recommended permissions, leave them as they are.

Permissions are commonly represented by three digits that specify who can read and write. If your provider does not specify values, the following are general reference values. Follow your provider's recommendations when available.

Item	General reference	What to check
The _gallery, works, and generated thumbs folders	755	Owner: read, write, execute; group and others: read, execute
Photos, .htaccess, and regular PHP files	644	Owner: read, write; group and others: read

If the interface accepts numeric values, check one item at a time and change it only if necessary, then save. Do not select Apply to Subfolders or Recursive. You do not need to apply folder permissions to all photos and PHP files. Consult your provider's official guide below for its interface and recommended values.

These instructions assume PHP runs as the owner of the photo folder. In that case, changing ownership is normally unnecessary. On some servers, PHP runs as a different user, and setting 755 alone does not grant write access. Shared hosting does not automatically mean that an ownership change is either required or unnecessary. If the storage check below fails, contact your provider before changing permissions to 777 or attempting to change ownership yourself.

For provider-specific screens and PHP settings, see the official hosting guides.

Check storage after publishing

1. After completing the Blocs settings and publishing described below, open the gallery page in a browser. Include at least one JPEG with a long edge greater than 400px so that you can also check thumbnail generation.
2. Return to File Manager, open _gallery → works, and refresh the listing.
3. Open the automatically created thumbs folder and check that small images and .catalog.json have been saved. If .catalog.json is not visible, enable Show Hidden Files or Show Dotfiles. You do not need to create or edit these generated files yourself.
4. When you add photos, reload the gallery page to update the listing. In some cases, such as when the original image is 400px or smaller, the original is used without creating a separate thumbnail.

If the warning “サムネイルを保存できません。” (thumbnail storage failed) appears, or thumbs and .catalog.json are not created, you can send the following message to your hosting provider's support team. Replace works if you use a different folder name.

I am setting up a PHP photo gallery. PHP needs to create a thumbs/ folder inside _gallery/works/ under my document root, then save images and .catalog.json inside it. Saving currently fails. Please advise which ownership and permission settings allow PHP to write there, and how to change them on my hosting plan.

2. Place Gallery Pro in Blocs

Place Gallery Pro in the body of the page where you want the photos to appear. Unlike Math Renderer and Code Highlighter, it does not belong in a dedicated Bloc that simply holds extensions. Give the photo listing the width and spacing it needs.

Enter works in Source → Path. Specify the folder relative to _gallery/, rather than the full /_gallery/works/ path. Select Layout and adjust the columns, spacing, and captions as needed.

The required files are automatically added to Attachments when you place the Bric. You normally do not need to register attachments manually. To check them, see Check attachments below.

The Blocs editing canvas displays a configuration banner. View the actual photos in a preview that can access PHP, or on the published site. If your preview refers to photos on the published server, set the Base URL in Project Settings to match that site.

Using multiple Gallery Pro instances on one page

You can place multiple Gallery Pro instances on one page, as in the demo. When you click a photo, the lightbox uses the photo listing and lightbox settings of the gallery you clicked.

However, a photo URL does not identify which Gallery Pro instance should open it. If several instances display the same photo, opening that URL directly or reloading it selects the first instance. Consequently, even if you copy a photo URL from the second or a later gallery, the recipient sees it with the first gallery's settings.

More precisely, the Bric uses the first Gallery Pro instance containing the requested photo ID. Avoid duplicate photo IDs when placing different albums on the same page as well. For a layout comparison, place the Gallery Pro instance whose appearance you want for direct photo URLs first.

3. Set the page to PHP and add code before the doctype

Paste the PHP into the Code section of Page Settings. Follow these steps.

1. In Blocs, display the page where you will place Gallery Pro.
2. Choose Page → Settings from the menu bar. The keyboard shortcut is ⌥⌘P.
3. Open General in Page Settings (the leftmost sliders icon) and select PHP from the File Type list. This example publishes the exported page as /gallery/index.php.

Figure 1: Select PHP from File Type.

4. At the top of the same Page Settings window, click Code (the </> icon).
5. Open the list above the code field and select Before <!DOCTYPE>.

Figure 2: Select Before <!DOCTYPE> to insert the code at the start of the page.

6. Use the copy button at the top right of the following code block, then paste it into the Page Settings code field. Copy all three lines, from <?php through ?>. If the field is empty, this is all you need to add. If other code is already present, keep it and add this code alongside it.

<?php
require $_SERVER['DOCUMENT_ROOT'] . '/includes/gallery-pro-ogp.php';
?>

7. Check the pasted code and confirm that the list shows Before <!DOCTYPE>. Click Done at the bottom right, then save your Blocs project.

Figure 3: The PHP has been pasted. Select Code at the top, set the insertion point to Before <!DOCTYPE>, and finish by clicking Done.

Apply this setting to each page that uses Gallery Pro. Paste the code only once per page, even if that page contains multiple Gallery Pro instances.

Using Code Editor from the Window menu

Blocs also has a separate Code Editor window. Open it with Window → Code Editor in the menu bar. Select Page - Before <!DOCTYPE> from the insertion point list at the top right to edit the same location for the current page. If you already pasted the code in Page Settings above, do not paste it again.

Figure 4: The list in Window → Code Editor. Select Page - Before <!DOCTYPE> for the current page.

What the added PHP does and where it appears in the export

The exported file uses this order:

<?php
require $_SERVER['DOCUMENT_ROOT'] . '/includes/gallery-pro-ogp.php';
?>
<!DOCTYPE html>

This code loads /includes/gallery-pro-ogp.php from the document root. When someone opens a photo URL directly, it adds the photo title, image URL, and related information to the social sharing metadata, and makes images and CSS load from the correct locations. Configure the social card for the gallery as a whole under Social Cards in Blocs Page Settings.

With this setup, the PHP you paste is the same whether the gallery page is at /gallery/, /photos/, or /ja/gallery/. Set the paths in .htaccess to match the actual page location. Reusing one language's page under another language's URL requires additional configuration specific to your site.

4. Add photo URL rules to .htaccess

To make photo URLs open directly, add a short configuration in Blocs Hypertext Access. The following example publishes the gallery page at /gallery/.

1. If the site is already live, open the document root in your hosting file manager, enable Show Hidden Files if needed, and look for .htaccess. If it exists, download a backup and check its contents.
2. In the Blocs menu bar, choose Window → Code Editor, then select Hypertext Access - htaccess from the insertion point list. It is the last item in the list shown in Figure 4.
3. Copy the code below and paste it into the editor. Keep any existing code. Include any required settings that currently exist only on the server so that they are not lost when publishing. If you have rules for another application such as WordPress, or rules that apply to the whole site, ask your provider where to insert the new rules. Put the gallery rules before rules that send all requests to another page or provide a 404 fallback.
4. In Project Settings (⌘,), open Export, enable Htaccess Production Mode, and save the project. The next Publish operation will upload the file as .htaccess.
5. After publishing, open a photo and reload its URL to check that the same photo opens.

When Htaccess Production Mode is disabled, Blocs exports the file as htaccess.txt. The photo URL rules do not take effect under that filename. When you enable the mode and publish, Blocs makes a timestamped backup of the existing .htaccess and replaces it with the new contents. Existing settings are not merged automatically, so retain the required contents in step 3. See the official Blocs settings guide.

RewriteEngine On

# Keep photo URLs in the address bar and serve the gallery PHP page.
RewriteCond %{DOCUMENT_ROOT}/gallery/index.php -f
RewriteRule ^gallery/p/([^/]+)/?$ /gallery/index.php?p=$1 [B,L,QSA]

For example, the following public URL is handled internally:

Public URL: https://example.com/gallery/p/Example-Photo
PHP target: /gallery/index.php?p=Example-Photo

The photo URL remains in the browser's address bar. This is an internal rewrite, not an HTTP redirect to another URL.

What each part of the URL rules means

Setting	Meaning
RewriteCond ... -f	Applies only if the target gallery/index.php exists
^gallery/p/([^/]+)/?$	Matches one photo slug after /gallery/p/; the trailing slash is optional
p=$1	Passes the photo slug to PHP
B	Escapes the captured text before inserting it into the target
L	Stops processing further rules in this rewrite round
QSA	Preserves query parameters from the original URL

See the official Apache documentation for the flags. Since p selects a photo, do not also use it as a query parameter for another purpose.

If you place the page at /photos/, change all three occurrences of gallery in the rules above to photos. This is independent of the album name in /_gallery/works/ and Source → Path. If the gallery page is at the document root itself, use the following rules instead. You do not need to paste both the folder and root versions.

RewriteEngine On

RewriteCond %{DOCUMENT_ROOT}/index.php -f
RewriteRule ^p/([^/]+)/?$ /index.php?p=$1 [B,L,QSA]

5. Publish from Blocs and check the result

Choose Publish from the export menu at the top right of Blocs and publish to your configured hosting server. This transfers the page and Gallery Pro attachments together. For your first SFTP publication, the official guide recommends selecting Full Site to transfer all required files. See the Blocs publishing guide for the steps, including connection settings.

Once publishing is complete, check the following.

1. Open /gallery/ and check the photo listing and layouts.
2. Click a photo and check the lightbox, photo information, and navigation between photos.
3. Check that the address bar changes to a photo URL such as /gallery/p/Example-Photo.
4. Open that URL directly in a new tab and reload it to check that the same photo opens.
5. In File Manager, check that images and .catalog.json have been created in the photo folder's thumbs/ directory. See “Check storage after publishing” above for details.
6. Share a photo URL on a social platform and check that its title and image appear.

Checking the social metadata in HTML

Open a photo URL and check that the server's HTML response contains all four required Open Graph properties. The values of og:title, og:image, and og:url correspond to the photo, and og:type is website. Social crawlers may not execute JavaScript, so inspecting only the DOM after the page has loaded in a browser is not sufficient. If needed, ask the person responsible for your website to perform this check.

Check attachments

The required files bundled with the Bric are automatically registered as Attachments when you place it. The official Blocs Custom Bric Structure guide explains that they are registered as Project or Page attachments depending on whether the Bric is placed in a Global Area or the regular page area.

Bric location	Automatically registered as	Where to check
Regular page area (page-local)	Page Attachments	Paperclip icon in Page Settings
Global Area	Project Attachments	Paperclip icon in Project Settings

Check from the sidebar

1. Select Gallery Pro in the editor.
2. Look for the green Page Attachments field in the right sidebar. Gallery Pro registers four required files.
3. Click View to open the list of registered files.

Figure 5: Gallery Pro placed in the regular page area. Click View to check the attachments.

The following four files appear as Gallery Pro Bric attachments. If they are already listed, you do not need to add them with the + button.

File	Purpose
gallery-pro.js	Displays and controls the photo listing and lightbox
gallery-pro.css	Styles the gallery and lightbox
gallery-pro.php	Retrieves the photo listing and metadata from the server
gallery-pro-ogp.php	Generates social sharing metadata and related information for individual photo URLs

Figure 6: The attachment list in Page Settings. Gallery Pro's four files are registered automatically. Files from other Brics on the same page also appear here.

To check directly from Page Settings, open Page → Settings and click the paperclip icon (File Attachments) at the top.

Brics placed in a Global Area

Files for Brics in a Global Area are registered as Project Attachments. Open Project Settings (⌘,) and click the paperclip icon at the top to check them.

Figure 7: An example of Project Attachments. This screenshot lists files for Navbar Pro and other Brics used in a Global Area.

Automatic registration and folders on the published site

The Bric also contains an internal folder called includes/, but you do not manually copy that entire folder. Blocs places attached JavaScript in the published js/ folder, CSS in css/, and PHP in includes/. These files are included in normal export and Publish operations. See the official Blocs Project Attachments explanation.

Registering a PHP file as an attachment and loading that PHP at the start of the page are separate actions. Manual file registration or individual uploads are unnecessary, but you still need to paste the code into Page Settings → Code → Before <!DOCTYPE> as described in step 3, and configure the photo URL rules in .htaccess.

Troubleshooting

Symptom	What to check first
No photos appear	Check that photos are in _gallery/works/ on the server and the Bric's Path is works
“Gallery could not be loaded.” appears	Check PHP settings, automatic registration in Attachments, the Blocs Publish result, and the hosting error log
“サムネイルを保存できません。” (thumbnail storage failed) appears	Check the photo folder's permissions and ownership; send the support message above to your provider
Clicking works, but reloading a photo URL returns 404	Check the .htaccess location and that gallery in the rules matches the published page location
The entire page returns a 500 error after setup	Restore the .htaccess backup from before editing and check the page; ask your provider about the insertion location and PHP settings
Opening a URL shows a different layout	Check whether several Gallery Pro instances use the same photo; a direct URL opens in the first matching instance

Back to Gallery Pro / Settings and photo information