Code
All on Github.
Development environment
I prefer to use Visuals Studio Code.
Source code
In general the ‘rules’ are:
ES5 compliant
Styling if possible via creative.css
Server code PHP 5 compliant
use ‘prettier’ for code formatting
eslint should give no warnings
Some users still have a ES5 browser, like old Android tablets. In the past I used the ‘ const’ keyword a few times. This resulted in complaints.
For ES5 vs ES6 see for instance: http://es6-features.org
We could switch to ES6, but then probably we have to start using Babel as well, to transpile back to ES5. This is something I would like to prevent, because it makes the develop/build environment a bit more demanding.
Guidelines:
No ES6 syntax, like ‘const’, ‘let’, arrow functions, class keyword, object spread, Promise.
No synchronous AJAX calls.
jQuery promises may be used.
Dependencies
Most external libraries are managed via npm and bundled with Webpack. If you need to update the bundle, follow the following steps.
Install node
Install the dependencies
npm install
Build the bundle
npm run build
The sources for the bundle can be found in src/
These files will be transpiled with Babel to ES5.
The Swiper library is in ES6 format, and will be transpiled to ES5 as well. See babel.config.js
for the configuration.
The regular Dashticz files will NOT be transpiled: They should be in ES5 format.
jQuery 3.4.1
In December 2019 Dashticz was upgraded from jQuery 2.2.4 to jQuery 3.4.1, because of a reported security vulnerability in jQuery 2.2.4.
Migration is checked via jquery-migrate plugin, which can be enabled in src/index.js
.
The spectrum-colorpicker is not fully compatible with jQuery 3. The jquery-migrate plugin generates warnings in the console if the jquery-migrate
plugin is enabled.
Design
Since v3.2.0 a standard component will be used for most special blocks. All blocks are loaded by js/dashticz.js
.
The source code for each block can be found in the js/components
folder.
If you want to add a new block with the name ‘myblock’, then follow the following steps:
Create the file js/components/myblock.js
. A minimal implementation should contain the following:
var DT_myblock = {
name: "myblock",
run: function (me) {
//this function will be called after the component has been initialized and has been mounted into the DOM.
//me.mountPoint: Mountpoint of the container (dt_block)
//For basic usage you will add additional code to $(me.mountPoint + ' .dt_state')
//me.block: Reference to the block definition in CONFIG.js
}
}
Dashticz.register(DT_myblock); //Don't forget to register the block
Add 'myblock'
to the components variable at the start of js/dashticz.js
An example of a more extensive implementation:
var DT_myblock = {
name: "myblock",
canHandle: function (block, key) {
//returns a boolean to indicate whether the block can be handled by this component
//key is the identifier (string) that is used in the column definition to select a block.
//In case an object is provided in the column definitions (like buttons, frames) then key is undefined
},
init: function () {
//Will be called for initialization
//returns a jquery deferred (similar to a Promise)
},
defaultCfg: { //All optional. defaultCfg can also be a function and then will receive block as parameter.
icon: 'fas fa-newspaper', // string to define the default icon
containerClass: function (block) { //function returning a string containing class names that will be added to the block
return 'hover'
}, //Or:
containerClass: 'hover',
containerExtra: function (block) { //function or string returning additional settings for the container HTML element (dt_block)
return (block && block.maxheight) ? ' style="max-height:' + block.maxheight + 'px;overflow:hidden;"' : ''
}
},
defaultContent: function (me) { //Optional. function (or string) returning the static content of dt_state
return '<ul id="newsTicker"></div>'
},
run: function (me) {
//this function will be called after the component has been initialized and has been mounted into the DOM.
//me.mountPoint: Mountpoint of the container (dt_block)
//For basic usage you will add additional code to $(me.mountPoint + ' .dt_state')
//me.block: Reference to the block definition in CONFIG.js
},
refresh: function (me) {
// if me.block.refresh is defined, and this function exists, then this function will be called every <me.block.refresh> seconds.
}
}
Dashticz.register(DT_myblock); //Don't forget to register the block
Add 'myblock'
to the components variable at the start of js/dashticz.js
The following key words are reserved and should not be modified in me
or block
:
key
mountPoint
type
name
And specifically for me
:
block
Github workflow
We use a PR (Pull Request) based workflow, with preferably one new/changing feature per branch. All work is derived from the beta branch. If the beta branch is stable, a master branch will be derived from the beta branch.
For big changes a temporary branch will be created to test the new functionality by a bigger audience.
Basic workflow
Create an account on Github.com
Fork the Dashticz repository on github.com
Clone your own repository locally:
cd <working directory of choice> git clone https://github.com/<username>/dashticz cd dashticz
Add the dashticz upstream remote:
git remote add upstream https://github.com/Dashticz/dashticz
Get the latest changes:
git checkout beta git fetch upstream git merge upstream/beta
Create a new branch for your changes:
git checkout -b mynewfeature
Make the changes
Add the new files (if any):
git add .
Commit the changes:
git commit -am "My new feature"
Push the changes to your own Dashticz repository:
git push origin mynewfeature
On github.com create a Pull Request with the request to merge your own branch into beta
Have some patience, and lokonli will merge your PR
After your PR has been merged, you should cleanup your repository.
Delete your mynewfeature branch from your Dashticz repository on github.
Switch back to the beta branch:
git checkout beta
get the new beta:
git fetch upstream git merge upstream/beta
Delete your local mynewfeature branch. It’s not needed anymore, because it has been merged:
git branch -d mynewfeature
If you want to make additional changes, go back to step 6
Test branch
If additional testing is required then lokonli will not merge directly into beta (step 12), but will create a test branch. To continue working on this testbranch:
git fetch upstream
git checkout testbranch
git merge upstream/testbranch
git checkout -b mynewfeature
Then you have a new branch ‘mynewfeature’ derived from testbranch. Continue with step 7-10 to make your changes.
On github create a PR with the request to merge your new branch into testbranch.
Updating documentation
If possible update the documentation together with your code changes in the same PR. For updating the documentation see Documentation