=== EntryWizard ===
Contributors: joanne123,teskeyn, Ilia Tyker
Tags: upload, image, competition, spreadsheet, camera club, photography
Requires at least: 5.0
Requires PHP: 7.0
Tested up to: 6.6.2
Stable tag: 1.3.29
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Uploading by logged-in users of sets of image files and associated data. Administrators design the upload form, and download the images and data.

== Description ==

EntryWizard was developed to cater to the needs of camera club competitions.  In these competitions members may submit multiple images with titles and other data attached.

* Administrators use the software to design web forms, asking for information as text inputs and/or drop-down menu items as well as image files.

* They may set up any number of different "layouts" ( specifications of what information to ask for and what limits to enforce ), assigning an identifier to each.

* Here is **one example** of the sort of rules a layout is able to specify:
    +  Each image must have:
       1. a short title;
       2. a "Category", which must be one of "Nature", "Photojournalism", "Still Life" or "Portrait";
       3. a "Format", which must be one of "Digital", "Slide" or "Print"
    +  Up to 6 entries may be submitted, each with or without a digital version
    +  Any image of type "Digital" must have an uploaded digital version
    +  At most 2 of the 6 images may be in the "Nature" category.
    +  The images must be in jpeg format, with maximum dimensions of 1280 x 1024 pixels, longest dimension no less than 900 pixels, and size no greater than 1M.
* Each webform is given a unique alphanumeric identifier, and this identifier is used within a shortcode to insert the webform in a page or post. Any number of different webforms may be created, and one of the layouts is assigned to each one. Multiple webforms may appear on one page, although currently they have to be submitted individually.

* Each webform separately may be set as "open for upload" or "closed".  If it is open, the shortcode is replaced by the upload form.  If it is closed, the shortcode is replaced by a message saying that the upload is closed.  A closed webform may also be opened temporarily to specified members only, and an open webform may be set to close automatically at a specified time.

* When items have been uploaded, the administrator may either view the items online, or download them. The downloaded image files may be renamed in various ways.  A spreadsheet (in comma-separated .csv format) showing the uploaded data together with some optional information about the users, may also be downloaded.

* The uploaded images may be attached to pre-existing pages for display in a gallery.

* There is a fine-grained permissions system allowing administrators to grant an individual user various levels of control over the webforms and layouts.
  Only logged-in users may see the webform.

