Expand your Youtube tutorial series and docs to cover more of the basic setup and features

[MaximilianKohler]

I shouldn't have to spend hours searching and reading on how to set up basic email functionality for example. If something this essential and basic is this poorly documented, I can only imagine how much worse it will be for Xenforo's dozens of other features.

I am watching all of your tutorials (many hours long) https://www.youtube.com/@XenForo. They are insufficient.

When I do a web search for "xenforo setup email" or "xenforo setup email amazon ses" I get dozens of low-quality results. The official documentation https://xenforo.com/docs/xf2/options/#email is useless.

The info you mentioned on the options/groups/emailOptions/ page is insufficient. For example, I have lots of questions:

1. The difference between default email & contact email isn't clear.
2. Bounced email address and Unsubscribe email address setup, importance, use examples.
3. Automated bounced email handler - I understand that we should set up a unique gmail account (bounces234324@gmail.com) just for this, and that's the ONLY way it will work?
4. Automated unsubscribe email handler - we have to create another gmail account (unsubsmyforum93843@gmail.com) just for this, and that's the ONLY way it will work?

ALL email software (Listmonk, Sendy, Mailwizz, etc.) have built-in communication with Amazon SES & SNS (and all other SMTP providers) to process bounces & complaints easily and automatically. Given that Xenforo is a relatively expensive paid option, there's really no excuse for it to be missing this essential integration.

Having to create multiple new gmail accounts solely dedicated to processing bounces & complaints seems really bizarre.

Someone has already done most of the work for you https://xenforo.com/community/resources/amazon-ses-bounces-support.8319/ but they're not maintaining it and it has problems which arguably make it not viable currently.

EDIT:

5. Say I set up two new gmail accounts for bounces & unsubs. Then what? Under "Automated bounced email handler" how do I configure that to work with the new accounts? There are no instructions that I can find anywhere on the internet for this.

FYI, I'm coming from Reddit. A lot of other communities might be interested in doing the same thing, given major recent upheavals over there. I think it's in your interest to make the switch as easy as possible for us. Reddit is free and easy. So far, Xenforo is neither.

 

[MaximilianKohler]

A related request would be to provide some level of support/guarantee for some of the addons people make https://xenforo.com/community/resources/categories/add-ons-2-x.44/

For example, some of them perform essential functions, and if the addon stopped working it would be a major disruption to our forum.

The SES addon I linked in the OP for example. Xenforo devs should be paying attention to the status of those types of addons and jump in to keep them working (or integrate them directly into Xenforo) when the maintainer cannot.

 

[Jeremy P]

The default email address is the address emails are sent from. The contact email address is the address "contact us" emails are sent to.

