Difference between revisions of "User:Christopherszu"

From Documentation
Line 1: Line 1:
 +
{{Template:UnderConstruction}}
 +
 
{{Template:Smalltalk_Author|
 
{{Template:Smalltalk_Author|
 
|author=Christopher Szu, Engineer, Potix Corporation
 
|author=Christopher Szu, Engineer, Potix Corporation
Line 5: Line 7:
 
}}
 
}}
 
= Introduction =
 
= Introduction =
−
In the [https://www.zkoss.org/wiki/Small_Talks/2016/May/New_Approach_for_Building_Custom_ZK_Theme previous smalltalk], we've covered how to build ZK custom theme using the newly introduced ZK Theme Template. If you are not familiar with ZK Theme Template, we'd 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 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.
−
 
 
−
Before ZK Theme Template came along, one sitution that often troubles ZK developers is trying to upgrade their ZK custom theme version to match the ZK version of the application.
 
  
−
There were no mechanism or tools provided officially, thus making it even harder.
+
Before ZK Theme Template came along, one sitution that often trouble 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 becomes a difficult task.
  
−
But since we have built ZK Theme Temaplte with Git, switching versions becomes much easier as we leverage the versioning capabilities of Git.
+
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.
 
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.
Line 19: Line 19:
 
<br/>
 
<br/>
 
We will assume you have already cloned ZK Theme Template and ran the init script. Please refer to the [https://www.zkoss.org/wiki/Small_Talks/2016/May/New_Approach_for_Building_Custom_ZK_Theme previous smalltalk] for more detail.
 
We will assume you have already cloned ZK Theme Template and ran the init script. Please refer to the [https://www.zkoss.org/wiki/Small_Talks/2016/May/New_Approach_for_Building_Custom_ZK_Theme previous smalltalk] for more detail.
−
<ol style="list-style-type: lower-alpha;">
+
<ol style="list-style-type: upper-alpha;">
 
<li>
 
<li>
−
At this stage, you should have a custom theme based on the master (newest) branch of ZK Theme Template.
+
After git clone and init script, you should have a custom theme based on the master (newest) branch of ZK Theme Template.
 
</li>
 
</li>
 
<li>
 
<li>
−
Remember your theme version should match the ZK version of your application. For this demo, we will assume ZK version is 7.0.2 initially and upgraded to 7.0.8 afterwards.
+
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.
 
</li>
 
</li>
 
<li>
 
<li>
−
We will make two changes, one of them will cause git merge conflict when we perform the upgrade later
+
Switch to ZK 7.0.2 with the following command.
 +
<source lang="text">
 +
➜ git checkout -b custom-theme v7.0.2
 +
</source>
 +
* This will create a branch called "custom-theme" based on ZK 7.0.2 tag "v7.0.2"
 
</li>
 
</li>
 
<li>
 
<li>
−
We'll edit '''src/archive/web/zul/less/_zkvariables.less''', the file where all the colors are defined.
+
We will make two changes, one of them will cause git merge conflict when we perform the upgrade later.
 +
</li>
 +
<li>
 +
For the first change, we'll edit '''src/archive/web/zul/less/_zkvariables.less''', the file where all the colors are defined.
 
</li>
 
</li>
 
<li>
 
<li>
Line 42: Line 49:
 
@windowBackgroundColor: #FF8888;
 
@windowBackgroundColor: #FF8888;
 
</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.
 
</li>
 
</li>
 
<li>
 
<li>
−
We'll edit '''src/archive/web/zul/less/_zkvariables.less''', the file where all the colors are defined.
+
For the second 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 button height of the ZK toolbar component <br/>
 
from
 
from
−
<source lang="text">
+
<source lang="text" high="3">
−
@windowBackgroundColor: #D9E5EF;
+
.z-toolbarbutton {
 +
display: inline-block;
 +
height: @baseButtonHeight;
 +
border: 1px solid transparent;
 +
//omitted for brevity
 +
}
 
</source>
 
</source>
 
to
 
to
−
<source lang="text">
+
<source lang="text" high="3">
−
@windowBackgroundColor: #FF8888;
+
.z-toolbarbutton {
 +
display: inline-block;
 +
height: 30px;
 +
border: 1px solid transparent;
 +
//omitted for brevity
 +
}
 
</source>
 
</source>
 
</li>
 
</li>
 
<li>
 
<li>
−
If you build the theme right now, you'll get a ZK 7.0.2 custom theme. But since we want to upgrade to ZK xxx, let's just commit the changes for now.
+
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.
 
<source lang="text">
 
<source lang="text">
 
➜ git add -u
 
➜ git add -u
−
➜ git commit -m "some changes"
+
➜ git commit -m "made some changes"
 
</source>
 
</source>
 
</li>
 
</li>
 
<li>
 
<li>
−
Let's upgrade from current version to ZK xxx.
+
Let's upgrade from current version ZK 7.0.2 to ZK 7.0.8.
−
<source lang="text">
+
<source lang="text" high="17, 25, 36, 44">
 
➜ git tag -l
 
➜ git tag -l
−
➜ git fetch vxxxx
+
v7.0.0
−
➜ git merge vxxxx
+
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: 30px;
 +
        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.
 
</source>
 
</source>
 +
* 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 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 44: git 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>
−
Run '''git pull upstream''' to receive the latest change in ZK template theme- for example CSS related bug fixes. This way, if your customization has any conflict with ZK's change, you will see git merge conflict messages.
+
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.
 +
<source lang="text" high="4, 5, 6, 7">
 +
// Toolbarbutton
 +
.z-toolbarbutton {
 +
display: inline-block;
 +
<<<<<<< HEAD
 +
height: 30px;
 +
=======
 +
>>>>>>> v7.0.8
 +
border: 1px solid transparent;
 +
.borderRadius(@borderRadiusSmall);
 +
margin: 0 2px;
 +
</source>
 +
* Line 4-7: We can see that there is no height attribute in v7.0.8, but inteh HEAD revision there is, since we decided that the change is needed, we will keep the height attribute.
 +
</li>
 +
<li>
 +
After removing the conflict message in '''toolbar.less''', this is what we have now.
 +
<source lang="text" high="4">
 +
// Toolbarbutton
 +
.z-toolbarbutton {
 +
display: inline-block;
 +
height: 30px;
 +
border: 1px solid transparent;
 +
.borderRadius(@borderRadiusSmall);
 +
margin: 0 2px;
 +
</source>
 +
</li>
 +
<li>
 +
Now we can finish the merge process by commiting the changes we've just made.
 +
<source lang="text" high="39">
 +
➜ git status
 +
On branch v7.0.8
 +
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
 +
</source>
 +
* Line 39: The file with merge conflict will be marked "both modified"
 +
</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.
 
</li>
 
</li>
 
</ol>
 
</ol>
Line 80: Line 219:
 
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, especially with pull and merge.
+
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.
 +
<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.
  
 
{{Template:CommentedSmalltalk_Footer_new|
 
{{Template:CommentedSmalltalk_Footer_new|

Revision as of 04:56, 15 June 2016

WarningTriangle-32x32.png This page is under construction, so we cannot guarantee the accuracy of the content!


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

Introduction

In the 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.

Before ZK Theme Template came along, one sitution that often trouble 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 becomes 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.
  2. 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.
  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.
  5. For the first change, we'll edit src/archive/web/zul/less/_zkvariables.less, the file where all the colors are defined.
  6. Change the background color of the ZK window component
    from 
    @windowBackgroundColor: #D9E5EF;

    to 

    @windowBackgroundColor: #FF8888;

    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.

  7. For the second change, We'll edit src/archive/web/js/zul/wgt/less/toolbar.less, the style file for ZK toolbar component.
  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: 30px;
	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: 30px;
        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, buy you should replace that name with whatever you named 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 44: git 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 v7.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: 30px;
=======
>>>>>>> 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 inteh 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: 30px;
	border: 1px solid transparent;
	.borderRadius(@borderRadiusSmall);
	margin: 0 2px;
  13. Now we can finish the merge process by commiting the changes we've just made. 
    ➜ git status
On branch v7.0.8
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.

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.
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.


Comments



Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.
Retrieved from "https://www.zkoss.org/_w/index.php?title=User:Christopherszu&oldid=45005"