/guide

Mollom client implementation guidelines and examples

Primary LanguagePHP

Mollom client implementation guidelines

Entities

  • Mollom session
    • entity_type VARCHAR(32), entity_id INT
      • Or whatever is suitable for your app; required to map a contentId or captchaId to a locally stored entity.
    • content_id VARCHAR(32) NULL
      • Text analysis only.
      • Note: Certain database engines/drivers care for case-sensitivity (e.g., Postgres); for maximum compatibility use content_id instead of contentId.
    • captcha_id VARCHAR(32) NULL
      • Only exists when a post involved a CAPTCHA in any way.
      • Note: Certain database engines/drivers care for case-sensitivity (e.g., Postgres); for maximum compatibility use captcha_id instead of captchaId.
    • created INT(11)/DATE NOT NULL DEFAULT NOW()
      • Used to prune out obsolete session data older than 6 months.

Terminology

  • CMP: Content Moderation Platform
  • Form flow: Basic assumed form workflow stages:
    1. Form construction (initial; no user input)
    2. Form validation (user input, possibly throwing errors that cause the form to be re-rendered)
    3. Form submission (only reached if there are no validation errors)

Form elements

  • Content ID, commonly contentId or mollom[contentId].

  • CAPTCHA ID, commonly captchaId or mollom[captchaId].

  • Honeypot field

    • Wrap the text input element in a container with a CSS class that gets display: none; applied.
    • Use an "attractive" name for the input element; e.g., name="mollom-homepage" or name="mollom[homepage]".

  • Mollom privacy policy link

      By submitting this form, you accept the <a href="//mollom.com/web-service-privacy-policy" target="_blank" rel="nofollow">Mollom privacy policy</a>.

Form flows

Text analysis

  1. On form construction:
    • --
  2. On form validation:
    1. Check (unsure) CAPTCHA, if a CAPTCHA ID was submitted.
      • Regardless of whether the solution is empty.
    2. Check content (using submitted content ID, if any).
    3. Output new content ID as hidden form input value.
    4. React to spamClassification:
      • spam: Throw form validation error (blocking submission).
      • unsure: Retrieve + output CAPTCHA associated with contentId + throw form validation error (blocking submission).
      • ham: Accept post
        • Remove the CAPTCHA ID from the form's HTML markup to not re-trigger the CAPTCHA validation again.
  3. On form submission:
    1. Store MollomSession data locally, including entity type + ID mapping.
    2. If CMP integration is enabled, mark content as stored + provide meta/context info:
      • stored=1
      • url=http://example.com/articles/123#comment-456
      • contextUrl=http://example.com/articles/123
      • contextTitle=Article title

CAPTCHA-only (discouraged)

  1. On form construction:
    1. Retrieve a new CAPTCHA.
    2. Start local session to store CAPTCHA ID + URL with solved=0 + url=http://...
    3. Disable page caching + ensure to send proper HTTP headers to notify reverse-proxies.
    4. Output CAPTCHA + CAPTCHA ID as hidden form input + solution text form input element.
  2. On form validation:
    1. Check CAPTCHA solution using submitted CAPTCHA ID.
    2. Output new CAPTCHA ID as hidden form input value.
    3. React to solved:
      • 0: Throw form validation error (blocking submission) + output CAPTCHA again.
      • 1: Accept post.
  3. On form submission:
    1. Store MollomSession data locally, including entity type + ID mapping.