Perfect Example Module: Upload Enumerator
Swift HTML Objective-C
Pull request Compare This branch is 19 commits ahead of shanen21:master.
Latest commit d7dcaaf Oct 19, 2016 @iamjono iamjono committed on GitHub header

README.md

Upload Enumerator

Get Involed with Perfect!

Star Perfect On Github Stack Overflow Follow Perfect on Twitter Join the Perfect Slack

Swift 3.0 Platforms OS X | Linux License Apache PerfectlySoft Twitter Slack Status

This example illustrates how to extract file upload information from a request. The project consists of only a server component which generates HTML that can be viewed in your browser.

Issues

We are transitioning to using JIRA for all bugs and support related issues, therefore the GitHub issues has been disabled.

If you find a mistake, bug, or any other helpful suggestion you'd like to make on the docs please head over to http://jira.perfect.org:8080/servicedesk/customer/portal/1 and raise it.

A comprehensive list of open issues can be found at http://jira.perfect.org:8080/projects/ISS/issues

Quick Start

To use the example with Swift Package Manager, type swift build and then run .build/debug/UploadEnumerator.

To use the example with Xcode, run the Upload Enumerator target. This will launch the Perfect HTTP Server.

Navigate in your web browser to http://localhost:8181/

Server Operations

  1. The server module consists of two relevent files:
    • UploadHandler.swift, within which is the PerfectServerModuleInit function, which all Perfect Server modules must implement, and the UploadHandler class, which implements the PageHandler protocol.
    • index.mustache, which contains the template for the HTML based response data.
  2. When the Upload Enumerator target is built in Xcode it places the resulting product in a directory called PerfectLibraries. When the Perfect Server is launched, it will look in this directory, based on the current process working directory, and load all the modules it finds calling the PerfectServerModuleInit function in each.
  3. When the Upload Enumerator target is built in Xcode it also copies the index.mustache file into the directory named webroot. This permits the file to be treated as the default page for the site.
  4. PerfectServerModuleInit adds a route for the root of the web server, associating with it a closure which will be called to handle each request.
  5. When a request comes in targetting the root of the server, the server will parse the index.mustache file.
  6. The server calls the UploadHandler.valuesForResponse function, which is part of the MustachePageHandler protocol, passing to it the request's MustacheEvaluationContext and MustacheEvaluationOutputCollector objects which contain all the information pertaining to the request. The return value of the valuesForResponse function is a Dictionary object populated with the keys and values used when processing the mustache template. The result of the template processing is the resulting data which will be sent back to the client.
  7. The handler accesses the WebRequest.fileUploads property. This is an array containing one MimeReader.BodySpec object for each file which was uploaded. These BodySpec objects contain the following:
    • field name
    • file name
    • file size
    • file content type (as determined by the browser which submitted the file)
    • local temporary file name
    • the File object containing the locally written file data
  8. The handler iterates over each uploaded file and stores the related information into a dictionary. These dictionary values will be utilized in the mustache template which constitutes the resulting HTML data.
  9. The handler then iterates over all non-file related parameters which were submitted by the browser. The names and values for each parameter are placed in their own dictionaries. In the resulting template, both file and non-file related submissions will be shown.
  10. Finally, the handler adds a dictionary item for the page "title" and returns the resulting dictionary from its valuesForResponse function.
  11. The index.mustache template first iterates over the supplied {{#files}} elements, outputting each piece of uploaded file related data into a table. It then iterates over the non-file {{#params}} and prints them in a list. The resulting completed HTML data is then returned to the browser.

Further Information

For more information on the Perfect project, please visit perfect.org.