Retrieve client.js

Defines javascript functions that can be used to validate and submit posts.

The advantage of using these functions versus using the post submission endpoint directly is that
some of the post validation checks can be done on the client side which will be faster.

NOTE: If used, this javascript file MUST be loaded dynamically for each user because the contents
of the file are generated dynamically based on the current user. The file may be cached on a per
user basis based on the HTTP cache headers that are returned when the file is requested (currently
the cache headers specify that the file should expire after one day).

The following functions are available:

window.TN.check_crossposting_restrictions(group_ids)

Checks for crossposting restrictions when the user selects more than one group to post to.

Parameters:

group_ids is an array of group IDs

Returns an object with three properties {allowed, restricted, restrictions}.

allowed is an array of the group IDs from group_ids that can be crossposted to

restricted is an array of the group IDs from group_ids that can't be crossposted to

restrictions is an object mapping group IDs that have crossposting restrictions to arrays of group IDs that are restricted.
It is useful for pinpointing why a group ID shows up in the restricted array so that users can be provided feedback
about the reason for the crossposting restriction (eg. a message like 'group A doesn't allow crossposting to group B').

For example, given group_ids = [1, 2, 3, 4] and assuming group 1 doesn't allow posting to group 3 and group 2 doesn't allow
posting to group 1, the returned object will be:

{allowed: [4], restricted: [1, 2, 3], restrictions: {1: [3], 2: [1]}}

window.TN.submit_post(args, session, preferences, callback)

Submits a new post and performs validation checks on the post before it is accepted for submission.

Parameters:

args is an object containing data about the post being submitted and must include
the following properties:

type: The type of post. One of: offer, wanted

title: A short description of the item(s).

location: A short location description.

The following properties are optional:

content: A longer description of the item(s).

group_ids: An array of group IDs to submit the post to (if any).

fair_offer: If set to 1, the post will be posted with the Fair Offer Policy (only valid for offer posts - see https://trashnothing.com/fair_offer_policy ).

photo_ids: A comma separated list of the IDs of the photos that should be attached to this post.

latitude

longitude

session is a temporary object that is used by submit_post to store data about the submission
process for a single post. The first time submit_post is called with a post, session should
be a new empty object (eg. {}). The session object should be persisted until that post
is successfully submitted and then it can be discarded so that the next post will start
over with a new empty session object.

preferences is a permanent object that the client persists and modifies based on warnings returned
by the post submission process and user input. Some post warnings passed to the callback object
have a preference_key string property so that users can opt out of those warnings in the future.
To save this opt-out preference, set the property indicated by the preference_key in the preferences
object (eg. preferences[preference_key] = 1). The preferences object is only read by submit_post and
never modified - it is up to the client to initialize, modify and persist the preferences object.

callback is a function used to return the result of the post submission. It is called and passed
one argument - an object with five properties {result, message, preference_key, identifier, session}.
The result property is a string that is one of: success, error, warning. The identifier property is
set for errors and warnings and will contain a string that represents the type of error or warning that
occurred.

A success result indicates that the post was submitted successfully. Note that posts may not
appear instantly after submission because the moderators of many groups may have additional
automatic or manual review processes in place that can delay the publishing of a post.

An error result indicates that there is an error with the post to show the user and the message property
will contain text describing the error.

A warning result indicates that there is a warning about the post to show the user and the
message property will contain a string describing the warning. A warning result doesn't prevent a post from
being submitted, to continue the submission process after a warning result, just re-submit the post
(with the updated session object) to temporarily override that specific warning.

Certain types of warnings can be opted out of. These warnings will set preference_key to a string that can be
set in the preferences object by the client to opt out of that type of warning in the future (see the description
of the preferences parameter for more details).

Request

Responses