046 General overview of how community snippets work

GENERAL OVERVIEW OF HOW COMMUNITY SNIPPETS WORK

Added A Community Concept To Snippets In JCB

I would like to give you a tutorial on the new Snippet Manager and how it works. 00:00:07 We are very excited to announce that we have added a community concept to the Snippets in JCB. Previously you could create your own Snippets and then if you would to create a Custom Admin View, a Site View, a Template or a Layout, 00:00:25 you could access the Snippets through a drop down. Let me demonstrate that quickly. Now in a Site View, if I were to click on one of these Snippets, you will see it loads the Snippet here. You can copy it from here, and you can then place it in your code 00:00:44 and so it is possible to load many Snippets.

New Snippet Area

Now currently we already looking at the new Snippets Area. You will see that we have the type of the Snippet first, then the name of the Snippet and then the library 00:01:04 the snippet belongs to. Once you've selected the Snippet again and updates: the name of the Snippet(text truncate), the type of Snippet(Common), and the library it belongs to(see more details(UitKit v2). Usually this library is a link, it'll open you to the actual documentation on that library's website of the specific Snippet. So that's all as it used to be, nothing fancy, nothing much different.

Local And Community Snippets

Yet there are major changes 00:01:32 taken place because we have what is known as local Snippets, and then community Snippets. We have enlarge the Snippets area so that you can contribute to the community Snippets, and also import from those Snippets that is been added to the community by others. 00:01:56

Contribute Snippets To The Community - Import Snippets That Is Been Added To The Community By Others

Now how does that exactly work. Well Snippets that already exist are Snippets that either I made or someone else and they already have what is known as a contributor. The name of the contributor, it's email address, web address and so forth. When you create a Snippet 00:02:19 we will use your details to create this contribution. If we open an existing Snippet and you go to the contribution area, you'd see that there is names in these Fields. If there aren't any names then that means the update didn't do exactly what it should have done. When you go to the Snippets area 00:02:46 where you get Snippets, I'll show you that in a moment, there is a place for you to update all the contributor names. Be sure to have their names in the Database. The reality is these details should be in there already. If they are not, it's not a Snippet you made. You don't need to really worry about it. These details only really apply when you want to share a Snippet or when you want to improve a Snippet and then we will add the correct details in any way. So really it's not to be worried about. Here you'll see 'How Contributed Details Work' 00:03:25 are dealt with. We are using your company details that is set in the global Options you could click 'Option' button to get there under the company tab of the JCB for the new Snippets you create. You cannot change the Contributed Details of the Snippet that already exist at this time via this area. So that is a simple heads up. This area is really only for the management of the community Snippets. 00:03:52 If you're not going to be contributing then this doesn't even matter at all.

Important - Snippets Mapped The Same Way As Snippets in The Community

What is important though is that your Snippet be mapped the same way as the Snippets in the community. For example if the Name: Grid, Library: UiKit v2 is called Type: Layout then don't change it. Because it will then behave like a new Snippet and not like an existing one. 00:04:17 You see because the community uses the Name the Library and the Type to build the Filename. The Filenames we'll look at that also as we go along. All you need to know is there are a bunch of Snippets already in your component. 00:04:38 These snippets were shipped with Joomla Component Builder. This is how it was by default.

Area Called: Get Snippets

