Documentation Improvement

[gabs-simon]

Hello to all users of the laravel-achievements package!

I'm currently writing a new version of the documentation and would like to hear feedback from everyone.

Please consider leaving a comment letting me know about:

• How did you like the current README.md file? Is it clear? Is it beginner-friendly?
• Did you experience any problems while using this package that the documentation wasn't clear enough?
• How did you like the examples provided in the current documentation?
• Do you have anything else to add?

Thank you very much!

[swirlingskirts]

I just got started with this package today and had a fairly robust achievement system (about 40 achievements, although some are "chained") going in about an hour. The documentation was quite adequate and clear, and the examples were excellent and got me going with all the basics. I'm still expanding my system, so I'll keep commenting if I run into issues. :)

[swirlingskirts]

Okay, here's a minor typo:

use App\Achievements\Have1000GoldOnTheBag;

$user->setProgress(new Have100GoldOnTheBag(), $user->amountOfGoldOnTheBag);

I'm almost certain you mean IN the bag rather than on?

On to more important things -- one thing I recall that DID trip me up about the docs was calling $user->unlockedAchievements() got me an instance of AchievementProgress. It tripped me up pretty badly when I could not do things like $achievement->name or even $achievement->achievement_detail->name in my view. Eventually through reading the code I was able to figure out that you've called it detail(), and that $achievement->detail->name did just fine. I think it would be worth showing that as an example.

[gabs-simon]

That's interesting. Do you thing unlockedAchievements() should return instances of AchievementDetail instead?

I believe that what the documentation is lacking most is a way to display unlocked achievements. I have an example in a parallel repo but I have not linked it here.

[gabs-simon]

And thanks for your feedback! Please let me know if you run into more issues while using this package.

[swirlingskirts]

No, I think what it returns now is fine, I just think there should be an explicit example included showing how to access the details. Even just demoing {{ $achievement->detail->name }} once would be a helpful hint for newbies.

[gabs-simon]

Hi @kgenly !

I'm currently preparing base templates to be used for teaching purposes. Are you able and would you be willing to share the templates you have created on your system?

[swirlingskirts]

Hi again @gabriel-simonetti ! I'd be happy to share some -- did you have any in particular in mind?

Here's something for my user profile view:

@if ($achievements->count() > 0)
      <div class="achievements" id="achievements">
        <h3>{{$user->name}}'s achievements</h3>
        @foreach($achievements as $achievement)
        <div class="achievement">
          <img
          src="{{ asset('img/badges/'.strtolower(str_replace(' ', '_', $achievement->details->name)). '.png') }}"
          title="{{$achievement->details->name}}" alt="{{$achievement->details->name}} achievement badge"
          >
        </div>
        @endforeach
      </div>
      @endif

[HDVinnie]

I use this in my profile view

            <div class="well">
                <div class="row">
                    <div class="col-md-12 profile-footer">
                        {{ $user->username }} - {{ trans('user.recent-achievements') }}:
                        @foreach($user->unlockedAchievements() as $a)
                            <img src="/img/badges/{{ $a->details->name }}.png" data-toggle="tooltip" title=""
                                 height="50px" data-original-title="{{ $a->details->name }}">
                        @endforeach
                        <div class="col-xs-1 achievements"><i
                                    class="{{ config('other.font-awesome') }} fa-trophy text-success"></i><span>{{ $user->unlockedAchievements()->count() }}</span>
                        </div>
                    </div>
                </div>
            </div>

[HDVinnie]

This is actual user achievements view

