PLUGIN README
facebookLogin - Extends Website Membership to support login and sign-up via Facebook
-------------------------------------------------------------------------------


UPGRADING FROM FACEBOOK LOGIN v1.xx
------------------------------------------------------------------------------
Note: If you're not upgrading an older Facebook Login plugin you can skip this section.

To upgrade from v1.xx perform the following steps:

  1) Copy the new file "facebookLogin_settings.php.example" and save it as "facebookLogin_settings.php"
  2) Copy your app id and app secret from the top of the old plugin into facebookLogin_settings.php
     NOTE: If you don't have your old settings, you can get them from Facebook by following the instructions below.
  3) Open your website login page and remove this old login code: 

      <?php if (@$GLOBALS['FACEBOOKAPI_ENABLE_LOGIN']): // NOTE: This feature requires the Facebook Login plugin! ?>
        <a href="<?php echo facebookLogin_getFacebookLoginUrl();?>"
        onclick="<?php echo facebookLogin_getFacebookLoginUrl_popupOnClick(); ?>">Login with Facebook</a><br/><br/>
      <?php endif ?>

  4) Follow the instructions below under: ADD "LOGIN WITH FACEBOOK" TO YOUR LOGIN PAGE.
  5) The plugin may have added some fields under website accounts table.  Go the field editor and dragsort them into your preferred position.
  5) Let us know if you have any problems upgrading.


GETTING STARTED
-------------------------------------------------------------------------------
This plugin extends the functionality of the "Website Membership" plugin.

If you haven't already done so, see the "readme.txt" instructions that came
with "Website Membership" and follow those instructions to setup and activate
the Website Membership plugin.

Next, create a Facebook App by following these instructions:


CREATING A FACEBOOK APP AND ENABLING FACEBOOK LOGIN
------------------------------------------------------------------------------

-  Go to developers.facebook.com, login if required, then go to My Apps -> Add a new App in the drop down menu at the top of the page.

-  If this is your first app, or if you have not verified your Facebook account, click on "Register Now" and register.

-  A pop up will appear asking you which type of app you wish to create, select website. 

-  On the Quick start for website screen enter the name you'd like for your App and click 'Create New Facebook App ID'. Then select which category your app falls under. Leave 'Is this a test version of another app? Learn More. ' set to No.

-  You'll be taken to a 4 step 'quick start' process. 

- The first step shows you some JavaScript code, you can ignore this and enter your sites domain in the 'site url' field at the bottom of the page.

- Once this is done, you'll be taken directly to the 'test' step, and the initial configuration is complete!

- Now you can click 'Skip quick start' button in the top corner of this page. 

- This will bring you to your app edit page.

- Create a file called "facebookLogin_settings.php" by copying "facebookLogin_settings.php.example"

- Copy the APP ID and APP Secret strings into the plugin file: facebookLogin_settings.php
  fbl_settings('app_id',      '');          // Copy Facebook App ID from app created at https://developers.facebook.com/apps
  fbl_settings('app_secret',  '');          // Copy Facebook App Secret from app created at https://developers.facebook.com/apps

- Click on "App Domains" and enter your domain without the www (eg: example.com)

