## Help

### Quick start

1. Create a local directory "test_category".
2. Copy pictures in "test_category".
3. Open an FTP connection to this remote gallery.
4. Upload local directory "test_category" into your remote directory names "galleries". Set authorizations to 777 on directory "galleries/test_category".
5. Connect to your Piwigo as an admin.
6. Go to Administration, Pictures, Thumbnails. Piwigo find the picture from "test_category" without thumbnails. Ask to create thumbnails.
7. Go to Administration, Categories, Synchronize. Check "directories + files" option, uncheck "only perform a simulation" and submit the synchronization.
8. Job's done. You've created a category "test_category" at the root of your gallery.

### Adding elements

- Category directories are in the Piwigo directory "galleries". Here follow the directory tree of a very small gallery (but using many features) :

      .
      |-- admin
      |-- doc
      |-- galleries
      |   |-- category-1
      |   |   |-- category-1.1
      |   |   |   |-- category-1.1.1
      |   |   |   |   |-- category-1.1.1.1
      |   |   |   |   |   |-- pwg_high
      |   |   |   |   |   |   +-- wedding.jpg
      |   |   |   |   |   |-- thumbnail
      |   |   |   |   |   |   +-- TN-wedding.jpg
      |   |   |   |   |   +-- wedding.jpg
      |   |   |   |   +-- category-1.1.1.2
      |   |   |   +-- category-1.1.2
      |   |   |-- category-1.2
      |   |   |   |-- pookie.jpg
      |   |   |   +-- thumbnail
      |   |   |       +-- TN-pookie.jpg
      |   |   +-- category-1.3
      |   +-- category-2
      |       |-- piglet.gif
      |       |-- pwg_representative
      |       |   +-- video.jpg
      |       |-- thumbnail
      |       |   +-- TN-piglet.jpg
      |       +-- video.avi
      |-- include
      |-- install
      |-- language
      |-- template
      +-- tool

- Basically, a category is represented by a directory at any level in Piwigo directory "galleries". Each category can contain as many sub-level as you wish. In the example above, category-1.1.1.1 is at level 4 of deepness.
- Basically, an element is represented by a file. A file can be a Piwigo element if its extenstion is among `file_ext` configuration parameter possibilities (see include/config_default.inc.php file). A file can be a picture if its extension is among `picture_ext` configuration parameter possibilities.
- Picture elements must have an associated thumbnail (see section below about thumbnails)
- Picture elements can have a high quality file associated. As for wedding.jpgin the example above. No prefix on the high quality picture is required.
- Non picture elements (video, sounds, file texts, what you want...) are by default represented by an icon corresponding to the filename extension. Optionaly, you can associate a thumbnail and a representative file (see video.avi in the example above).
- Warning : the name of directories and files must be composed of letters, figures, "-", "_" or ".". No blank space, no accentuated characters
- Advise : a category can contain elements and sub-categories in the same time. Nerverthless, you are strongly advised for each category to choose between category containing elements or category containing sub-categories.
- Once files, thumbnails and representatives are correctly placed in the directories, go to : Administration, Categories, Synchronize

### Thumbnails

- As said earlier, each element of picture type must be associated with a thumbnail.
- Thumbnails are stored in the sub-directory "thumbnail" of the category directory. The thumbnail is a picture (same filename extensions possible than picture files) which filename is prefixed by the configured "Thumbnail prefix" (see admin panel, Configuration, General).
- Thumbnails don't need to have the same extension as their associated picture (a picture with .jpg extension can have a thumbnail in .GIF extention for instance).
- Advise: use an external module for thumbnails creation.
- You can also use the thumbnail creation page (Administration, Pictures, Thumbnails), but it is not recommended. Indeed, thumbnail quality may be poor and it uses a high CPU load which can be a problem if you use free web hosting.
- If you choose to use your hosting provider to create thumbnails, you must give write rights on all category directories and sub-directories "thumbnail" for ugo (user, group, other).

### Access authorization

- You can forbid access to categories. Categories can be "public" or "private". Permissions (for groups and users) can be set only if the category is private.
- You can set a category to private by editing a single category (Administration, Categories, Manage, edit) or by setting options to your whole category tree (Administration, Categories, Properties, Public / Private).

- Once the category is private, you can manage permissions for groups and users through 3 screens :

  - Administration, Identification, Users, permissions action (one link per user)
  - Administration, Identification, Groups, permissions action (one link per group)
  - Administration, Categories, Manage, edit category permissions action (one link per category)

### Users Groups

- Piwigo is able to manage groups of users. It can be very useful to have common permission access for private categories.
- You can create groups in Administration, Identification, Groups and associate users to this group in Administration, Identication, Users.
- A user can belong to several groups. The authorization is stronger than prohibition : if user "jack" belongs to groups "family" and "friends", and that only group "family" can see category "Christmas 2003", "jack" will be able to see "Christmas 2003".

### Files upload by users

Piwigo offers the possibility for users to upload images. in order to do it:

1. authorize upload on any categories (Administration, Categories, Manage, edit or Administration panel, Categories, Properties, Upload)
2. give write rights on directories for ugo (user, group, other)

Files uploaded by users are not directly visible on the website, they must be validated by an administrator. For that purpose, an administrator must go in Administration, Pictures, Waiting in order to validate or to refuse the files proposed, then to synchronize filesystem with database.

### Links between elements and categories, virtual categories

- Piwigo dissociates categories where elements are stored and categories where they are shown.
- By default, elements are shown only in their real categories : the ones corresponding to directories on the web server.
- To link an element to a category, you just have to make the association on the page of element edition (link to this screen on picture.php logged as an administrator) or on the informations of all elements of a category.
- Using this principle, it is possible to create virtual categories : no directory coresponds to this category. You can create virtual categories in Administration, Categories, Manage.

### Miscellanous informations

- As soon as you created your gallery, modify default display properties in Administration panel, Configuration, Default. Indeed, every new registered user will have by default the same display properties.
- If you have any question, do not hesitate to take a look at the forum or ask a question there. The forum (message board) is available on the presentation site of Piwigo. Check the official Piwigo documentation for further reading.