I use regular SMTP for SES, which supports unsubscribe and bounce handling without an add-on. It does require separate email accounts for processing (they don't have to be Gmail -- any POP3/IMAP provider is fine). You enter the credentials in the handler options and it checks the inboxes periodically for incoming bounce/unsubscribe messages. The built-in options follow published standards which should work for any provider, but it would be nice to integrate more deeply with the propriety options from common providers.

If you wish to use Gmail inboxes, I think you'd need to use the Google OAuth option for authentication.

 

[MaximilianKohler]

This can be expanded to the developer documents as well https://xenforo.com/docs/dev/designing-styles. They were referenced to me as a way to implement these changes: https://xenforo.com/community/threads/edit-templates-in-file-system.134635/post-1635445. But I'm stuck on step 2 "Enabling designer mode for a style". I edited the src/config.php file, and the next step is referencing a CLI. What CLI? Has a new CLI been activated in the "admin.php?tools/" or "admin.php?appearance/" etc.? No, I don't see any. Is it our server CLI (Putty, etc.)? No, the command doesn't work there.

php cmd.php xf-designer:enable dark1 designdark1
Could not open input file: cmd.php

 

[TPerry]

and the next step is referencing a CLI. What CLI? Has a new CLI been activated in the "admin.php?tools/" or "admin.php?appearance/" etc.? No, I don't see any. Is it our server CLI (Putty, etc.)? No, the command doesn't work there.

Errr... most that have been around computers for any length of time realize that CLI references Command Line Interface... it's not a web interface. And for those that aren't aware of what it means... they probably don't need to be futzing around where they are trying to play.

And generally.. when attempting to call a file, you either have to provide the path to it, or if you are actually IN the directory you need to be in at least placing ./ in front of the call of the file to specify it is from the current directory and not somewhere on the path.

Most of those guides expect a minimum of knowledge to be present by those using them.

 

[MaximilianKohler]

You could easily integrate a CLI on the admin page.

Most of those guides expect a minimum of knowledge to be present by those using them.

Yes, in my opinion they expect too much and should be made more user-friendly. If we're to run the command from a specific folder, it should tell us which one.

We enable designer mode on a style by using the CLI and specifying the style ID of the style

It should tell us how to find the style ID.

I'm trying to change the title character limit to 300. It seems unlikely that would apply only to a single style, but if so, then I should be changing the default style. I don't know what its ID is. I created a style called Dark1, but I don't know if that name is also the "style ID".

Once these questions are answered I think the rest of the page is fairly intuitive.

 

[TPerry]

It seems unlikely that would apply only to a single style, but if so, then I should be changing the default style.

I don't think that limit is "style" specific... but actually coded into the underlying PHP code, requiring modification of it via a separate bespoke add-on to change it... and that expects an existing level of knowledge.

 

[MaximilianKohler]

That's what I would think as well. Someone shared the code & file to edit https://xenforo.com/community/threa...r-forum-title-limit.13160/page-2#post-1309965 but after editing it I couldn't get the changes to go live https://xenforo.com/community/threads/increasing-the-150-character-forum-title-limit.215208/

I was pointed to that docs page here https://xenforo.com/community/threads/edit-templates-in-file-system.134635/

 

[TPerry]

Ergo my comment about extending it via an add-on and that expects a certain level of existing competency.
Modifying style/template issues is totally different than modifying/extending the core PHP code.

 

[Jeremy P]

The developer documentation (and CLI tool) is primarily aimed at add-on developers and style designers running local installations, and the start page does introduce the CLI tool as something which should be run from the XF root directory. For production installations, editing templates should be done via the control panel. However, none of the instructions to increase the node length limit ask or require template edits anyway.

 

[MaximilianKohler]

By the way, @Jeremy P @Chris D @Kier a lot of redditors are like myself, currently looking for a valid alternative due to the major upheaval over there. I think you guys could get a lot of new business if you made a simple guide for porting communities from reddit to Xenforo. I've struggled a lot with it, and have yet to find/figure out the necessary customizations. If I can get everything up and running, and if you're not interested in creating such a guide, I'll make a post with what I did to share with people looking for reddit alternatives.

Besides the titles differences/issues, another missing feature that stands out to me is differentiating between a user's posts and comments on their profile page https://xenforo.com/community/members/maximiliankohler.264823/#recent-content. I think this would be a good reddit-like feature to implement.

 

[MaximilianKohler]

Another example is importing styles. The docs don't even have a section for "importing styles". https://xenforo.com/docs/xf2/styles/

I was trying to import styles and was getting an error https://xenforo.com/community/threa...util-file-php-at-line-281.156584/post-1635500.

They are being imported and activated but the /home/nginx/domains/forum.mysite.com/public/styles folder is empty and the docs don't cover which folder imported styles get put into.

 

[Jeremy P]

You generally just select the XML or archive file and press the import button. Styles requiring anything beyond that should come with instructions of their own. If it doesn't work out of the box then it's almost certainly due to server misconfiguration. We do try to check and display warnings about common issues but it's impossible to anticipate how every given server may have been set up.

Style data (most data, really) is stored in the database and not directly on the filesystem.

 

[MaximilianKohler]

If you wish to use Gmail inboxes, I think you'd need to use the Google OAuth option for authentication.

I'm going through the steps and the "explain" link at the top doesn't work:




I did everything to the best of my ability and got this error:
Access blocked: This app’s request is invalid

myforumbounce23434@gmail.com
You can’t sign in because this app sent an invalid request. You can try again later, or contact the developer about this issue. Learn more about this error
If you are a developer of this app, see error details.
Error 400: redirect_uri_mismatch

Error details:

Error 400: redirect_uri_mismatch
You can't sign in to this app because it doesn't comply with Google's OAuth 2.0 policy.
If you're the app developer, register the redirect URI in the Google Cloud Console.
Request details: redirect_uri=https://forum.mysite.com/admin.php?misc/email-oauth-setup

This is way too difficult to set up without any tutorial.

 

[TPerry]

This is way too difficult to set up without any tutorial.

Unluckily... some aspects actually require a working knowledge.
The issue you show is readily apparent to be an error in your App setup not matching the domain that is trying to connect.

 

[MaximilianKohler]

Unluckily... some aspects actually require a working knowledge.
The issue you show is readily apparent to be an error in your App setup not matching the domain that is trying to connect.

From what I gathered from your comment, I entered https://forum.mysite.com/admin.php?misc/email-oauth-setup at console.cloud.google.com/apis/credentials -> OAuth 2.0 Client IDs -> Authorized redirect URIs.

That seemed to allow me to progress, but now I get another error:

Access blocked: mysite.com has not completed the Google verification process
myforumbounce111@gmail.com
mysite.com has not completed the Google verification process. The app is currently being tested, and can only be accessed by developer-approved testers. If you think you should have access, contact the developer.
If you are a developer of mysite.com, see error details.
Error 403: access_denied

Error 403: access_denied
Request details: access_type=offline response_type=code redirect_uri=https://forum.mysite.com/admin.php?misc/email-oauth-setup state=asdf type=web_server prompt=consent client_id=asdf.apps.googleusercontent.com scope=https://www.googleapis.com/auth/userinfo.email https://mail.google.com/ openid

I can't believe the documentation/instructions for setting up the basic email functions are completely absent in a product that's supposed to be the #1 choice and has been around for so many years.

 

[MaximilianKohler]

I gave up on OAuth and tried these IMAP settings instead:

• https://xenforo.com/community/threads/bounce-email.156547/post-1298668
• Go to gmail settings -> POP/IMAP -> enable IMAP. https://support.google.com/mail/answer/7126229

All I did was add a bounce@gmail to /admin.php?options/groups/emailOptions/. My Default email address and Contact email address are both the same @mydomain emails, which I previously tested to be working. But now when I try to send a test email via admin.php?tools/test-email it seems to be trying to send it from the bounce@gmail:

++ XF\Mail\SmtpTransport started
>> MAIL FROM:<myforumbounce123+91234520+bounce=simulator.amazonses.com@gmail.com>
<< 250 Ok
>> RCPT TO:<bounce@simulator.amazonses.com>

or

++ XF\Mail\SmtpTransport started
>> MAIL FROM:<myforumbounce123+ca4saff+admin=mysite.com@gmail.com>
<< 250 Ok
>> RCPT TO:<admin@mysite.com>

And I get these errors:
Errors were encountered while trying to send the email.

<< 554 Message rejected: Email address is not verified. The following identities failed the check in region US-WEST-1: myforumbounce123+91234520+bounce=simulator.amazonses.com@gmail.com...

!! Expected response code 250 but got code "554", with message "554 Message rejected: Email address is not verified. The following identities failed the check in region US-WEST-1: myforumbounce123+91234520+bounce=simulator.amazonses.com@gmail.com...
" (code: 554)

 

[Jeremy P]

I'm going through the steps and the "explain" link at the top doesn't work:

That appears to be a genuine bug in XF that appeared with the introduction of Microsoft OAuth support in the most recent version. It should read:

You will need to navigate to Google's Developer Console and setup a new project with OAuth 2.0 credentials for a web application. If you are using G Suite, creating an app with an internal user type is recommended to avoid a lengthy review process. In all cases, you will need to ensure the credentials support redirecting to the following URL: https://yoursite.com/admin.php?misc/email-oauth-setup

That seemed to allow me to progress, but now I get another error:

Per the error, you would need to verify your app with Google to allow OAuth to work. I may have been mistaken about OAuth being required for non-Workspace (regular Gmail) accounts, but I haven't tested to be sure. If it works, it's definitely much simpler to set up than OAuth.

And I get these errors:

Per the error message, you will need to verify the identity of the bounce email address in SES. Since you will need to verify the individual email address (you can't verify the gmail.com domain of course), you may have to disable VERP by unchecking the 'Enable variable email address values for automated email handling' option in XF as well.

 

[MaximilianKohler]

Another example for social media card previews/thumbnails: https://xenforo.com/community/threads/twitter-card-meta.57655/post-1639120

 

[FTL]

I'll second the need for better documentation, especially examples.

In my case, I managed to set up email functionality with AWS SES, but it took some doing. That's not all down to XF though due to the need to learn how SES works and then to get AWS to take my account out of the sandbox required me to make a written case for it, then having to wait for approval. It felt like a completed challenge at the end of it, lol.