|
|
energyfolks integration documentation
Please also remember to check out the integration examples. All examples include fully commented code, and
most are less than 3 lines of total code to implement.
WordPress Plugin
Looking for the energyfolks wordpress plugin? Find the documentation here. The wordpress plugin integrates energyfolks and eliminates the need to directly call the javascript functions on this page.
contents
Styling the EnergyFolks library
Important: You are highly encouraged to include a CSS stylesheet on your pages to customize the style of energyfolks content. A default sheet can be loaded directly in your head section from https://www.energyfolks.com/assets/energyfolks.css
The EnergyFolks library uses occasional inline-styles throughout its many displays to obtain a desired look (by setting element positioning, padding, and other options). Colors, font choices, and other styles are not set inline, and flow from your set of CSS styles. All of your pages that show any energyfolks content should load a stylesheet for proper display, and we recommend our default stylesheet. Custom stylesheets can be loaded instead as well, and the default stylesheet can be used as a template for your custom CSS file. Regardless of customizations, it is still recommended that you load the EnergyFolks.css file from our servers in your head section before loading your custom file. This will ensure that any future styles added to the platform reach your users and requires you to only define styles that differ from our defaults in your css files. (Note: any customizations you have in your files will take precedence over the default styles if you load your custom file after the default file in your header).
The EnergyFolks Javascript Library
The EnergyFolks library is available for download or inclusion into your site at: https://www.energyfolks.com/assets/energyfolks.js. We recommend loading the library directly from energyfolks servers (instead of storing a copy locally on your server) as any bug fixes or updates will automatically flow to your userbase. You should also include this library on evert page (energyfolks emails will send users to your site for actions, and if the library is not loaded on those pages, such as the homepage, actions will fail). For proper display, be sure to include either the default energyfolks css file (described above) or your own custom file.
The library includes a version of JQuery for its operation. To avoid conflicts with other JQuery installations or other javascript libraries that utilize the '$' namepsace, JQuery is mapped to EnergyFolks.$ in the Energyfolks library.
All methods and properties are accessed from the EnergyFolks namespace. For example, the LoginBox method is called with EnergyFolks.LoginBox().
Addressable Properties
These global properties are used library-wide and can be overwritten to customize library operation. For example, the accent color can be customized by adding EnergyFolks.color = 'AABBCC'; to your page in a javascript tag.
| Property |
Type |
Description |
id |
number |
A unique id number that identifies the affiliate group that should be associated with this request. If you do not know your group id, email contact@energyfolks.com. |
color |
string |
A hexadecimal color code representing the color scheme to be used. Defaults to F16522 (Blue). Note that if an id is set, this will automatically be set to the affiliate color set in the energyfolks database. |
Read-Only Properties
These properties are set by the library and can be read site-wide to access information. Note that these parameters can be overwritten, but doing so may cause unexpected behavior.
| Property |
Type |
Description |
user_logged_in |
boolean |
Boolean, whether the user is logged in or not. Note that this is 'false' at page load, and is set after page load by a script that pings energyfolks for user information. |
current_user |
json |
Hash of information related to the current user, such as name, company, affiliations, and administrator rights. |
Data Display Properties and Methods
The data display functions allow you to embed large energyfolks data windows on your page. You can show jobs, events, discussions, and other data types in a variety of styles and with a pre-set filters to limit results.
Properties
| Property |
Type |
Description |
per_page |
boolean |
The number of items to show per page for data views. |
get_moderated |
string |
If true, data displays will load items needing moderation. |
get_my_posts |
number |
If true, data displays will load post authored by the current user. |
source_restrict |
number |
Used to restrict data views to either posts originating from the network (set with id), or highlighted by the network. Values are:
-
EnergyFolks.ANY_POST: All posts (or all users in this network)
-
EnergyFolks.AFFILIATE_ONLY: From network
-
EnergyFolks.HIGHLIGHTED_ONLY: Highlighted by network
|
map_location_lat |
number |
Latitude to search around. Used in conjunction with map_location_lng, map_location_radius, map_location_name |
map_location_lng |
number |
Longitude to search around. Used in conjunction with map_location_lat, map_location_radius, map_location_name |
map_location_radius |
number |
Radius (miles) to search around the lat/lng coordinates. Used in conjunction with map_location_lng, map_location_lat, map_location_name. 0 disables location search. |
map_location_name |
number |
Name of location the search is being conducted around. Used in conjunction with map_location_lng, map_location_radius, map_location_lat |
search_terms |
string |
String to search for when retrieving data for view. Defaults to nothing (no search). |
Methods
| Methods |
Return Value |
Description |
Sidebar() |
none |
Will create the energyfolks sidebar wherever it is called on a page. Should only be used once per page. |
showPage( parameters:hash) |
none |
Creates energyfolks data view. The input hash should have the following options:
-
source: the type of data to load. Allowed values are:
events: Events Calendar
jobs: The jobs database
users: the membership database
blogs: the blog database (other group submitted blogs)
discussions: the discussion threads
-
format: the view to show the data in. Allowed values are:
list: list view (default)
month: Calendar view (not valid with users)
map: map view (not valid with discussions)
stream: stream (full text) view (only with discussions and blogs)
|
EnergyFolks Widgets
Widgets are a different way to display EnergyFolks data in a compact manner
Methods
| Methods |
Return Value |
Description |
showWidget( source, [parameters:hash] ) |
none |
Outputs an energyfolks widget that shows energyfolks information in a compact, vertical list. Multiple widgets can be used per page. Input parameters are:
source: required, the datatype to load. Allowed values are:
events: Events Calendar
jobs: The jobs database
blogs: the blog database (other group submitted blogs)
discussions: the discussion threads
The parameters hash is optional, and has the following optional parameters:
- [
title]: Title to show at the top of the box. Use '' to hide a title. Otherwise one is generated based on source
- [
items]: the number of items to show in the view (default 5)
- [
item_height]: the height, in pixels, of each item (default 35)
- [
latitude]: latitude to search around (default is affiliate location)
- [
longitude]: longitude to search around (default is affiliate location)
- [
radius]: radius (miles) around lat/lng to search (0 for no limit, default is affiliate chosen value)
- [
terms]: words to search for (default '')
- [
tags]: comma seperated list of tags to limit view to (default '')
- [
affiliate_only]: when set to true, will limit to items from this affiliate (Set by EnergyFolks.id). Default false.
- [
highlighted_only]: when set to true, will limit to items highlighted by this affiliate (Set by EnergyFolks.id). Default false.
|
The EnergyFolks Comments Library
The EnergyFolks Comments library is used to add an energyfolks comment stream to a page. This is useful for blog entries or any other page where you want to enable user comments: by using this library, users will be able to comment using their energyfolks account and subscribe to comments and replies to the thread.
Properties
| Property |
Type |
Description |
max_comment_before_collapse |
string |
For comment streams, the maximum number of comments to show before hiding the rest. |
max_replies_before_collapse |
boolean |
For replies in comments, the maximum number of replies to show before hiding the rest. |
Methods
| Functions |
Return Value |
Description |
Comments(title:string, [hash:string]) |
none |
Places a commenting box on the page where this is called. Input is a title that is used to identify the page/item this comment box corresponds to, and the second optional parameter is a unique hash or ID that identifies this box. You can create multiple boxes on the same page, and any boxes on the same page or different pages that share the same hash will display the same comment stream. If the hash is not provided, the page URL is used as the hash. |
Comments_HTML(title:string, [hash:string], [md5:boolean]) |
string |
Same as Comments, but instead of outputting to the document, it returns the HTML to create the box. Includes an optional third parameter which when set will stop the library from taking an MD5 of the hash based on the EnergyFolks.id. This is used when comment boxes will be shared accross groups or domains. |
Logins to EnergyFolks
Two Login scenarios are possible with the javascript library:
- Client-Side (default): The external site/server never knows any information about the state of the visiting user. All interactions
are taken care of by the energyfolks servers, and as a result the external site does not know whether the visitor is
logged in, a member, etc. Any embedded energyfolks content on the site, however, will be displayed based on the logged status of the current user. This is appropriate for most sites that do not need server-side knowledge of a user for scripting or other purposes.
- Server Side: the external site server communicates directly with the energyfolks server, allowing the
external site to learn the logged state of the visitor. This allows the site to taylor displays to the user, show
specific information based on status, etc. This requires server side scripting functionality, and is the functionality
used by the energyfolks wordpress plugin. See the
callbackURL property for information on setting server side logins up.
Logins are handled directly by the energyfolks library, and no methods need to be called to log a user in. Server-side functionality requires setting some EnergyFolks properties.
Custom Login Form
If you want to code a custom login form for your website, instead of using a built-in library function, you can do so. The requirements to make the form operate:
- Form should have the class
EnFolksExternalLoginForm
- Form should have a input type=text with class
EnFolksUser
- Form should have a input type=password with class
EnFolksPass
- Form should have a input type=checkbox with class
EnFolksCookie (used to select 'remember user' to set cookie beyond session)
- Form should have a button element to submit the form
- If you want to include a link to 'create a new account', make a link with class
EnFolks_create_account
- If you want to include a link to 'reset your password', make a link with class
EnFolks_forgot_pass
- If you want to include a link to 'resend activation email', make a link with class
EnFolks_reactivate
- If you want to include a link to login with external websites, make a link with class
ef_third_party_link and attribute data-type with the name of the external service ('linkedin' is only valid service)
Properties
| Property |
Type |
Description |
forwardto |
string |
Upon a successful login, the user will be forwarded to this URL. If not provided, the page is simply reloaded. |
forceLogin |
number |
Forces the system to ping energyfolks for user information and execute the login callback. This is used for systems that need server authentication, as it will force energyfolks to return user information if the server does not know the logged state of the user. When using server-side logins, this should be set to 'true' whenever the server does not know the logged state of the user. |
callbackURL |
string |
Used to enable server-side logins. Input is a URL that is called when a successful energyfolks login occurs. This URL is passed a 'hash' parameter as a get request. The server location should then pass this hash parameter to energyfolks via this url: https://www.energyfolks.com/users/from_hash?hash=RETURNED_HASH&aid=AFFILIATE_ID&secret=SECRET
The secret is generated from the shared secret your application has with energyfolks. It is an MD5 hash of the secret concatenated with the hash parameter. Upon a successful request, the server will return a JSON encoded array with user information, including id, first_name, last_name, and other information.
This function requires your application to be registered with energyfolks and to share a secret key. To register, please email us.
|
Methods
| Methods |
Return Value |
Description |
LoginBox([element_id]) |
none |
Creates a large login box for a user, or shows user profile information if user is already logged in.
Default behavior is to display information on the page where this function is called. If an element_id is provided, the output will be inserted into the body of the element with the id specified. |
SmallLoginBox([element_id]) |
none |
Creates a small login box for a user, or shows user profile information if user is already logged in.
Default behavior is to display information on the page where this function is called. If an element_id is provided, the output will be inserted into the body of the element with the id specified. |
LoginLinks([element_id]) |
none |
Creates login links (2 links: 'get an account' and 'login') for a user, or shows links to 'edit profile' and 'logout' if already logged in.
Default behavior is to display information on the page where this function is called. If an element_id is provided, the output will be inserted into the body of the element with the id specified. |
|
|