* Users of this plugin may also be interested in using Flexishow (https://sourceforge.net/projects/flexishow/) to run a slideshow  using the information in the spreadsheet to select the images displayed.

* EntryWizard has a companion plugin called Ewz-Rating (https://wordpress.org/plugins/ewz-rating/). It is designed for display and online judging of items uploaded via EntryWizard.

= Privacy =
This plugin does not send any data to external servers. It does store in the wordpress database whatever data is requested in the forms designed by the administrator. Viewing of such data using the plugin's shortcodes is always restricted to logged-in users, and is usually further restricted by the administrator.

== Installation ==

* Either
    + Go to Plugins -> Install New and search for EntryWizard.  Click "Install Now".
  Or
    + Download and unzip the file into your plugins folder.

* In the administration area, go to Plugins, look for "EntryWizard", and click "activate".

* The "EntryWizard" links should appear on the administration sidebar.

* **Use With Caching Plugins**: Caching plugins may need to be configured so they do not cache EntryWizard data.  For example, if you are using the "DB Cache Reloaded Fix" plugin, you need to add "EWZ_|ewz_" to the cache filter (where it says "Do not cache queries that contains this input contents").  If you don't do this, users will not get immediate feedback when they upload, but will have to wait for the cache to expire.


= Usage =

* The initial setup comes with two sample layouts and one sample webform.  The sample webform has been assigned the identifier "example".
  To show the sample webform on your page, simply include the shortcode

       **[ewz_show_webform identifier="example"]**

   in the page or post where you wish the form to appear.

* Quickstart for the impatient:

  1. In the EntryWizard->Layouts admin page, click "Add a new layout" with options copied from the sample.

  2. Give it a new title and save it.

  3. In the EntryWizard->Webforms admin page, click "Add a new Webform".  In the new webform:
             * give it a name and an identifier
             * select your newly-created layout
             * click "Open for Uploads"
             * save the webform

  4. Create a new test page, containing
            [ewz_show_webform identifier="xxx"]
     where xxx is the identifier you just created for your new webform.

  5. Now you can experiment, changing the settings for your own layout and webform and checking the effect by reloading your test page. If it turns out badly, delete that layout and start over with a fresh copy of the sample one.  Once you have a layout that makes a good starting point for you, you may delete the sample ones.

* If you are using a plugin such as Cimy User Extra Fields, or S2Member, and wish your spreadsheet to contain some of the extra member information they create,  edit the file "ewz-extra.txt".  Save the result as "ewz-extra.php" in your plugins folder, and activate the new 'EWZ_EXTRA' plugin that it creates.  ( Do not make any changes to ewz-custom-data.php ).  Your code will then not be overwritten by subsequent upgrades to EntryWizard.

* Most items in the EntryWizard admin pages have "help" icons beside them.  Clicking one of these should pop up a window with more detailed information.

* The "layout" governs the appearance of the form in the page. To change the layout of a form, go to the "webforms" page, open the relevant webform and select a different layout.

* To change a layout, or create a new one, go to the "layouts" page. To save you the work of filling out all the details every time, new layouts are first created as copies of existing ones, to be modified as required. It is suggested that you keep the sample layouts for reference until you are comfortable with the software, and then modify the first one to be your "base" layout.

* To open a new webform for upload, go to EntryWizard->Webforms in the Wordpress Admin menu, click on the webform and check "open for uploads".  To open a closed webform for selected individuals only, click "Show user selection list", and select the users.  Then click "Save Changes".

* Logged-in users may now upload images by navigating to the page containing the "ewz_show_webform" shortcode.

* Administrators may download images and/or spreadsheet by going to EntryWizard->Webforms in the Wordpress Admin menu, clicking on the webform and selecting the preferred download option.  Or clicking "Manage Items" takes you to a list of all the images, which you may view, delete, or attach to a page for display in a wordpress gallery.

* EntryWizard saves the images in a special subfolder of the wordpress "uploads" folder.  The image filenames are derived from the user's original filenames in the following way:
    1. All characters except letters, digits, underscores, dashes,  and all periods except the last,  are replaced by '_' ( In the Settings page you may change this to '-', 'X' or 'x'). This ensures the filename is acceptable on most systems.
    2. If the base filename then ends with a digit, another '_' is appended.  This makes extra digits added by Wordpress in the case of duplicate filenames more legible. It also ensures that no filename is totally numeric - Wordpress handles files with completely numeric names differently in some cases.
Administrators may, if required, add a prefix to this filename, or even generate it entirely from information stored on the server.


= How one site makes use of EntryWizard and Ewz-Rating =

* Image Upload
-----------
Images are uploaded using EntryWizard. If we are planning to print the images, they are required to have one dimension at least 2560 px, otherwise the images are required to fit within 1280x1024, which is (was when this was written!) an adequate size for both judging on most monitors and for projecting at meetings.

The layout contains a single-line text input for the title, a drop-down for the category, and usually a checkbox to be checked if a comment is requested.  We get up to 200 images in a competition, so to save work for the judges a maximum of 2 out of the 4 allowed entries may ask for comments.

 A prefix containing the user id and the webform identifier is  set to be applied on upload.  This ensures that all image files for the current year have unique names.

* Download and Preparation
-----------
Because the number of images is large, using the webform download sometimes times out. So the images are usually downloaded using ftp, and the webform download is only used for the spreadsheet itself.

If we are planning to print, the large versions of the images on the server are copied to another place.  The downloaded copies are resized to 1280x1024 and re-uploaded to the upload folder, overwriting the originals. Otherwise, if we are not planning to print, the images are simply downloaded for eventual display at a club meeting.

The rating scheme is set up to show the judges the title and the category, with both using "append to previous column". This helps keep the form narrow enough to display side-by-side with the image on a 1920x1200 monitor.

If there was a "comment requested" checkbox in the original upload, that field is divided among the judges. ( If there was no "comment requested" checkbox, a new "fixed text" field with the text "Comment Required" is created and divided  among the judges. ) The comment input field ( which is a multi-line text input ) is then appended to this field, so "Comment Required" appears immediately above it if a comment is required.  The effect of this is that on any image all judges may add a comment if they wish, and one judge is required to do so.


* Judging
-----------
Each judge is given a (temporary) user account on our website.  We use a "Page Security & Membership" plugin to assign the judges to a group that has access to the page containing the relevant judging form, plus the public  parts of our site, but not to the private sections.

 After the main judging has taken place, if tie-breaking is required, a new page is created.  For each set of tied images, an ewz-rating shortcode is added like this:
[ewz_rating view = "secondary"  identifier="sampleform" item_ids="I1,I2,I3"], where I1,I2,I3 are the wordpress id's of the tied images.
 Any extra inputs required for tiebreaking are added to the rating scheme as "secondary", so they do not display on the main judging page.


* Presentation
-----------
All scores and comments are downloaded to a spreadsheet.  For presentation at a club meeting, this spreadsheet is used with Flexishow (https://sourceforge.net/projects/flexishow/) to drive a slideshow.

After the presentation, a new .csv file is generated from the spreadsheet and uploaded back to EntryWizard using the Webforms->Data Management->Upload Extra Per-Image Data.  The "content" includes the scores and comments for the image.

A new page is created that is limited to logged-in members and contains a "[gallery]" shortcode. Using the Manage Items link on the webform, the images are "attached" to this page, with comments allowed.  This creates an image gallery displaying all the images, with their scores and comments, to which logged-in members may add their own comments.

( The winning images are also displayed in a public gallery that is a little nicer-looking, using other software. )


* For Developers Only
-----------

There are two hooks you may wish to make use of:
      1. ewz_after_upload, which runs on completion of a successful upload. Arguments passed are
         webform_title, user_id, number of new items uploaded, number of existing items updated.
   and
      2. ewz_after_delete_item, which runs after each individual item deletion. Arguments are webform_title and user_id.

Here is some very basic example code:

    function my_after_upload_function( $webform_title, $user_id, $created_count, $updated_count ){
        $userdata = get_userdata( $user_id );
        $email = $userdata->user_email;
        $name = $userdata->display_name;
        error_log("Uploaded to $webform_title by $name ( $email ), $created_count items created, $updated_count items updated");

    }
    add_action('ewz_after_upload', 'my_after_upload_function', 10, 4);
        ( See Wordpress documentation for add_action for the meanings of the last two arguments )


    function my_after_delete_function( $webform_title, $user_id ){
        error_log("1 item Deleted from $webform_title: $user_id");
    }
    add_action('ewz_after_delete_item', 'my_after_delete_function', 10, 2 );


( Also, hooks ewz_before_delete_field, ewz_before_delete_item, ewz_before_delete_layout, ewz_before_delete_webform act are designed for use with Ewz_Rating.  Changes to these may not always be documented. )


== Screenshots ==

1. Setting up the fields for the webform.
2. The webform in action.
3. Error message shown to user ( in a recent version of Firefox ).
4. Downloading the images and spreadsheet.

== Changelog ==
= 1.3.29 =
* Run against the latest version of wordpress 6.9.1
= 1.3.28 =
* Some minor changes required for latest versions of JQuery
* Rearranged controls for Layout and Webform management screens
* Lengthened input for auto-open/close-date to allow for some longer date formats
= 1.3.27 =
* Fix required for new  block themes to make the javascript used in shortcodes work properly.  Not needed for classic themes
= 1.3.26 =
* Allow viewing/editing of user permissions on the Permissions page with edit_users capability.
= 1.3.25 =
* fixed a problem with auto-opening and auto-closing of new, unsaved webforms.
= 1.3.24 =
* Make compatible with PHP7.0. Update not required if you are running PHP7.4
= 1.3.23 =
* fixed some error messages in the Permissions section.
= 1.3.22 =
* Fixed an issue with multi-line text boxes not displaying properly
= 1.3.21 =
* Code cleanup and documentation.
* Only list hidden webforms that the user has permission to see.
* Set width and height of image during batch upload.
* Return to the previous page after editing items in the admin item-list view.
= 1.3.20 =
* made the addition of a terminal underscore to a filename optional
* made compatible with the new version of jquery used by latest wordpress
= 1.3.19 =
* fixed problem with random numbers in prefix when set on download.
* improved view of permissions page on small screens.
= 1.3.18 =
* Fixed: admin can't edit optional data if it was not entered by the user.
* Fixed: an all-items field is uneditable by the user if used in a prefix applied on upload.
* Fixed: "all-items" fields disappear after delete or clear.
* Disabled checking "Apply to all items" for image fields in layouts.
* Minor code improvements and changes to help items
= 1.3.17 =
* own permission instead of list_users
* minor changes to support WordPress 5.5 and PHP 7.4
* minor code improvements
= 1.3.16 =
* Covert entrywizard tables to UTF8 if thwy do not already support it
* Improved handling of invalid characters.
= 1.3.15 =
* Automatic opening of webforms
* Allow any field in the prefix if not applying it on upload
* Improved timezone handling to conform with WordPress 5.3 recommendations
= 1.3.14 =
* In Manage Items view, allow admin to edit data entered by users.
* In Manage Items view, the larger views seen by clicking on the thumbnails all open in the same window.
= 1.3.13 =
* front-end only ready for translation
* option to show title if webform is closed
* optional random number as part of prefix
* fixed possible permission errors on files created
= 1.3.12 =
* Allow a checkbox to be required
* If zip files are being created for downloads, show a "Clean up folders" option on the webforms page bulk options
* optionally set the text for blank selection in a dropdown
* optionally title, caption, content from entrywizard fields when attaching images to pages
* optionally warn when uploading an image that is not sRGB according to it's exif data
* several other minor bugfixes and improvements
= 1.3.11 =
* Fixed initial value of no-selection text in a new field
= 1.3.10 =
* allow an extra "tag" field to be added to an image via a csv upload
* allow setting custom text for the no-selection item in option list
* show a toggle indicator on all postboxes
* css changes that may help with some plugin conflicts

== Upgrade Notice ==
= 1.3.28 =
* Changes for latest version of JQuery, rearranged controls for Layout and Webform management screens
= 1.3.27 =
* Fix required for new  block themes only.
= 1.3.26 =
*  Permissions page viewing.
= 1.3.25 =
* fixed a problem with auto-opening and auto-closing of new, unsaved webforms.
= 1.3.24 =
* Make compatible with PHP7.0. Update not required if you are running PHP7.4
= 1.3.23 =
* fixed some error messages in the Permissions section.
= 1.3.22 =
* Fixed an issue with multi-line text boxes not displaying properly
= 1.3.21 =
* Code cleanup, minor changes to hidden webforms, admin batch upload, admin editing of items.
= 1.3.20 =
* fixed issues with random numbers in prefix and with addition of a terminal underscore to filenames.
= 1.3.19 =
* fixed problem with random numbers in prefix when set on download.
= 1.3.18 =
* Improved handling of all-items fields, several other minor improvements.
= 1.3.17 =
* Support WordPress 5.5 and PHP 7.4, grant own permission to see user data.
= 1.3.16 =
* Covert entrywizard tables to UTF8 if thwy do not already support it. Improved handling of invalid characters.
= 1.3.15 =
* Auto-open, allow any field in  prefix if not applying it on upload
= 1.3.14 =
* Improvements in Manage Items admin view.
= 1.3.13 =
* front-end translation-ready, random number in prefix, option to show title for closed webform.
= 1.3.12 =
* allow required checkboxes, check for sRGB, caption setting when attaching, blank-selection text in dropdown
= 1.3.11 =
* Fixed initial value of no-selection text in a new field
= 1.3.10 =
* Add an optional extra field to an image, possible resolution of some plugin conflicts.
