Files and Mail

A form can take a file, a page can hand one back, and an action can send e-mail. projects/helpdesk uses all three: tickets with an attachment, a mail to the support team and to the requester.

Taking a file

Declare the file as a param of the action. accept and maxsize are rules like minlength: a file that breaks them never reaches the action, and the form shows why next to the field.

<q:action name="open" method="POST">
  <q:param name="title" required="true" minlength="5" />
  <q:param name="attachment" type="file" maxsize="5MB" accept=".png,.jpg,.pdf" />

  <q:if condition="attachment">
    <q:file action="upload" file="{attachment}" result="saved" />
    <!-- saved.filename, saved.original_filename, saved.size, saved.mimetype -->
  </q:if>
  <q:redirect url="/" flash="Ticket opened: {title}" />
</q:action>

<ui:form on-submit="open" submit="Open ticket">
  <ui:input bind="title" />
  <ui:input bind="attachment" />
</ui:form>

The form knows the action takes a file: it posts multipart/form-data, and attachment is a file input offering .png,.jpg,.pdf. You write neither.

The file is saved under paths.uploads (./uploads unless the config says otherwise), with a safe name; destination="invoices" puts it in a folder inside it. Keep saved.filename — it is how you find the file again.

q:file action is upload, delete or send (below); anything else does not parse:

<q:file action="copy" file="{attachment}" />

Error: <q:file action="copy">: use upload, delete or send

A multi-line field is <ui:input bind="description" rows="6" />.

Handing a file back

Uploads are not served as static files: anyone with the URL could read them. A page sends one, and decides who may have it:

<!-- components/attachment/[id].q -->
<q:component name="Attachment">
  <q:query name="ticket" datasource="db">
    SELECT attachment, attachment_name FROM tickets WHERE id = :id AND attachment IS NOT NULL
    <q:param name="id" value="{id}" type="integer" />
  </q:query>
  <q:if condition="ticket_result.recordCount == 1">
    <q:file action="send" file="{ticket[0].attachment}" name="{ticket[0].attachment_name}" />
  </q:if>
  <p>There is no attachment for ticket #{id}.</p>
</q:component>

q:file action="send" ends the page with the file as a download. The stored name comes from the database, never from the URL; a path outside paths.uploads is refused, and a missing file answers 404. Put a guard on the page (require_auth, or a q:if with q:redirect) and only the right people get it.

Sending mail

An action sends a message with q:mail; the server is the mail: section of quantum.config.yaml. From the recipe Mail in development, tested as shown:

<q:component name="Contact">
  <q:action name="send" method="POST">
    <q:param name="email" type="email" required="true" />
    <q:param name="message" required="true" minlength="5" />
    <q:mail to="support@example.com" reply_to="{email}" subject="Contact from {email}" type="text">{message}</q:mail>
    <q:redirect url="/" flash="Thanks! We will answer {email}." />
  </q:action>

  <h1>Contact us</h1>
  <q:if condition="flash"><p class="flash">{flash}</p></q:if>
  <form method="POST" action="/?action=send">
    <input name="email" type="email" />
    <textarea name="message"></textarea>
    <button>Send</button>
  </form>
</q:component>

# Recipe: mail in development. `host: log` writes each message to the log
# instead of sending it; set SMTP_HOST in production and the same page sends.
paths:
  components: ./components

mail:
  host: ${SMTP_HOST:-log}
  from: support@example.com

host: log writes each message to the log instead of sending it — use it in development. Without a mail: section, q:mail is an error that says so; it never pretends to send:

<q:mail to="ana@example.com" subject="Welcome">Hello, Ana!</q:mail>

Error: q:mail needs a mail server

When the server says no

A message the server does not take stops the action with the server's reason. When the rest of the action must happen anyway, say onerror="continue" and check <name>_result.success — from the recipe When the mail server says no, where the order is saved even when its confirmation cannot be sent:

<q:component name="Order">
  <q:action name="order" method="POST">
    <q:param name="email" type="email" required="true" />
    <q:param name="item" required="true" />
    <q:query name="saved" datasource="db">
      INSERT INTO orders (email, item) VALUES (:email, :item)
      <q:param name="email" value="{email}" type="string" />
      <q:param name="item" value="{item}" type="string" />
    </q:query>

    <!-- onerror="continue": a refused message does not undo the order -->
    <q:mail name="confirmation" to="{email}" subject="Your order: {item}"
            type="text" onerror="continue">We received your order for {item}.</q:mail>

    <q:if condition="confirmation_result.success">
      <q:redirect url="/" flash="Ordered {item}. A confirmation is on its way." />
    </q:if>
    <q:redirect url="/" flash="Ordered {item}. We could not send the confirmation e-mail." />
  </q:action>

  <h1>Order</h1>
  <q:if condition="flash"><p class="flash">{flash}</p></q:if>
  <form method="POST" action="/?action=order">
    <input name="email" type="email" />
    <input name="item" />
    <button>Order</button>
  </form>
</q:component>

The helpdesk (projects/helpdesk) does the same: it saves the ticket first and says, in its message, when a mail could not be sent.

Rules

FILE-1, FILE-2, MAIL-1, MAIL-2 and UI-14 in the SPEC.