- Click on "Website with Facebook Login".  Enter your website URL (eg: http://example.com/ ) and click "Save Changes".


ADD ADDITIONAL ADMINISTRATORS TO FACEBOOK APP
------------------------------------------------------------------------------
If there are other people who are going to need to access the app, such as clients,
developers, or other vendors, then add them as follows:

- Click on your app here: https://developers.facebook.com/apps/
- Go to: Your App > Left Menu > Roles > Roles > Administrators > Add Administrator
- Enter the name of the person you want to add.  You may need to ask them for their Facebook username or fbid.
- Tell them to approve the request here: https://developers.facebook.com/requests/


ADD "LOGIN WITH FACEBOOK" TO YOUR LOGIN PAGE.
------------------------------------------------------------------------------
To add a "Login With Facebook" button to your page:

First, open the login page that you previously created with Website Membership.

If the page has this "old" Facebook Login code, remove it: 
  <?php if (@$GLOBALS['FACEBOOKAPI_ENABLE_LOGIN']): ?>
    <a href="<?php echo facebookLogin_getFacebookLoginUrl();?>"
       onclick="<?php echo facebookLogin_getFacebookLoginUrl_popupOnClick(); ?>">Login with Facebook</a><br/><br/>
  <?php endif ?>

Add this HTML where you want to display the login with facebook link:

  <!-- Facebook Login -->
  <?php if (function_exists('fbl_login')): ?>
    <?php fbl_loginForm_javascript(); ?>
    <a href="#" onclick="fbl_login(); return false;">Login with Facebook</a><br/>
  <?php endif; ?>
  <!-- /Facebook Login -->

NOTE: You can move the javascript to the head or footer of your page if your prefer.


ADD "CONNECT/DISCONNECT FACEBOOK" TO YOUR EDIT PROFILE PAGE
------------------------------------------------------------------------------
This feature lets user manually connect or disconnect their Facebook account
from their "Edit Profile" or "Account" page.  Users might want to do this if
they didn't initially sign up with Facebook, or if they no longer want to
authorize Facebook logins.

On "Connect" all the facebook_* fields in the user record are updated.

On "Disconnect" the facebook_id and facebook_access_token fields are cleared.

Edit the profile page and add this code (this example uses Bootstrap 3):

  <?php // Facebook Login - Connect and disconnect authorization ?>
  <?php if (function_exists('fbl_login')): // if Facebook Login enabled ?>
    <?php fbl_loginForm_javascript(); ?>
     <div class="form-group">
      <label>Facebook Login</label>
      <div>Connect your account to Facebook to login with one-click</div>

      <?php if (empty($CURRENT_USER['facebook_id'])): ?>
        <a href="#" onclick="fbl_login_connect(); return false;" class="btn btn-primary btn-sm">Connect</a>
      <?php else: ?>
        <a href="#" onclick="fbl_login_disconnect(); return false;" class="btn btn-primary btn-sm">Disconnect</a>
      <?php endif ?>
     </div>
  <?php endif ?>
  <?php // END: Facebook Login - Connect and disconnect authorization ?>

Then test connecting and disconnecting your Facebook account to confirm it works.


SET LOGIN URL AND ACTIVATE PLUGIN
------------------------------------------------------------------------------

Finally, check the "WEBSITE_LOGIN_LOGIN_FORM_URL" value in the Website Membership
plugin and make sure the URL is an absolute url starting withing http, https, or /.

Finally, activate the "Facebook Login" plugin under: Admin > Plugins.

Then reload the login page, logging off if necessary, and try logging in with Facebook.

If a user account already exists with the same email address as the Facebook account, then
Facebook will be associated with that account and the user will be logged in.

If no user account exists with the same email as the Facebook account, then a
new account will be created for that user.

NOTE: If you have any problems or errors, either follow the instructions to correct
them, or temporarily deactivate the FacebookLogin plugin if needed.


FACEBOOK LOGOS AND BRANDING
-------------------------------------------------------------------------------
If you want to use any type of Facebook Logo or branding on your site, you must
ensure that you are ONLY using those images in accordance with Facebook rules and
guidelines.

For more information, see here:
http://www.facebook.com/brandpermissions/


IMPORTING ADDITIONAL USER DATA FROM FACEBOOK
------------------------------------------------------------------------------
Each time the user logs in with Facebook or connect their Facebook account, the
following built-in fields will be updated in the user record:

facebook_access_token - A temporary (~60 days) security token that securely identifies the user and can be used to read, modify or write the users Facebook data on their behalf.
facebook_id           - The id of this person's user account. This ID is unique to each app and cannot be used across different apps.
facebook_name         - The person's full name
facebook_gender       - The gender selected by this person, `male` or `female`. If the gender is set to a custom value, this value will be based off of the preferred pronoun; it will be omitted if the preferred pronoun is neutral

Additionally, if you manually create these fields in the member accounts table they
will be automatically updated on Facebook login or connect:

facebook_email        - The person's primary email address listed on their profile. This field will not be returned if no valid email address is available
facebook_first_name   - The person's first name
facebook_middle_name  - The person's middle name
facebook_last_name    - The person's last name
facebook_link         - A link to the person's Timeline (uses an app scoped user id)
facebook_locale       - The person's locale, eg: en_US
facebook_timezone     - The person's current timezone offset from UTC, eg: -7
facebook_updated_time - Last time the user's profile was updated, eg: 2017-08-30T18:34:28+0000
facebook_debug        - An internal debug field showing all the data we got back from the Facebook Graph API (use a textbox field)

ADDITIONAL TECHNICAL NOTES
-------------------------------------------------------------------------------
This plugin creates several fields in the accounts table to store the users Facebook
login details.  They are as follows: facebook_id, facebook_access_token,
facebook_name, and facebook_gender.

-------------------------------------------------------------------------------
end of file.
