#123

Product support

Get help in the plugin support forum.

Categories

  • Developer Tools
  • Miscellaneous
  • Social
  • Utility

User Extended 2.0.00

Overview

User Extended provides simple components and User Utility functions for complex interactions with users.

User Extended currently offers friends lists, role management, and User Utilities.

Dependencies

Installation

Install this plugin and run php artisan october:up

Usage

  • Just add the components you require to a page and everything should work out of the box
  • You can create modules to interact with User Extended and other UE modules
  • Use the command: php artisan create:uemodule author.pluginname in order to scaffold a module class for your own plugins.

Check out the bug tracker and feature planner

Contributors

Feature List

  • Frontend role/group management
  • Advanced page restriction using groups
  • Friends lists. You can send friend requests, and block/delete/accept friends
  • User Utility functions which can be used accross your own plugins
  • User profiles and a profile comment system
  • User search. Search for users by name, email or username
  • Timezone support! Use the '|timezonify' twig filter. Use the '|relative' twig filter to get a textual relative time stamp (5 seconds ago, 2 months ago)
  • Timezonable trait which can be added to models to automagically convert times
  • Backend user role/group management
  • Extensible modules

Please see the help directory for more information

Videos


A demo of the Generic User Settings Coming Soon

A demo of the Role Manager UI

A demo of Timezones

Planned Features

Check out the feature planner

Road map

View our road map

Details

User Extended is not trying to be a social network plugin. We are providing functionality for more complex user functions which have use cases outside of social networks.

Websites specializing in online games, forums, blogs, news etc. can all benefit from User Extended.

Event List

  • clake.ue.preregistration(post &$data) : halted. $data contains registration form data. Returning false will cancel registration.
  • clake.ue.postregistration(UserExtended &$user). $user contains the final user object before saving it and logging out the user to finalize registration.
  • clake.ue.login(User $user). $user contains the user object after authenticating.
  • clake.ue.logout(User $user). $user contains the user object after logging out.
  • clake.ue.settings.create(UserSettingsManager &$instance). After the user settings instance object has been created
  • clake.ue.settings.update(UserSettingsManager &$instance). After the user settings instance object has been created
Backend Role Manager

Components

Account

Use cases

  • User registration
  • Logging in
  • Logging out
  • Changing user settings

Template Data Getters

  • createSettings() Returns a list of dynamic settings which are makred as registerable
  • updateSettings() Returns a list of dynamic settings which are marked as editable
  • user() Returns the user object for the logged in user
  • signUp() Returns whether or not we are using email or username to register

Handlers

  • onUpdate() Called to update user settings and details
  • onRegister() Called to preform a registration
  • onLogin() Called to authenticate and login a user
  • onLogout() Logs out a user

Usage Examples

To render any of the account feature you will have to manually specify the partial you wish to use.

In the future, this will be integrated into the component inspector.

{% partial 'account::update' %} - User Settings

{% partial 'account::signup' %} - User Registration

{% partial 'account::login' %} - User Login

{% partial 'account::logout' %} - User Logout

Friends

Use cases

  • Send friend request
  • Delete friend
  • Block user - Might be moved to a different component
  • Visit profiles
  • Accept friend request
  • Decline friend request
  • Display friends list
  • Display friend requests

Template Data Getters

  • type() : propType Returns whether we want to render a friends list or a friend request list
  • friendsList() : UserCollection Returns a list of a users friends
  • friendRequests() : UserCollection Returns a list of friend requests for the logged in user

Handlers

  • onDelete(post userId) Removes a friend from the logged in users friends list
  • onBlock(post userId) Blocks a user from the logged in users friends list
  • onVisitProfile(prop profilePage) Redirects to a users profile page
  • onAccept(post userId) Accepts a friend request
  • onDecline(post userId) Declines a friend request
  • onRequest(post userId) Sends a friend request

Usage Examples

  • Add the component to a page and use the inspector to choose an output type.
  • You can also use the AJAX handlers directly if you would like to utilize them in your own plugin.

Current output types:

  • Friends list
  • Friend requests

User

Use cases

  • Creating a profile page
  • Displaying random users
  • Searching users
  • Displaying a user
  • Sending friend requests
  • Handling user profile comments
  • Visiting user profile

