joomla/Component-Builder
joomla
/
Component-Builder
38
19
Fork 11
Code Issues 53 Pull Requests Projects 3 Releases Wiki Activity

Updated 047 Tutorial on forking JCB snippets so you can share your snippets with the rest of the Community (markdown)

Amigo 2019-08-29 09:35:11 +02:00
parent 5cd3e1c974
commit a88a21c9b8
1 changed files with 11 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
047-Tutorial-on-forking-JCB-snippets-so-you-can-share-your-snippets-with-the-rest-of-the-Community.md

@ -47,19 +47,19 @@ Good practice: Every time you want to make a change then you need to follow a fe
[00:06:50](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h06m50s)
Once this forking of the main repository has been done, you need to clone this repository down to your developing environment. Click on 'Clone' and select either SSH or HTTPS depending on how you have got Git set up in your developing environment. [00:07:14](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m14s) I would suggest using SSH as this is, of course, it is more secure. Copy 'git@github.com:Llewellynvdm/Joomla-Component-Builder-Snippets.git' and then I am going to use my users home folder for now. I am in the command line and running Linux but if you are using Windows, you have to watch tutorials on how to do Git in Windows. [00:07:47](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m47s) You might end up using a tool instead of the command line. First, it is going to be cloned. Now there is a folder called Joomla-Component-Builder-Snippets. [00:08:19](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h08m19s) I am going to change it into that folder with 'cd' and a folder name: 'Joomla-Component-Builder-Snippets' and I am in the folder and if I do 'ls-la' all the files that were on GitHub can be seen in that folder. We want to change these files, but not directly but use JCB to do the dirty work because we might have issues with the 'escaping' and all kinds of things that can go wrong. So just to have good convention whatever changes you want to make, even if you want to add files or new libraries whatever, do the export package in JCB. [00:09:01](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m01s) If you export a snippet, see that it has three values always set. We will scrutinize those three values when a pull request is made but that those name conventions must be standard. It is quite important, we have the library name Uikit, it is uppercase 'u' and space lowercase 'v2', then Common with uppercase. 'Common' is the type of snippet, then it is the name 'Animation' and obviously, it is a JSON file.
Once this forking of the main repository has been done, you need to clone this repository down to your developing environment. Click on 'Clone' and select either SSH or HTTPS depending on how you have got Git set up in your developing environment. [00:07:14](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m14s) I would suggest using SSH as this is, of course, it is more secure. Copy 'git@github.com:Llewellynvdm/Joomla-Component-Builder-Snippets.git' and then I am going to use my users home folder for now. I am in the command line and running Linux but if you are using Windows, you have to watch tutorials on how to do Git in Windows. [00:07:47](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h07m47s) You might end up using a tool instead of the command line. First, it is going to be cloned. Now there is a folder called Joomla-Component-Builder-Snippets. [00:08:19](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h08m19s) I am going to change it into that folder with 'cd' and a folder name: 'Joomla-Component-Builder-Snippets' and I am in the folder and if I do `ls-la` all the files that were on GitHub can be seen in that folder. We want to change these files, but not directly but use JCB to do the dirty work because we might have issues with the 'escaping' and all kinds of things that can go wrong. So just to have good convention whatever changes you want to make, even if you want to add files or new libraries whatever, do the export package in JCB. [00:09:01](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m01s) If you export a snippet, see that it has three values always set. We will scrutinize those three values when a pull request is made but that those name conventions must be standard. It is quite important, we have the library name Uikit, it is uppercase `u` and space lowercase `v2`, then `(Common)` with uppercase. 'Common' is the type of snippet, then it is the name `Animation slide-top reverse` and obviously, it is a `json` file.
### Convention Builds By JCB
[00:09:40](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m40s)
This is the convention and at this stage, JCB builds that. I am going to show where it gets this convention. To follow this convention is going to be very important if new snippets for the Uikit v2 Library are made, [00:09:58](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m58s) make sure that your version 2 naming in your system is the same as it is here. If you are adding a new library that is not already in our repository, then you need to make sure that you use the naming as others will understand it as the most common naming convention. If you need help with that, you can open an issue and ask one of the admin to maybe give you a suggestion of what to call the library. [00:10:31](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h10m31s) The short end of it is **please stick to the naming conventions**. Do not change this Uikit to maybe remove the space between Uikit and v2 or something like that because it will end up mismatching things. The first thing we have done was to fork a repository and have now cloned it to our offline developing environment.
This is the convention and at this stage, JCB builds that. I am going to show where it gets this convention. To follow this convention is going to be very important if new snippets for the Uikit v2 Library are made, [00:09:58](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h09m58s) make sure that your version 2 naming in your system is the same as it is here. If you are adding a new library that is not already in our repository, then you need to make sure that you use the naming as others will understand it as the most common naming convention. If you need help with that, you can open an issue and ask one of the admin to maybe give you a suggestion of what to call the library. [00:10:31](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h10m31s) The short end of it is **please stick to the naming conventions**. Do not change this `Uikit` to maybe remove the space between `Uikit` and `v2` or something like that because it will end up mismatching things. The first thing we have done was to fork a repository and have now cloned it to our offline developing environment.
### Export Snippets - New Snippet, Changed Or Improved Snippet, Move A Snippet To A Different Type
[00:10:59](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h10m59s)
Now I am going to go to JCB and will export three snippets. The one is a new snippet, the second is a changed or improved snippet, then the third is a snippet that has been moved to a different type. FooTable will be targeted. [00:11:27](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h11m27s) The FooTable snippet is at the moment in Layout. There is a better type for this snippet. We could add some more FooTables snippets, but leave that to some to you to do. I am going to move this one to the tables because it is a table. I am going to add one snippet to the Uikit v3.[00:11:57](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h11m57s) Since those snippets are still coming. I will just add one as a demonstration and then make a little change to one of these snippets just for demonstration. The first thing is FooTable, click on that, change it from Layout to Tables. No other changes will be made but to change the Type.
Now I am going to go to JCB and will export three snippets. The one is a new snippet, the second is a changed or improved snippet, then the third is a snippet that has been moved to a different type. The `FooTable` will be targeted. [00:11:27](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h11m27s) The `FooTable` snippet is at the moment in `Layout`. There is a better type for this snippet. We could add some more `FooTables` snippets, but leave that to some to you to do. I am going to move this one to the tables because it is a table. I am going to add one snippet to the Uikit v3.[00:11:57](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h11m57s) Since those snippets are still coming. I will just add one as a demonstration and then make a little change to one of these snippets just for demonstration. The first thing is FooTable, click on that, change it from Layout to Tables. No other changes will be made but to change the Type.
### Snippets Builds The File Name - Name - Library - Type
@ -89,20 +89,13 @@ Let me take another Snippet and just make a little improvement to it. I am going
[00:18:12](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h18m12s)
Next thing share snippets. I made it compile a zip file so that it is easier to move around. We could argue that we might want to just have it zip or move. Rather move the files right into your local cloned folder. Maybe we should add a switch here in the Global Options that could give the option to select the one or the other depending on what is most convenient for you. [00:18:52](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h18m52s) I am going take the snippet '/media/host/Dropbox/sandbox/joomla/tmp/snippets' and unzip it into that repository that has been cloned. (see video). First, unzip it. There are those three files(see video) that we want to make part of the repository. The repository is cloned right into my user folder. [00:19:23](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h19m23s) Go to that folder and cut this (Please follow on video). Cut and then paste it into that folder. One file gets updated and asks if it already contains a file? When a file is improved, it should be replaced. [00:19:49](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h19m49s) Therefore click 'Replace'. Now that you have added those two new files and have replaced one of them, the third one will now have this FooTable, the Tables version, and it is also at the Layout version. [00:20:09](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h20m09s) One of them needs to go there should be no duplicates. Remove this one but do not remove it via the interface. Use Git to remove the file so that you can also add a message so that when you make a pull request and see our files removed that we will know why you did it. Then it will become a discussion. This will be demonstrated in the next tutorial.
Next thing share snippets. I made it compile a zip file so that it is easier to move around. We could argue that we might want to just have it zip or move. Rather move the files right into your local cloned folder. Maybe we should add a switch here in the Global Options that could give the option to select the one or the other depending on what is most convenient for you. [00:18:52](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h18m52s) I am going take the snippet '`/media/host/Dropbox/sandbox/joomla/tmp/snippets`' and unzip it into that repository that has been cloned. (see video). First, unzip it. There are those three files(see video) that we want to make part of the repository. The repository is cloned right into my user folder. [00:19:23](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h19m23s) Go to that folder and cut this (Please follow on video). Cut and then paste it into that folder. One file gets updated and asks if it already contains a file? When a file is improved, it should be replaced. [00:19:49](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h19m49s) Therefore click 'Replace'. Now that you have added those two new files and have replaced one of them, the third one will now have this FooTable, the Tables version, and it is also at the Layout version. [00:20:09](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h20m09s) One of them needs to go there should be no duplicates. Remove this one but do not remove it via the interface. Use Git to remove the file so that you can also add a message so that when you make a pull request and see our files removed that we will know why you did it. Then it will become a discussion. This will be demonstrated in the next tutorial.
### Back To Command Line - git status To See What Happened
[00:20:39](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h20m39s)
Back to the command line. Say git status to see what happened. One has been modified and these two have been added(see video). The first thing is to remove the one that is not needed. Because we have chosen to leave spaces within our file names, then put the file name in quotations to ensure that it does not misinterpret what you doing.[00:21:10](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h21m10s) Then do a git 'rm'(remove), then the file name 'FooTable - (Layout) FooTable.json'. You could click tab after typing FooTable and then Layout and it grabs the name. Then click enter. Now it is removed.<<<<<<
Back to the command line. Say `git status` to see what happened. One has been modified and these two have been added(see video). The first thing is to remove the one that is not needed. Because we have chosen to leave spaces within our file names, then put the file name in quotations to ensure that it does not misinterpret what you doing.[00:21:10](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h21m10s) Then do a `git 'rm'(remove)`, then the file name '`FooTable - (Layout) FooTable.json`'. You could click tab after typing `FooTable` and then `Layout` and it grabs the name. Then click enter. Now it is removed.
### Commit Message
@ -116,6 +109,12 @@ If a git status is done, we will see that it is in the deleted area and you need
The next thing here is to add these new files. Do `git status`, that file has been made part of the commit, or the branch or the local files of this clone. [00:23:18](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h23m18s) We want to add those two other files. The first one to target is adding the `FooTable - (Table) FooTable.json` which we just removed. Do a `git status`. With that one added, give it a commit message. [00:23:47](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h23m47s) **Since it is so dangerous to move a snippet to another type, do make a commit message for every step.** But if you are adding like the whole new library and are contributing like 300 new snippets, it will be okay if you add all of that on the one commit message. Just ensure that it was exported via Joomla's Component Builder so that there would not be any wrong kind of code within those snippet files. At the pull request, we will scrutinize those files and have to look through them to ensure that it will not make any system unstable. [00:24:25](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h24m25s) It have to be policed to ensure that nothing gets merged into the master branch that will put everyone at risk. When you are making changes to one specific snippet and does not like doing many at a time, be as detailed as you can in your commit messages.[00:25:03](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h25m03s) The more we are aware of what you are doing, the easier it will be to merge it into the branch and to approve your pull request.<<<<<<<<<
### git commit message update
[00:25:19](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h25m19s)