We now have an area called Get Snippets. If you are one of those who like to get your name out there and want to 00:04:58 become involved in the JCB community and have others know about you and so forth. This is the ideal time to do that if you share a Snippet. Let say if you have created Article Snippet for example, then you would click on Share Snippets or you could take more than one, it doesn't need to be only one. You can clicks Share Snippets. This will then create a package. Let me show you. We see that it created a package. It's placed in this Path folder(/media/host/Dropbox/sandbox/joomla/tmp/snippets.zip. 00:05:33

Helper Tutorials - Few Links And Shortcuts To Get Involved Sharing Snippets

You got a few helper tutorials to get you going. If you want to learn this tutorial I'm making now will be this link: https://www.youtube.com, and if you want to learn more about Git, it's this one: https://www.udemy.com/git-quick-start/, and if you want to know how the forking is going to work, then it's this: https://www.youtube.com. If you want to know how to do pull request it, it will be this one: https://www.youtube.com 00:05:55 If there's any issues you can open an issue on GitHub: https://github.com/vdm-io/Joomla-Component-Builder-Snippets/issues. This gives you a few links and shortcuts to get involved in sharing Snippets.

What Happens When You Share Snippets?

What happens when you share the Snippet? If someone clicks on Get Snippets, then they will see your name. If that specific Snippet 00:06:18 comes up. Let me illustrate that. If we click on Get Snippets it might take a moment depending on how many Snippets are in the repository at this stage. Because it via Ajax it's getting all the Snippets from GitHub and it's building a little page for you. 00:06:38 It's just loaded the whole bunch of Snippets. The first view shows you all the current Snippets in the JCB community Snippets Repository. You can go to this repository by simply clicking on this GitHub link. It will take you there.

Snippets - In Sync

You can see which of these Snippets are already In Sync. It's called EQUAL. You click on this EQUAL. It show you what EQUAL means. 00:07:05 In Sync with your Local snippets. It has little right mark saying it's a Local snippet and it is In Sync. If you do want to know more about when is a Snippet considered EQUAL then click on this little EQUAL button and it will show you that like I've said.

Snippets - Out Of Date

Then if there is a Snippet Out of Date. Let's say someone contributed to the community on a specific snippet. Let's say it this Snippet Uitkit v2-(Common) Alert. Someone saw if we open the Snippet they see this little snippet(see video) and they thought, we could do better and they improved on it, 00:07:41 and then shared it with the community. Then that Snippet will end up in the Out of Date tab. If there is no Out of Date Snippets, then all be blank. But if there is Snippets that are Out of Date, they all will show up.

Snippets - New

Then there is the New tab. Now the New tab could be a little bit misleading 00:08:01 because in this example that I'm giving you, I went and I deleted a Snippet from my Database. Since that Snippet already exists in the community, the system then detects that snippet isn't here so it must be new. That's how it worked out. Now you could click on this Get Snippet and it will say: 00:08:28 Are you sure you would like to add this new JCB community snippet to your local snippets? You say: OK. Then it goes to GitHub, gets the snippet and moves it to your Database. You done. This Snippet is no longer New. If you click New you'll see no New Snippets. It is also been added locally.

Snippets - Diverged

Then Diverged Snippets is where there is a discrepancy in both the creation date as well as the modified date. 00:08:58 And then those snippets will show up in Diverged and they can be updated in the same way. If you have made a change to a Snippet in your local environment and then you've realized that changes hasn't been good, it's better to return back to the old Community version.

Snippets - Ahead

Then you would come to Ahead. I've made a little change to this specific Snippet. 00:09:23 They'll tell you that the Snippet is Ahead and if you click on it, they'll show you what that would mean. You can then click on Get snippet, to revert back to the old one, and that's what it will tell you. Are you sure you would like to update your local snippet to this older JCB community snippet? You can say: Cancel. I like my new snippet I don't want to update it and just ignore it. But if you want to go back then there is this option 00:09:51 to do so. If this is a good Snippet you might want to consider sharing it with the rest of us. That would be to do the sharing snippet and go through those tutorials in knowing how that works.

Bulk Tool

There is sometimes a situation where a specific person of the community might be very enthusiastic 00:10:13 and he contributes 300 new snippets to the community Snippets Repository. Now that would mean that you want to click on every one of those snippets Get snippet, Get snippet, that might be very tedious. So we added this little Bulk tool. The Bulk tool is able to detect whether there are New snippets and whether they are Ahead snippets or whether you just wanted to update all of them with this 'Just Get All Snippets'. 00:10:42 If there isn't any Diverged or any Out of Date Snippets, it will also not be able to do that. Instead of clicking it one at a time you could just click on 'Revert All Ahead Snippets' and it'll just update all of them for you and you're done.

Description, Usage, Snippet, Who Contribute, View Blame

But if you like me and you want to know exactly what's going on you could read the Description. There's no Description. See the Usage. See how the Snippet itself looks like. If you really like what you see 00:11:12 you might even want to look at who contributed the Snippet. That brings up an important and yet interesting concept. We have decided that when you contribute a new snippet your name and details will end up here(who contributed the snippet). Like I explained earlier when we looked at the contributor area. Yet when someone makes minor contributions to the snippet, we will not necessarily change or replace this Contributor's name. Instead we will let them show up in the blame view. There is a view 00:11:46 which is called the Blame View. The Blame View shows you who changed what part of the code and when. Whenever there is an improvement on any of the Snippets the GitHub Repository tools will help us show you who made those changes. So that's how they will be recognized for their contributions, is via the Blame. Where is if you contribute new Snippets to the JCB community you will end up having your details show up here and have people be able to click on this link 'Vast Development Method' 00:12:17 and go to the website you put up as your website. It's an ideal way of getting yourself out there in the JCB community and at the same time sharing good snippets with the rest of us and make make our life easier. That is looking at the Get Snippets Community area.

We're excited about this. We hope that this will really faster a lot of participation and that it will improve JCB constantly. 00:12:52 Snippets are used in these fork key areas Custom Admin Views, Site Views, Templates, Layouts. These areas are what the customer sees, the one that uses the component. We want to be always sure to have the latest and most stable Snippets ready and available for everyone using JCB. 00:13:16 Once you have imported the new snippet you will be able to see it at the end of your Snippets. Navbar is now the latest one we've imported. If you open the snippet, you will see that contributed details are already in place and so these contributed details will be updated as you add new Snippets.

When Details Not In Place - Say Dynamic Field

If for some reason these details are not 00:13:41 in place it will say dynamic field. Let me show you there. Just create a new one. It says dynamic field. When you have created your snippet, I'm just going to do a simple test to illustrate this. 00:14:03 If you click save, it will first search the JCB Snippet Repository to see if there is a snippet with this kind of a relationship between the Name, the Type and the Library. If it doesn't exist it will go to your Global area like explained 00:14:31 and they will get your details and dynamically added in to the snippet. It found my details and put it in there. That is how this details get set when you create a snippet, a new one, it will fall back to your details 00:14:51 if that Snippets Name, Type and Library relationship doesn't already exist in the JCB community. Now if for some reason it does exist it will take the initial contributors details and add that in there. That's how it works at this stage.

Maybe there is better ways but for now this is how we will start. I'm sure it will evolve and change as we go along until we are able to 00:15:22 satisfy all and everyone's needs. I think that's enough of an overview of how everything works. You've seen how to use the Snippets in your components. You've seen how to start initial steps of sharing a snippet. You simply select them like I showed you. Only when you have improved on it or whether you've created new ones will you ever want to do that. 00:15:48 Then you click on Share Snippet and it gives you a package. It has a few tutorials like tutorials on forking JCB Snippets. And tutorial making a pull request. These two tutorials would be quite key 00:16:11 for you to understand what would be this next steps and getting your Snippets into the JCB community.