@competitionlabs/leaderboard
v3.0.5
Published
Leaderboard Widgets
Downloads
28
Maintainers
Keywords
Readme
Leaderboard Widgets V3
HTML/CSS and Vanilla JavaScript Competition Labs Leaderboard / Achievements / Inbox-Messaging widget
Our widget "out of the box" is a product that you can use immediately by placing it on your existing game, on your website or include it into your Node project directly or anything that you need it to be used for. The widget is fully editable, re-adjustable, multilingual (all languages are supported), units of measure are also auto-generated by the system (all the currencies are pre defined in your private space) and it is a complementary product that gives the player a full in-depth gaming experience. All you have to do is:
Installation
The Leaderboard Widget package lives in npm. To install the latest stable version, run the following command:
npm install @competitionlabs/leaderboard
Or if you're using yarn:
yarn add @competitionlabs/leaderboard
Contributing
Prerequisites
- NodeJS >= 10.10
- NPM >= 6.x
Build
Go to the leaderboard_v3
directory and install the dependencies.
npm install
Run npm run build
in the leaderboard_v3
directory to generate production files inside build
.
npm run build
You can include css file into the bundle by running npm run build:inline-css
npm run build:inline-css
Or run npm run dev
to build widget in development mode.
npm run dev
Coding standards
Code formatting rules are defined in .eslintrc
. You can check your code against these standards by running:
npm run lint
To automatically fix any style violations in your code, you can run:
npm run lint -- --fix
Running tests
You can run the test suite using the following command:
npm run test
Run npm run test:coverage
to open coverage report
npm run test:coverage
Please ensure that the tests are passing when submitting a pull request.
Example
Run npm run example
to open the example page.
npm run example
Documentation
You can generate documentation by running:
npm run jsdoc
Different themes
There are a few themes to choose from (or create your own):
Build default theme:
npm run dev
Build dark theme:
npm run dev:dark-theme
Build blue theme:
npm run dev:blue-theme
Build green theme:
npm run dev:green-theme
Build grey theme:
npm run dev:grey-theme
Build red theme:
npm run dev:red-theme
Build orange theme:
npm run dev:orange-theme
Build black theme:
npm run dev:black-theme
Examples
Adding widget to your website
<script type="text/javascript">
(function(w,d,s,u,o){
w[o] = {
apiKey: '<api_key>',
spaceName: '<space_name>',
gameId: "<game_name>",
memberId: '<member_reference_id>',
language: "en",
uri: {
gatewayDomain: "https://gateway-staging.competitionlabs.com",
translationPath: "https://s3-eu-west-1.amazonaws.com/demo.competitionlabs.com/_widgets/leaderboard_v3/build/i18n/translation_:language.json"
},
resources: [
"https://s3-eu-west-1.amazonaws.com/demo.competitionlabs.com/_widgets/leaderboard_v3/build/css/theme/default-theme.css"
]
};
var a=d.createElement(s), m=d.getElementsByTagName(s)[0];
a.async=1;a.src=u;m.parentNode.insertBefore(a,m);
})(window,document,'script','https://s3-eu-west-1.amazonaws.com/demo.competitionlabs.com/_widgets/leaderboard_v3/build/javascript/leaderboard.v3.js',"_CLLBV3Opt");
</script>
Using the loader script
You can use this loader script to centralise all your widget loading needs (custom scripts, styles and environmental parameters) into a single place.
The "Loader" script requires the bear minimum of 2 things to be set to the global window._CLLBV3Opt
parameter before the scripts loads:
gameId
memberId
<script type="text/javascript">
window._CLLBV3Opt = {
gameId: "my_game_id",
memberId: "my_member_id"
};
</script>
Steps required to configure the loader script:
- update your default API key, space name (optional:
language
andcurrency
), unless you are loading the API key and space name from your game/product - define what products will load in the widget:
products: {
"my_product_id": {
script: "https://my.custom.script.location",
resources: [
"https://my.custom.stylesheet.location"
],
onBeforeLoad: function( instance, options, callback ){ // your custom logic before the widget gets initialised/rendered
if( typeof callback === "function" ) callback();
}
},
"my_product_id_2": {}
}
- add loader script to your website
FAQ
How do I set the currency:
The setting "currency" needs to be set to the appropriate ISO key used in units of measure section
{
currency: "usd"
}
How do I specify a custom stylesheet:
All styles are loaded as part of the initialisation, so overwriting the resources array variable with your stylesheet asset will allow you to load in the external stylesheets dynamically. There is no limit to how many stylesheets you can add as the widget will load all of them from the specified array.
How to show game/product specific competitions only:
The setting "enforceGameLookup" should be set to "true" and game/product ID should be assigned to the setting entry "gameId" part of the widget startup/initialisation
{
enforceGameLookup: true,
gameId: "my_id"
}
How to disable Inbox/Messaging section:
To disable the inbox/messaging area on the full widget preview the following setting "messages.enabled" has to be set to "false":
{
messages: {
enable: false
}
}
How to show the widget only if there are any available competitions:
The primary method “this.startup“ inside the "LbWidget" class is the one you should adjust to implement your scenario to achieve a pre-launch check, you can wrap what's inside of that method with the function:
this.checkForAvailableCompetitions()
This method collects all the necessary information about active, ready and finished competitions (example: _this.settings.tournaments.readyCompetitions will contain a list of upcoming competitions) so you can use the callback and the collected information to decide to show or hide the mini-scoreboard on startup based on your requirements.
How do I only show the competition tab if there is an active competition only and/or change the default tab to the achievements tab
The current flow is:
- once the mini scoreboard is clicked, the main layout gets initialized (unless it’s already not existing in the DOM)
- the navigation then gets reset to the initial competition tab
To achieve this scenario you would need to do an available competition check prior to the navigation reset and then hide/show tabs accordingly based on your business requirement. The code of interest would be on line inside the method called: "this.initLayout" in the "MainWidget" widget class, the method that resets the navigation is "_this.resetNavigation( callback )" this handles what navigation item to set as default for the user. You can either change this code directly or override that method after initialization inside the "this.startup" method for the class "LbWidget" by doing the following "_this.settings.mainWidget.resetNavigation = function(callback){}". There you can write some logic that would check what tabs to show/hide. Or you can overwrite this on a more global scope level where you initialize the widget "new LbWidget(window._CLLBV3Opt)" as you get full access to the settings and all other methods.
Localization - How do I translate the widget UI:
To enable translation the following steps need to be made:
- Translate your UI elements to the appropriate language and save it in a ".json" format using the following naming pattern
translation_en.json
JSON example - The translations you define inside the file will be merged with the core translations on run time
* The default widget language is set to english "en", the widget will try to load look for an external translation
resource based on the language setting and the "translationPath"
* If the resource path is used as "translation_:language.json" the widget script will try to replace ":language" with the
current language setting and load the translation dynamically from an external source, example:
https://s3-eu-west-1.amazonaws.com/demo.competitionlabs.com/_widgets/leaderboard_v3/i18n/translation_:language.json
* If translations are not required it is possible to disable them by changing "loadTranslations" setting to "false"
Why we use SASS:
Here are some of the basic benefits of why we are using SASS:
- provides the ability to use variables, allows you to store a value, or a set of values, and to reuse these variables throughout your SASS files as many times you want and wherever you want. Easy, powerful, and useful.
- the improved syntax allows you to use a nested syntax, which is code contained within another piece of code that performs a wider function
- provides mixin functionality: Mixins are like functions in other programming languages. They return a value or set of values and can take parameters including default values.
- allows you to break apart your big complex CSS files into smaller chunks, this improves the ability to work on the same stylesheets for multiple teams
- still supports the basic CSS syntax as SCSS syntax is CSS compatible