Template Data Getters

  • randomUsers(prop maxItems) : UserCollection Returns a collection of random users who aren't on our friends/block list
  • type() : propType Returns the type of rendering to do: 'random' users, 'single' user, 'search' users, user 'profile' page
  • singleUser(prop paramCode) : UserExtended Returns a user
  • user(prop paramCode) : UserExtended Returns a user object
  • locked(prop paramCode) : bool Returns whether we are a friend or own the profile we are looking at
  • comments(prop paramCode) : CommentsCollection Returns a collection of comments associated with a user
  • roles() : RoleCollection Returns a collection of roles for the logged in user
  • groups() : GroupsCollection Returns a collection of groups for the logged in user
  • userRoles(prop paramCode) : RoleCollection Returns a collection of roles for an arbitrary user
  • userGroups(prop paramCode) : GroupsCollection Returns a collection of groups for an arbitrary user

Handlers

  • onRequest() Sends a friend request
  • onSearch(post phrase) : PartialRender Searches for users based on a phrase and returns a list of results
  • onFriendUser(prop paramCode) Sends a friend request to a user
  • onComment(prop paramCode, post comment) : PartialRender Creates a new comment and then refreshes the comment list
  • onDeleteComment(post commentid) : PartialRender Deletes a comment and then refreshes the list
  • onVisitProfile($property = null, post id, prop profilePage) : Redirect,false Redirects a user to a profile page if valid

Page Variables

  • groups Collection of a users groups

Usage Examples

  • Add the component to a page and utilize the inspector to choose the output type.
  • You can also use the AJAX handlers directly if you wish.

Modules

How to extend UserExtended

If you are writing a plugin and you would like to use functions from UserExtended or provide your own functions, then this is the right place to come.

UserExtended provides two methods of extensibility. The old method is called User Utilities and the new method is called Modules.

Modules

Modules are a form of registration which plugins can use to directly interact with other modules as well as UserExtended.

Modules consist of:

  • Meta data: $name, $description, $author, $version
  • Overridden functions: injectComponents(), injectNavigation(), injectLang(), initialize()
  • Extensible functions. While the functions and meta data above are required, extensible functions are entirely up to the module author and can be non existent.

How do I create a Module?

Please use the scaffolding command shipped with UE:

php artisan create:uemodule author.pluginName

author.pluginName is the plugin you wish to create a module for.

What are modules for?

Modules allow plugin authors to form a strict contract for what they would like other plugin authors to be able to manipulate and access with their plugin when it comes to User functions.

As an example, imagine you are writing a forum plugin. It may be useful for you to create a module which can return a users latest activity, a users post history, or user post stats. Rather then having other plugin authors snoop through your code and database tables, you can just create some simple extensible functions in your module and other plugin authors can use those directly.

Okay, so I made a module class, how do I register it?

To register your module, you will have to go into your plugin's plugin.php file and add the line Module::register() inside of the register function.

My module is registered, now how do I use them?

To use a module, you simply use the following syntax anywhere in your plugin. UserExtended::moduleName()->extensibleFunction($params);

The moduleName is the $name meta data defined within a module registration file.

What are module best practices?

The name of a module should be in a format like: authorModuleName as this helps prevent naming conflicts.

What if I want to check if other modules are loaded before providing features? What is this initialize function for?

The initialize function which you override to create a module, is called on each module after all the modules have been registered.

This allows you as a plugin dev to unlock more functionality if various other modules are loaded.

What are the injection functions for?

It allows you to add components, lang, navigation and more in the future to UserExtended!

User Utilities

UserExtended provides a class called UserUtil which has many common User based functions which you may find useful to use in your own plugins.

The long term goal is to move these functions into the UserExtended core module and deprecate User Utilities.

UserUtil

All functions in User Util are declared as static and should be used like UserUtil::function();

Function API

getUsers($value, $property = "name") : UserCollection Preforms a DB query for users with their $property = $value

getUser($value, $property = "id") : UserExtended Preforms a DB query for the first user with their $property = $value

getRainlabUser($value, $property = "id") : User Preforms a DB query for the first user with their $property = $value

getLoggedInUser() : User Returns the Rainlab User model for the logged in user

getLoggedInUsersTimezone() : string Returns the timezone code for the logged in user

getUserTimezone($value, $property = "id") : string Returns the timezone code for a user where their $property = $value

castToRainLabUser(UserExtended $user) : User Preforms a top level cast by transferring only the attributes of the UserExtended object to a User object (Fast)

castToUserExtendedUser($user) : UserExtended Preforms a top level cast by transferring only the attributes of the User object to an UserExtended object (Fast)

