joomla/Component-Builder
joomla/Component-Builder
39
23
Fork 11
Code Issues 80 Pull Requests Projects 4 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-28 11:33:10 +02:00
parent e0a407d40b
commit fab348588e
1 changed files with 9 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,7 +3,7 @@
[00:00:00](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h00m00s)
(_Click on these time links to see Youtube video_)
Now that a general overview of how things work in the new Snippet Manager has been given, the next step is to illustrate how to take shared snippets and share them.
Now that a general overview of how things work in the new Snippet Manager has been given, the next step is to illustrate how to take shared snippets and share them.
### Fork JCB Community Snippets On GitHub, Export Snippets You like To Contribute, Make Pull Request
@ -47,41 +47,39 @@ 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' 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 have 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.<<<<<<<<<
So that'll be the one change I'm going to make then. I'm going to add one snippet [00:11:57](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h11m57s) to the Uikit v3. Since those snippets are still coming. I'll just add one as a demonstration and then I'll make a little change to one of these snippets just for demonstration. The first thing a FooTable, click on that, change it from Layout to Tables. I'm not going to make any other changes I'm just changing 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. 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
[00:12:24](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h12m24s)
This brings us to those three values that must always be set and shouldn't change unless it's seriously necessary. The one is the Name, you wouldn't want to change this name unless you are a hundred present sure it should be changed. Because in effect it will create a new snippet. Because the way the snippets work it builds the File Name with the Name, the Library, and the Type. Those three components together make up the File Name, so changing any of those will in effect create a new snippet, and create a duplicate, and that's really what I want to would try to avoid that. I realized this is going to what I'm doing here now is inevitably going to cause that. [00:13:14](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h13m14s) And I think it will show you why it's not a good thing to do it. I'm doing this more for the demonstration.
This brings us to those three values that must always be set and should not change unless it is absolutely necessary. The one is the Name, do change it unless you are a hundred present sure it should be changed because in effect it will create a new snippet. The snippets build the File Name with the Name, the Library, and the Type. Those three components together make up the File Name, so changing any of those in effect will create a new snippet, and create a duplicate, that should be avoided. What I am doing here as an illustration, inevitably is going to cause that.
### Important: When Adding A Snippet - Add It To The Correct Library and Type, Give The Correct Name
[00:13:23](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h13m23s)
The reality is that when we add a snippet, we add it to the correct Library and Type and give it the correct name from the start and that we don't need to change those three again. If we do, most of the time I would expect that your pull request will be rejected. Because this will mess up many conventions and cause many duplicates across the system [00:13:49](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h13m49s) in other developers' environment where they would import this new snippet and yet end up having two of the same snippets. I hope you understand how important this part is. Save and close.
When a snippet is added, it should be added to the correct Library and Type and from the start given the correct Name so that it is not necessary to change those three again. Most of the time our pull request will be rejected because this will mess up many conventions and cause many duplicates across the system in other developers' environment when they import this new snippet. Save and close.
### Adding A New Snippet
[00:14:06](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h14m06s)
The next one I'm going to do is add a new snippet. Since I've done this recording a second time, I've already done that and this is an Accordion snippet. You'll see that I've set that Type it's a JavaScript snippet. The Name is an Accordion. The Library is Uikit v3. I look down these Types, I'm wondering if someone of the other guys won't be better at this identifying of the Types. I might even not be the guy to make the call on this. I am open to some with a better perspective who maybe knows these libraries assorting [00:14:51](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XtZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h14m51s) ideas better. I think there's a place called Collapse. Accordions could also fit under this Collapse. I know the first Accordion we added for Uikit v2 that is found on the JavaScript but then we didn't have these many Types. [00:15:17](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h15m17s) I'll just add it under Collapse for now. Again I realize that this might be a difficult thing. What could help is to go back to the actual library itself. This the link for it: https://getuikit.com/docs/accordion and to try and see how they organized it and that's the problem [00:15:40](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h15m40s) Uikit didn't give more breakdown besides calling it Components. So it's only called a Component, it doesn't specifically add into a Type. Whereas Bootstrap is doing a little better at that. That's why I'm not sure exactly where to place it now. Since Bootstrap adds it under Collapse, [00:16:07](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h16m07s) I think we won't go wrong to do the same. Save and close. There we go, we got now a very crazy risky change of a Type and a new snippet.
Next, I am going to add a new snippet. Since I have done this recording the second time, this 'Accordion' snippet is already in place. The Type is set so that it should be a JavaScript snippet. The Name is an 'Accordion'. The Library is Uikit v3. [00:14:51](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XtZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h14m51s) I think there is a place called 'Collapse'. 'Accordion' could also fit under 'Collapse'. The first Accordion we have added for Uikit v2 that was founded on the JavaScript but then we did not have these many Types.<<<<
[00:15:17](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h15m17s) I'll just add it under Collapse for now. Again I realize that this might be a difficult thing. What could help is to go back to the actual library itself. This the link for it: https://getuikit.com/docs/accordion and to try and see how they organized it and that's the problem [00:15:40](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h15m40s) Uikit didn't give more breakdown besides calling it Components. So it's only called a Component, it doesn't specifically add into a Type. Whereas Bootstrap is doing a little better at that. That's why I'm not sure exactly where to place it now. Since Bootstrap adds it under Collapse, [00:16:07](https://www.youtube.com/watch?v=0hgHeQVTLOk&list=PLQRGFI8XZ_wtGvPQZWBfDzzlERLQgpMRE&t=00h16m07s) I think we won't go wrong to do the same. Save and close. There we go, we got now a very crazy risky change of a Type and a new snippet.
### Improving A Snippet