@section('content')
    <div class="container">
        <div class="row">
            <div class="col-md-8">
                <div class="panel panel-default">
                    <div class="panel-heading">{{ trans('user.unlocked-achievements') }}</div>
                    <div class="panel-body">
                        <br/>
                        <div class="table-responsive">
                            <table class="table table-borderless">
                                <thead>
                                <tr>
                                    <th>{{ trans('common.name') }}</th>
                                    <th>{{ trans('common.description') }}</th>
                                    <th>{{ trans('common.progress') }}</th>
                                </tr>
                                </thead>
                                <tbody>
                                @foreach($achievements as $item)
                                    <tr>
                                        <td><img src="/img/badges/{{ $item->details->name }}.png"
                                                 data-toggle="tooltip" title=""
                                                 data-original-title="{{ $item->details->name }}"></td>
                                        <td>{{ $item->details->description }}</td>
                                        @if($item->isUnlocked())
                                            <td><span class="label label-success">{{ trans('user.unlocked')
											}}</span></td> @else
                                            <td><span class="label label-warning">{{
											trans('common.progress') }}:
                                                    {{$item->points}}/{{$item->details->points}}</span></td>
                                        @endif
                                    </tr>
                                @endforeach
                                </tbody>
                            </table>
                        </div>
                    </div>
                </div>
            </div>
            <div class="col-sm-4 text-center">
                <div class="text-green well well-sm">
                    <?php $unlocked = auth()->user()->unlockedAchievements()->count() ?>
                    <h3>
                        <strong>{{ trans('user.unlocked-achievements') }}:</strong>{{
					$unlocked }}
                    </h3>
                </div>
                <div class="text-red well well-sm">
                    <?php $lock = auth()->user()->lockedAchievements()->count() ?>
                    <h3>
                        <strong>{{ trans('user.locked-achievements') }}:</strong>{{ $lock
					}}
                    </h3>
                </div>
            </div>
            <div class="col-md-8">
                <div class="panel panel-default">
                    <div class="panel-heading">{{ trans('user.pending-achievements') }}</div>
                    <div class="panel-body">
                        <br/>
                        <div class="table-responsive">
                            <table class="table table-borderless">
                                <thead>
                                <tr>
                                    <th>{{ trans('common.name') }}</th>
                                    <th>{{ trans('common.description') }}</th>
                                    <th>{{ trans('common.progress') }}</th>
                                </tr>
                                </thead>
                                <tbody>
                                @foreach($pending as $p)
                                    <tr>
                                        <td><img src="/img/badges/{{ $p->details->name }}.png"
                                                 data-toggle="tooltip" title=""
                                                 data-original-title="{{ $p->details->name }}"></td>
                                        <td>{{ $p->details->description }}</td>
                                        <td><span class="label label-warning">{{
											trans('common.progress') }}:
                                                {{$p->points}}/{{$p->details->points}}</span></td>
                                    </tr>
                                @endforeach
                                </tbody>
                            </table>
                        </div>
                    </div>
                </div>
            </div>
            <div class="col-md-8">
                <div class="panel panel-default">
                    <div class="panel-heading">{{ trans('user.locked-achievements') }}</div>
                    <div class="panel-body">
                        <br/>
                        <div class="table-responsive">
                            <table class="table table-borderless">
                                <thead>
                                <tr>
                                    <th>{{ trans('common.name') }}</th>
                                    <th>{{ trans('common.description') }}</th>
                                    <th>{{ trans('common.progress') }}</th>
                                </tr>
                                </thead>
                                <tbody>
                                @foreach($locked as $l)
                                    <tr>
                                        <td><img src="/img/badges/{{ $l->details->name }}.png"
                                                 data-toggle="tooltip" title=""
                                                 data-original-title="{{ $l->details->name }}"></td>
                                        <td>{{ $l->details->description }}</td>
                                        <td><span class="label label-danger">{{ trans('user.locked') }}</span></td>
                                    </tr>
                                @endforeach
                                </tbody>
                            </table>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
@endsection

[gabs-simon]

Thank you @HDVinnie and @kgenly for sharing your templates!

Do you have an example on how you're alerting your users for new Unlocks and Progresses?

[swirlingskirts]

I have this same code in all my achievements:

public function whenUnlocked($progress)
    {
      $user = $progress->achiever;
      ActivityAlert::create([
        'user_id' => $user->id,
        'alertable_type' => get_class($progress),
        'alertable_id' => $progress->id,
        'icon' => 'trophy',
        'url' => route('user.profile', ['id'=> $user->username]).'#achievements',
        'activity' => 'Achievement unlocked! '. $progress->details->name
      ]);
    }

Of course activity alerts is a model I've set up for various kinds of notifications.

[HDVinnie]

Im using the SWAL alert example you provided.