convertToUserExtendedUser($user) : UserExtended Preforms a low level conversion by preforming a DB query to populate the UserExtended object (Slow)

searchUsers($phrase) : UserExtendedCollection Searches for users via $phrase. It searches first name, surname, email, and username

getUsersIdElseLoggedInUsersId($userId = null) : int Gets the user ID for the logged in user, if no user is logged in, it returns the passed ID as a fallback

getUserForUserId($userId = null) : UserExtended Returns the UserExtended object for the user ID passed in. If the user ID passed in is null, gets logged in user

idIsLoggedIn($userId) : bool Returns whether or not a passed in ID is the ID of the logged in user

getLoggedInUserExtendedUser() : UserExtended Gets the logged in user object and converts it to an UserExtended user object before returning it

Timezone Trait

Usage

  1. Add this trait to a model:

    use Clake\UserExtended\Traits\Timezonable;
  2. Add a protected data member to your model:

    protected $timezonable = [
        'created_at',
        'updated_at'
    ];

    This contains model attributes to convert to a users timezone

  3. The trait will automatically convert timezones when using the model attributes specified. Defaults to UTC.

Searchable Trait

Usage

  1. Add this trait to a model:

    use Clake\UserExtended\Traits\Searchable;
  2. Add a protected data member to your model:

    protected $searchable = [
        'email',
        'name',
        'surname',
        'username'
    ];

    This contains model attributes to search

  3. Utilize the traits search function:

    $results = new Model();
    
    return $results->search($phrase);
2.0.00

User Extended Core Stable Release. Check your project as many things are now Deprecated and rewritten and will be removed in version 3.0.00

Mar 15, 2017

1.1.03

Fixed undefined offset error

Feb 05, 2017

1.1.02

Fixed non-property error

Feb 05, 2017

1.1.01

Creating role bug fix

Feb 05, 2017

1.1.00

User Extended Beta release. Check your project as many things are now Deprecated and rewritten.

Feb 05, 2017

1.0.25

Add user settings

Feb 05, 2017

1.0.24

Fixed data structures bug

Dec 13, 2016

1.0.23

Bug Fixes

Dec 07, 2016

1.0.22

Initial release of the Role Manager in the backend.

Nov 30, 2016

1.0.21

Added the Timezonable trait. Useful for automatically converting model fields to the logged in users timezone.

Nov 30, 2016

1.0.20

Added a controller for Roles. Check the 'User' tab in the backend.

Nov 30, 2016

1.0.19

Adds a primary id key to the users_groups model

Nov 30, 2016

1.0.18

Removes existing primary keys from Users Groups model

Nov 30, 2016

1.0.17

Adds role to the Users Groups table

Nov 30, 2016

1.0.16

Added Roles as a linear heirarchy under a group.

Nov 30, 2016

1.0.15

Create Roles table

Nov 30, 2016

1.0.14

Seed timezones

Nov 30, 2016

1.0.13

Modified Users table to add a timezone_id column

Nov 30, 2016

1.0.12

Added Timezone table

Nov 30, 2016

1.0.11

Updated User Group Seeder. You may wish to consider to rerun it.

Nov 30, 2016

1.0.10

Added Heirarchal Level to User Groups

Nov 30, 2016

1.0.9

Fixed 'Code Has Already Been Taken' error

Nov 21, 2016

1.0.8

Added delete capabilities for comments and friends

Nov 18, 2016

1.0.7

Added user profile pages

Nov 18, 2016

1.0.6

Added author to comments table

Nov 18, 2016

1.0.5

Add Comments table

Nov 18, 2016

1.0.4

Added user searching

Nov 18, 2016

1.0.3

Add Accepted to Friends table.

Nov 12, 2016

1.0.2

Create the table.

Nov 12, 2016

1.0.1

Seed in basic groups.

Nov 12, 2016

Core Stable Release

With the latest release of User Extended (UE), I recommend running php artisan plugin:refresh clake.userextended as I did some work with Table dropping and forming to solve some bugs and problems. However, I did design these changes in such a way that it should be backwards compatible, however, refreshing the plugin will ensure that.

It's also important to note that many functions have been marked as deprecated. In the following release these functions will be removed from the code base. Please check your project if you have used any functions from UE. As well, the components marked deprecated in the beta release, have now been de-registered. For backwards compatibility, you can re-register these functions manually as the code still exists. However, many of these components are now broken because of changes I made to other parts of the code base. In the next release, the old components source code will be removed.

Please see the documentation pages and the Github wiki for more information.