Upgrade Your Custom ZK Theme"

From Documentation
m
(9 intermediate revisions by 2 users not shown)
Line 4: Line 4:
 
|version=ZK 8.0.2
 
|version=ZK 8.0.2
 
}}
 
}}
 
{{Template:UnderConstruction}}
 
  
 
= Introduction =
 
= Introduction =
In the [https://www.zkoss.org/wiki/Small_Talks/2016/May/New_Approach_for_Building_Custom_ZK_Theme previous smalltalk], we have covered how to build ZK custom theme using the newly introduced ZK Theme Template. If you are not familiar with ZK Theme Template, we recommend a quick read through.
+
In the [https://www.zkoss.org/wiki/Small_Talks/2016/May/New_Approach_for_Building_Custom_ZK_Theme previous smalltalk], we covered how to build ZK custom theme using the newly introduced ZK Theme Template. If you are not familiar with ZK Theme Template, we recommend a quick read through.
  
 
Before ZK Theme Template came along, one situation that often troubled ZK developers is upgrading their ZK custom theme to match the ZK version of the application. Since there were no mechanism or tools provided officially, upgrading had become a difficult task.
 
Before ZK Theme Template came along, one situation that often troubled ZK developers is upgrading their ZK custom theme to match the ZK version of the application. Since there were no mechanism or tools provided officially, upgrading had become a difficult task.
Line 22: Line 20:
 
<ol style="list-style-type: upper-alpha;">
 
<ol style="list-style-type: upper-alpha;">
 
<li>
 
<li>
After git clone and init script, you should have a custom theme based on the master (newest) branch of ZK Theme Template. But since we are going to checkout another revision, we should commit the changes made by init.sh script.
+
After git clone and init script, you should have a custom theme based on the master (newest) branch of ZK Theme Template. But since we are going to check out another revision, we should commit the changes made by init.sh script.
 
<source lang="text" high="19">
 
<source lang="text" high="19">
 
➜ git status
 
➜ git status
Line 42: Line 40:
 
   (use "git add <file>..." to include in what will be committed)
 
   (use "git add <file>..." to include in what will be committed)
  
         src/org/zkoss/theme/red/
+
         src/org/zkoss/theme/biggerToolbarButton/
  
 
no changes added to commit (use "git add" and/or "git commit -a")
 
no changes added to commit (use "git add" and/or "git commit -a")
 
➜ git add -A
 
➜ git add -A
➜ git commit -m "init red theme"
+
➜ git commit -m "init biggerToolbarButton theme"
 
</source>
 
</source>
 
</li>
 
</li>
* Line 19: for this demostration, the theme is going to be called "red"
+
* Line 19: for this demonstration, the theme is going to be called "biggerToolbarButton"
 
<li>
 
<li>
Remember your theme version should match the ZK version of your application. For this demostration, we will assume ZK version is 7.0.2 initially and upgrade to 7.0.8 later.
+
Remember your theme version should match the ZK version of your application. For this demonstration, we will assume ZK version is 7.0.2 initially and upgrade to 7.0.8 later.
 
</li>
 
</li>
 
<li>
 
<li>
Line 61: Line 59:
 
</li>
 
</li>
 
<li>
 
<li>
We will make two changes, one of them will cause git merge conflict when we perform the upgrade later.
+
We will make two changes, one of them will cause git merge conflict when we perform the upgrade later. This is what ZK toolbar component looks like in ZK 7.0.2.
 +
<br/>
 +
[[File:Theme_smalltalk_2nd_before.PNG]]
 
</li>
 
</li>
 
<li>
 
<li>
For the first change, we'll edit '''src/archive/web/zul/less/_zkvariables.less''', the file where all the colors are defined.
+
For the first change, we'll edit '''src/archive/web/js/zul/wgt/less/toolbar.less''', the style file for ZK toolbar component.
 
</li>
 
</li>
 
<li>
 
<li>
Change the background color of the ZK window component <br/>
+
Change the line-height of the ZK toolbar button content<br/>
 
from
 
from
<source lang="text">
+
<source lang="text" high="4">
@windowBackgroundColor: #D9E5EF;
+
.z-toolbarbutton-content {
 +
.fontStyle(@baseTitleFontFamily, @fontSizeSmall, normal, @baseTextColor);
 +
padding: 2px;
 +
line-height: @baseLineHeight + 6;
 +
vertical-align: middle;
 +
position: relative;
 +
text-shadow: 0 1px #FFFFFF;
 +
white-space:nowrap;
 +
}
 
</source>
 
</source>
 
to
 
to
<source lang="text">
+
<source lang="text" high="4">
@windowBackgroundColor: #FF8888;
+
.z-toolbarbutton-content {
 +
.fontStyle(@baseTitleFontFamily, @fontSizeSmall, normal, @baseTextColor);
 +
padding: 2px;
 +
line-height: 36px;
 +
vertical-align: middle;
 +
position: relative;
 +
text-shadow: 0 1px #FFFFFF;
 +
white-space:nowrap;
 +
}
 
</source>
 
</source>
since ZK did not change the window background color between 7.0.2 and 7.0.8, this change should not cause any git merge conflict.
+
since ZK did not change the toolbar button content between 7.0.2 and 7.0.8, this change should not cause any git merge conflict.
 
</li>
 
</li>
 
<li>
 
<li>
For the second change, We'll edit '''src/archive/web/js/zul/wgt/less/toolbar.less''', the style file for ZK toolbar component.
+
For the second change, we'll edit different part of the same '''toolbar.less'''.
 
</li>
 
</li>
 
<li>
 
<li>
Line 96: Line 112:
 
.z-toolbarbutton {
 
.z-toolbarbutton {
 
display: inline-block;
 
display: inline-block;
height: 30px;
+
height: 40px;
 
border: 1px solid transparent;
 
border: 1px solid transparent;
 
//omitted for brevity
 
//omitted for brevity
Line 147: Line 163:
 
  .z-toolbarbutton {
 
  .z-toolbarbutton {
 
         display: inline-block;
 
         display: inline-block;
-      height: 30px;
+
-      height: 40px;
 
         border: 1px solid transparent;
 
         border: 1px solid transparent;
 
         .borderRadius(@borderRadiusSmall);
 
         .borderRadius(@borderRadiusSmall);
Line 159: Line 175:
 
</source>
 
</source>
 
* Line 17: the tag name for ZK 7.0.8 is "v7.0.8"
 
* Line 17: the tag name for ZK 7.0.8 is "v7.0.8"
* Line 25: "origin" is being used here, buy you should replace that name with whatever you named the ZK Theme Template repository.
+
* Line 25: "origin" is being used here, but you should replace that name with whatever name you used for the ZK Theme Template repository.
* Line 36: ZK 7.0.8 removed the height attribute of .z-toolbarbutton class, but we've also made a change to the height attribute, this surely will cause a git auto merge conflict later on.
+
* Line 36: ZK 7.0.8 removed the height attribute of .z-toolbarbutton class, but we've also made a change to the height attribute; this will surely cause a git auto merge conflict later on.
* Line 44: git letting us know it cannot figure out how to automatically merge the change ZK 7.0.8 and we both made .
+
* Line 44: git is letting us know it cannot figure out how to automatically merge the change ZK 7.0.8 and we both made .
 
</li>
 
</li>
 
<li>
 
<li>
As you can see, our second change creates a git auto merge conflict with ZK v7.0.8. To resolve this conflict, simply open '''toolbar.less''' in your editor of choice, and make the following changes.
+
As you can see, our second change creates a git auto merge conflict with ZK 7.0.8. To resolve this conflict, simply open '''toolbar.less''' in your editor of choice, and make the following changes.
 
<source lang="text" high="4, 5, 6, 7">
 
<source lang="text" high="4, 5, 6, 7">
 
// Toolbarbutton
 
// Toolbarbutton
Line 170: Line 186:
 
display: inline-block;
 
display: inline-block;
 
<<<<<<< HEAD
 
<<<<<<< HEAD
height: 30px;
+
height: 40px;
 
=======
 
=======
 
>>>>>>> v7.0.8
 
>>>>>>> v7.0.8
Line 177: Line 193:
 
margin: 0 2px;
 
margin: 0 2px;
 
</source>
 
</source>
* Line 4-7: We can see that there is no height attribute in v7.0.8, but in the HEAD revision there is, since we decided that the change is needed, we will keep the height attribute.
+
* Line 4-7: We can see that there is no height attribute in v7.0.8, but in the HEAD revision there is. Since we decided that the change is needed, we will keep the height attribute.
 
</li>
 
</li>
 
<li>
 
<li>
Line 185: Line 201:
 
.z-toolbarbutton {
 
.z-toolbarbutton {
 
display: inline-block;
 
display: inline-block;
height: 30px;
+
height: 40px;
 
border: 1px solid transparent;
 
border: 1px solid transparent;
 
.borderRadius(@borderRadiusSmall);
 
.borderRadius(@borderRadiusSmall);
Line 192: Line 208:
 
</li>
 
</li>
 
<li>
 
<li>
Now we can finish the merge process by commiting the changes we've just made.
+
Now we can finish the merging process by committing the changes we've just made.
 
<source lang="text" high="39">
 
<source lang="text" high="39">
 
➜ git status
 
➜ git status
On branch v7.0.8
+
On branch custom-theme
 
You have unmerged paths.
 
You have unmerged paths.
 
   (fix conflicts and run "git commit")
 
   (fix conflicts and run "git commit")
Line 239: Line 255:
 
</li>
 
</li>
 
<li>
 
<li>
Now we're done with the upgrade. Run '''mvn clean package''' to build your newly updated custom theme and test it out in your application.
+
Now we're done with the upgrade. Run '''mvn clean package''' to build your newly updated custom theme and test it out in your application. After our changes applied, this is now what the toolbar buttons look like (slightly bigger).
 +
        <br/>
 +
        [[File:Theme_smalltalk_2nd_after.PNG‎]]
 
</li>
 
</li>
 
</ol>
 
</ol>
Line 246: Line 264:
 
Although this new approach gives ZK developers more freedom to create their own theme, there are still some inconveniences.
 
Although this new approach gives ZK developers more freedom to create their own theme, there are still some inconveniences.
 
<br/>
 
<br/>
ZK developers not familiar with git might find all the git commands intimidating, so here is the official git [https://git-scm.com/book/en/v2 book] and [https://git-scm.com/documentation documentation] for reference. Alternatively, you can use your favorite GUI git tools like [https://www.sourcetreeapp.com/ sourcetree] to eleminate the need to type in commands manually.
+
ZK developers not familiar with git might find all the git commands intimidating, so here is the official git [https://git-scm.com/book/en/v2 book] and [https://git-scm.com/documentation documentation] for reference. Alternatively, you can use your favorite GUI git tools like [https://www.sourcetreeapp.com/ sourcetree] to eliminate the need to type in commands manually.
 
<br/>
 
<br/>
One thing to bear in mind when upgrading version is that some ZK bug fixes might include adjustments in .less files, so if you were to remove any existing styles, make sure they don't break your application before continue.
+
One thing to bear in mind when upgrading version is that some ZK bug fixes might include adjustments in .less files, so if you were to remove any existing styles, make sure they don't break your application before continuing.
  
 
= Existing Custom Themes =
 
= Existing Custom Themes =
Many ZK developers might already have an existing custom theme ''not'' based on the newly introduced ZK Theme Template, so one might ask is it possible to adpot the new structure of ZK Theme Template? Or is there any way old custom themes can be converted into ZK Theme Template format? Stay tuned for the next smalltalk where we will investigate the possibility of upgrading your current custom theme to adopt the new structure of ZK Theme Template.
+
Many ZK developers might already have an existing custom theme ''not'' based on the newly introduced ZK Theme Template, so one might ask is it possible to adopt the new structure of ZK Theme Template? Or is there a way for old custom themes to be converted into ZK Theme Template format? Stay tuned for the next smalltalk where we will investigate the possibility of upgrading your current custom theme to adopt the new structure of ZK Theme Template.
  
 
{{Template:CommentedSmalltalk_Footer_new|
 
{{Template:CommentedSmalltalk_Footer_new|

Revision as of 02:11, 21 June 2016

DocumentationSmall Talks2016JuneUpgrade Your Custom ZK Theme
Upgrade Your Custom ZK Theme

Author
Christopher Szu, Engineer, Potix Corporation
Date
Jun 21, 2016
Version
ZK 8.0.2

Introduction

In the previous smalltalk, we covered how to build ZK custom theme using the newly introduced ZK Theme Template. If you are not familiar with ZK Theme Template, we recommend a quick read through.

Before ZK Theme Template came along, one situation that often troubled ZK developers is upgrading their ZK custom theme to match the ZK version of the application. Since there were no mechanism or tools provided officially, upgrading had become a difficult task.

To mitigate the difficulty, we have built ZK Theme Template with git, making it much easier to switch between versions as we leverage the versioning capabilities of git.

In this smalltalk, we will show you how to build your custom theme based on any version of ZK, and how to switch to a different version.

Steps to Upgrading Your Custom Theme

Follow these steps to upgrade your own custom theme based on ZK's new theme template.
We will assume you have already cloned ZK Theme Template and ran the init script. Please refer to the previous smalltalk for more detail.

  1. After git clone and init script, you should have a custom theme based on the master (newest) branch of ZK Theme Template. But since we are going to check out another revision, we should commit the changes made by init.sh script.
    ➜ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    Changes not staged for commit:
      (use "git add/rm <file>..." to update what will be committed)
      (use "git checkout -- <file>..." to discard changes in working directory)
    
            modified:   pom.xml
            modified:   readme.txt
            modified:   src/archive/metainfo/zk/config.xml
            modified:   src/archive/metainfo/zk/lang-addon.xml
            deleted:    src/org/zkoss/theme/___THEME_NAME___/Version.java
            deleted:    src/org/zkoss/theme/___THEME_NAME___/___THEME_NAME_CAP___ThemeWebAppInit.java
            modified:   version
    
    Untracked files:
      (use "git add <file>..." to include in what will be committed)
    
            src/org/zkoss/theme/biggerToolbarButton/
    
    no changes added to commit (use "git add" and/or "git commit -a")
    ➜ git add -A
    ➜ git commit -m "init biggerToolbarButton theme"
    
    • Line 19: for this demonstration, the theme is going to be called "biggerToolbarButton"
  2. Remember your theme version should match the ZK version of your application. For this demonstration, we will assume ZK version is 7.0.2 initially and upgrade to 7.0.8 later.
  3. Switch to ZK 7.0.2 with the following command.
    ➜ git checkout -b custom-theme v7.0.2
    
    • This will create a branch called "custom-theme" based on ZK 7.0.2 tag "v7.0.2"
  4. We will make two changes, one of them will cause git merge conflict when we perform the upgrade later. This is what ZK toolbar component looks like in ZK 7.0.2.
    Theme smalltalk 2nd before.PNG
  5. For the first change, we'll edit src/archive/web/js/zul/wgt/less/toolbar.less, the style file for ZK toolbar component.
  6. Change the line-height of the ZK toolbar button content
    from
    .z-toolbarbutton-content {
    	.fontStyle(@baseTitleFontFamily, @fontSizeSmall, normal, @baseTextColor);
    	padding: 2px;
    	line-height: @baseLineHeight + 6;
    	vertical-align: middle;
    	position: relative;
    	text-shadow: 0 1px #FFFFFF;
    	white-space:nowrap;
    }
    

    to

    .z-toolbarbutton-content {
    	.fontStyle(@baseTitleFontFamily, @fontSizeSmall, normal, @baseTextColor);
    	padding: 2px;
    	line-height: 36px;
    	vertical-align: middle;
    	position: relative;
    	text-shadow: 0 1px #FFFFFF;
    	white-space:nowrap;
    }
    

    since ZK did not change the toolbar button content between 7.0.2 and 7.0.8, this change should not cause any git merge conflict.

  7. For the second change, we'll edit different part of the same toolbar.less.
  8. Change the button height of the ZK toolbar component
    from
    .z-toolbarbutton {
    	display: inline-block;
    	height: @baseButtonHeight;
    	border: 1px solid transparent;
    	//omitted for brevity
    }
    

    to

    .z-toolbarbutton {
    	display: inline-block;
    	height: 40px;
    	border: 1px solid transparent;
    	//omitted for brevity
    }
    
  9. If you build the theme right now, you'll get a ZK 7.0.2 based custom theme. But since we want to upgrade to ZK 7.0.8, let's just commit the changes for now.
    ➜ git add -u
    ➜ git commit -m "made some changes"
    
  10. Let's upgrade from current version ZK 7.0.2 to ZK 7.0.8.
    ➜ git tag -l
    v7.0.0
    v7.0.0-Preview
    v7.0.0-RC
    v7.0.1
    v7.0.2
    v7.0.3
    v7.0.3.1
    v7.0.3.2
    v7.0.4
    v7.0.5
    v7.0.5.1
    v7.0.5.2
    v7.0.6
    v7.0.6.1
    v7.0.7
    v7.0.8
    v8.0.0
    v8.0.0-RC
    v8.0.1
    v8.0.1.1
    v8.0.2
    v8.0.2.1
    v8.0.EL.2.2
    ➜ git fetch origin v7.0.8
    ➜ git diff HEAD v7.0.8
    ...
    diff --git a/src/archive/web/js/zul/wgt/less/toolbar.less b/src/archive/web/js/zul/wgt/less/toolbar.less
    index 72e90d6..b3b51e5 100644
    --- a/src/archive/web/js/zul/wgt/less/toolbar.less
    +++ b/src/archive/web/js/zul/wgt/less/toolbar.less
    @@ -57,7 +57,6 @@
     // Toolbarbutton
     .z-toolbarbutton {
            display: inline-block;
    -       height: 40px;
            border: 1px solid transparent;
            .borderRadius(@borderRadiusSmall);
            margin: 0 2px;
    ...
    ➜ git merge v7.0.8
    Auto-merging src/archive/web/zul/less/_zkvariables.less
    Auto-merging src/archive/web/js/zul/wgt/less/toolbar.less
    CONFLICT (content): Merge conflict in src/archive/web/js/zul/wgt/less/toolbar.less
    Automatic merge failed; fix conflicts and then commit the result.
    
    • Line 17: the tag name for ZK 7.0.8 is "v7.0.8"
    • Line 25: "origin" is being used here, but you should replace that name with whatever name you used for the ZK Theme Template repository.
    • Line 36: ZK 7.0.8 removed the height attribute of .z-toolbarbutton class, but we've also made a change to the height attribute; this will surely cause a git auto merge conflict later on.
    • Line 44: git is letting us know it cannot figure out how to automatically merge the change ZK 7.0.8 and we both made .
  11. As you can see, our second change creates a git auto merge conflict with ZK 7.0.8. To resolve this conflict, simply open toolbar.less in your editor of choice, and make the following changes.
    // Toolbarbutton
    .z-toolbarbutton {
    	display: inline-block;
    <<<<<<< HEAD
    	height: 40px;
    =======
    >>>>>>> v7.0.8
    	border: 1px solid transparent;
    	.borderRadius(@borderRadiusSmall);
    	margin: 0 2px;
    
    • Line 4-7: We can see that there is no height attribute in v7.0.8, but in the HEAD revision there is. Since we decided that the change is needed, we will keep the height attribute.
  12. After removing the conflict message in toolbar.less, this is what we have now.
    // Toolbarbutton
    .z-toolbarbutton {
    	display: inline-block;
    	height: 40px;
    	border: 1px solid transparent;
    	.borderRadius(@borderRadiusSmall);
    	margin: 0 2px;
    
  13. Now we can finish the merging process by committing the changes we've just made.
    ➜ git status
    On branch custom-theme
    You have unmerged paths.
      (fix conflicts and run "git commit")
    
    Changes to be committed:
    
            new file:   src/archive/web/js/zkmax/inp/ext/icons-black-2x.png
            new file:   src/archive/web/js/zkmax/inp/ext/icons-black.png
            new file:   src/archive/web/js/zkmax/inp/ext/icons-white-2x.png
            new file:   src/archive/web/js/zkmax/inp/ext/icons-white.png
            new file:   src/archive/web/js/zkmax/inp/less/tbeditor.less
            new file:   src/archive/web/js/zkmax/inp/less/timepicker.less
            new file:   src/archive/web/js/zkmax/layout/less/rowlayout.less
            modified:   src/archive/web/js/zul/grid/less/grid.less
            modified:   src/archive/web/js/zul/inp/less/combo.less
            modified:   src/archive/web/js/zul/mesh/less/paging.less
            modified:   src/archive/web/js/zul/sel/less/listbox.less
            modified:   src/archive/web/js/zul/sel/less/tree.less
            modified:   src/archive/web/js/zul/wgt/less/caption.less
            modified:   src/archive/web/zkmax/less/tablet/_calendar.less
            modified:   src/archive/web/zkmax/less/tablet/_combo.less
            modified:   src/archive/web/zul/less/_reset.less
            modified:   src/archive/web/zul/less/_zkmixins.less
            modified:   src/archive/web/zul/less/_zkvariables.less
            new file:   src/archive/web/zul/less/font/_animated.less
            new file:   src/archive/web/zul/less/font/_bordered-pulled.less
            new file:   src/archive/web/zul/less/font/_fixed-width.less
            new file:   src/archive/web/zul/less/font/_larger.less
            new file:   src/archive/web/zul/less/font/_list.less
            new file:   src/archive/web/zul/less/font/_mixins.less
            new file:   src/archive/web/zul/less/font/_rotated-flipped.less
            new file:   src/archive/web/zul/less/font/_stacked.less
            modified:   src/archive/web/zul/less/norm.less
    
    Unmerged paths:
      (use "git add <file>..." to mark resolution)
    
            both modified:   src/archive/web/js/zul/wgt/less/toolbar.less
    ➜ git add -u
    ➜ git commit
    
    • Line 39: The file with merge conflict will be marked "both modified"
  14. Now we're done with the upgrade. Run mvn clean package to build your newly updated custom theme and test it out in your application. After our changes applied, this is now what the toolbar buttons look like (slightly bigger).
    Theme smalltalk 2nd after.PNG

Known Difficulties

Although this new approach gives ZK developers more freedom to create their own theme, there are still some inconveniences.
ZK developers not familiar with git might find all the git commands intimidating, so here is the official git book and documentation for reference. Alternatively, you can use your favorite GUI git tools like sourcetree to eliminate the need to type in commands manually.
One thing to bear in mind when upgrading version is that some ZK bug fixes might include adjustments in .less files, so if you were to remove any existing styles, make sure they don't break your application before continuing.

Existing Custom Themes

Many ZK developers might already have an existing custom theme not based on the newly introduced ZK Theme Template, so one might ask is it possible to adopt the new structure of ZK Theme Template? Or is there a way for old custom themes to be converted into ZK Theme Template format? Stay tuned for the next smalltalk where we will investigate the possibility of upgrading your current custom theme to adopt the new structure of ZK Theme Template.


Comments



Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.