Differences

This shows you the differences between two versions of the page.

--- videos:code_generators_1 [2020/10/13 13:38] – [Transcript] demiankatz
+++ videos:code_generators_1 [2023/04/26 13:31] (current) – crhallberg
@@ Line 1: / Line 1: @@
 ====== Video 11: Code Generators, Part 1: Setting Up/Creating a Recommendation Module ======
-The eleventh VuFind instructional video explains how to set up a local code module and use VuFind's code generation tools to build a custom Recommendation module.
+The eleventh VuFind® instructional video explains how to set up a local code module and use VuFind's code generation tools to build a custom Recommendation module.
 Video is available as an [[https://vufind.org/video/Generators1.mp4|mp4 download]] or through [[https://www.youtube.com/watch?v=84e0xxSuiGQ&feature=youtu.be|YouTube]].
@@ Line 13: / Line 13: @@
 ===== Transcript =====
-// This is a raw machine-generated transcript; it will be cleaned up as time permits. //
+Welcome to the 11th VuFind tutorial video. This month we are going to start looking at code generators and talk about how to manage local custom code and how to build a simple recommendation module using a code generator. So in past videos we've talked about two ways in which you can customize your VuFind instance, one by maintaining a local configuration directory for your config files and another by creating a local team. So the third way is to create a local code module where you can extend override or add to VuFind's code.
- welcome to the 11th viewfinder tutorial
+So before we start creating a code module, let me just talk a little bit about code modules in general. So if I go to the VuFind home directory and I look at the files that are here. There's a directory called module. And if I look in there, I see that there are a number of sub directories, VuFind, VuFind API, VuFind admin, etc. Each of these directories is a Laminas code module. Laminas has a module manager, which allows you to organize your code into modules, each of which is bundled with a bit of configuration. And a Laminas application can be built by composing together a number of these modules to get all of the functionality into one place. And the neat thing about the code plus configuration design here is that you can add a module of your own and load it last. Then the configuration of your module will override equivalent configuration in any of the earlier module. Thus, you can build your own module for VuFind, put your code and configuration in there, and this gives you the power to add to or replace any of the core functionality.
-video
-uh this month we are going to look start
+The modules that come with VuFind bundle different parts of its functionality. The majority of the application is in the main VuFind module. Some more specialized pieces have been broken out into separate chunks. And it's entirely possible that over time, the code will become more modular as we split it up into more logical pieces. But that's an ongoing process. In any case, to get started, let's create a local module where we can begin to work. And when I create it also show you what it looks like so you can have a better understanding of how these modules are structured. If you want a module VuFind's install script, it gives you an option to create one. So depending on how you set up your VuFind instance, you might actually already have one. But if you don't, don't worry, you can just run the installer again. Keep all of your options the same except add a module, and that'll do the job for you. So that's exactly what I'm going to do right now. The tutorial VuFind instance we've been working with was installed from a Debian package, which does not create a local code module by default.
-looking at code generators
-uh and talk about how to manage local
+So I'm just going to, from my VuFind home directory, run ''php install.php'' to rerun the installer, and this will give me the option to create a module. So I have to be sure that all of the other choices I make here are the same as the choices that were made the last time the installer was run. So it asks me where I want my local settings, vufind/local. That's fine. I want to keep the default.
-custom code and how to build
-a simple recommendation module using a
+Now it asks me what module name I want to use and this is where I need to make a decision. There can be any legal PHP namespace, which means practically anything. You just want to be careful that you don't choose a name that either conflicts with an internal PHP command, or conflicts with an existing VuFind module, or a dependency. Usually if you name it for say your local institution, you'll be very safe for the purposes of the tutorial though I'm just going to call my local module tutorial. So now it asks me what path to use and VuFind URL. I want to keep that the same: /vufind; and I'm done.
-code generator
-so in past videos we've talked about two
+So all that the installer has done is it's created the empty local module for me, and it has updated my Apache configuration to include a setting to load that module. So I got VuFind under Git control last week, or rather last month. I can do ''git status'' to see what the installer actually did. And as I can see it has created a module tutorial directory. And it's modified two files: my env.bat file, which I don't care about because that only is used under Windows, and my local/http-vufind.conf, my VuFind Apache configuration. So let me do a quick get to inspect exactly what has changed. So first of all, what happened in the environment that which again doesn't matter because we're not in Windows, but if we were in Windows, we would care that it has added an environment variable. Pointing to tutorial. The more important changes are in the Apache configuration. You can see that it has uncommented the setting to set up the VuFind local modules environment variable and set it to tutorial. So this is what tells you find which module code to load. So if I had made any mistakes when running the install.php script, I would see other unwanted changes in here, like changes to VuFind directory path. So if that had happened, I could have done a get reset to back out the changes and I could try again. But in this case I've gotten it right the first time. So I am just going to commit these changes so that I have all of this going forward. So I'm going to do a get status again to see what I'm working with.
-ways in which you can customize your
-viewfind instance
+I'm going to get add the changes to my env.bat. I'm also going to delete this HTTP VuFind dot com dot back dot timestamp file. That's a backup that the install script made of my Apache configuration, which is a really nice safety mechanism to have if you're not using it. But since we're using get to manage our changes in our our versioning, we really don't need to keep backup files around. We can revert using it if we really have to. So I'm going to commit my tutorial module.
-one by maintaining a local configuration
-directory for your config files and
+There are a couple more things that I also am going to need to do to fully prepare this module. First of all, because I've changed my Apache configuration, I need to restart Apache to load the new configuration. So I can do that with ''sudo systemctl restart apache'' to I'm just going to go over to my web browser and refresh my VuFind to confirm that it still works. I haven't broken everything by adding my new module. That's good.
-another by creating a local theme
-so the third way is to create a local
+The other thing I want to do is be sure that I have my module defined as an environment variable at the command line. Because if I use VuFind from the end line utilities, I want those to have access to my custom code as well. So I do this by editing the ''/etc/profile.d/vufind.sh'' script. And I just add to that ''export VUFIND_LOCAL_MODULES=Tutorial''. Then I'll reload my profile ''source /etc/profile/d''. And now if I echo $VUFIND_LOCAL_MODULES. I get "Tutorial" so my environment variables are all set up. And I'm ready to begin working with this module.
-code module
-where you can extend override
+But before I add anything to it. Let's take a quick look at what's actually in there. And I'll actually open up the code to do that, because I can be easier to look at in a code editor. Alright, so here I am in VS code. And if I look under my module directory I see all of you find core modules as well as the tutorial module I've created. And if I expand that out I see we have a few things here. We have a Module.php file every laminas module contains a Module.php, which is used for loading the module. And if you look at this file. There's not a whole lot in here. It loads the configuration file for us. It's an auto loader, so that the rest of the framework knows where to find the code that lives in the module. And it has a couple of empty hook methods, where you could theoretically add actions that occur when the module initializes or bootstraps but you rarely need to do that. So this is a file you shouldn't have to touch much it's just part of the setup of the module.
-or add to viewfinds code
-so before we start creating a code
+Then under config there's a module.config.php file containing the modules configuration. Right now this is simply an empty array, because we haven't put anything in here yet. But we could in theory copy configuration from other modules and change it, and it would be overridden, because our tutorial module is going to load last, which makes it take precedence over the things that are loaded before it. And finally, we have a source/Tutorial directory, and this is where all of our code will live, but we haven't added any code the module yet so right now it's simply an empty directory.
-module let me just talk
-a little bit about code modules in
+Thus, we need to add some code. And VuFind contains several different code generator tools that can be used to add code to a local module. So you're going to look specifically at the plugin generator, which is what you use when you want to create a new plugin of an existing type. So to run the plugin generator. You simply run ''php $VUFIND_HOME/public/index.php generate plugin'', and then some parameters. But with any of VuFind command line tools if you don't know what the parameters are you can add ''--help'', and you'll get a usage screen. That we can provide the plugin generator with the name of the class we wanted to generate and optionally the name of a factory that we want to use to instantiate our class when VuFind builds it. If you don't specify a factory, the generator will actually create a new factory for you that will generate an instance of your class. There's also an optional top level switch that you can use if you want to create a plugin in VuFind top level service manager. Otherwise, the generator is going to look at the class name you provided it and try to figure out what kind of plugin you're generating based on the namespace and then put it in the appropriate context. And as I mentioned at the beginning, what we're going to generate today is a recommendation module. We talked about recommendation modules quite a few videos ago, when we were talking about search configuration. So recommendation modules can be turned on in the any files and they provide additional information, usually above or to the side of search results. So what I'm going to do is create a recommendation module that will display a message at the top of the combined search screen. So this shows you how if you wanted to put a welcome message or some kind of additional local information, you can easily add it to that top level screen.
-general
-so if i go to the viewfind home
+So I'm going to call this recommendation module tutorial recommend combined notes. So, we'll go back to this generate command and we will say ''php $VUFIND_HOME/public/index.php generate plugin Tutorial\\Recommend\\CombinedNotes''. I'm not going to specify a factory so this will allow it to generate one for us. And a couple of notes about what I've done. So I want to create a class called tutorial recommend combined notes. Each part of this is important. The "Tutorial", the beginning of the name, the first part of the namespace tells VuFind and the generator what module this belongs to. Everything in the tutorial namespace needs to live inside the tutorial module and all code in the tutorial module needs to belong to the tutorial namespace.
-directory
-and i look at the files that are here uh
+The next part is "Recommend" and all of our recommendation modules have the second part of their namespace set to recommend. So most of VuFind's core recommendation modules have classes that are named VuFind\Recommend\(something). So we're following that same pattern. We're just using our Tutorial module. And of course, "CombinedNotes" is the name of the actual class we want to create within this namespace.
-there's a directory called module
-and if i look in there i see that there
+The reason I have to double up my backslashes is because backslashes are how fully qualified PHP class names represent the parts of or connect together the parts of a namespace. Backslashes have a special meaning on the Linux command line. So I have to double them up so that they get passed through correctly to the PHP code. If I only put single backslashes here, weird stuff would happen. So that's a common gotcha. Be sure when you're providing class names to generators that you double up all the backslashes.
-are
-a number of subdirectories you find you
+Anyway, now I can run my command. So I have to do some messages. It created my combined notes class. It created a combined notes factory. It backed up my module configuration and then it updated the module configuration. So if I do a get status now. Some files have been added to my module tutorial source directory and my module configuration has been modified. I'm going to switch back over to vs code to just show you what we've got. So as you can see my module configuration has gotten some stuff added to it. There's now a plugin manager's array inside of VuFind array and it contains a recommend section which is where recommendation modules are defined. There's a factories element, which specifies that this new tutorial recommend combined notes class that I created should be built by the combined notes factory. There's an alias set up so that when I configure in my configuration files a recommendation module named combined notes, it knows that that maps to the combined notes class that we've just created.
-find api
-you find admin etc
+And going into depth on how this whole service manager configuration works would be a good topic for a future video. But for now, just take for granted that the generator configured this all correctly for you so that you don't have to worry about it. You can just fill in this class and this factory and use this alias name in your configuration files.
-uh each of these directories is a
-lominos code module
+So let's look at the source that was generated. These are combined notes.php. As you can see it has the right tutorial recommend name space on it. It's named combined notes. It implements the appropriate interface for a recommendation module, which the generator figured out based on the name space, we told it to use when we specified our class name. But there's nothing in here we're going to have to write this class. But first let's take a look at the factory that was created. And all this does is return an instance of the requested service, which based on the way the service manager works is always going to be the name of the class that we want to build, which would be tutorial recommend combined notes. So based on what we're doing today there is actually no reason to build a special factory to generate this I just wanted to demonstrate that it's possible, so that if you're building something with dependencies, you have this class available to do some dependency injection within. But for today's demo we're just going to leave this at the default and not worry about it any further. Because our combined notes class implements an interface, we're not going to be able to use it until we've defined all of the methods that the interface requires. So let's talk a little bit about the recommendation module interface and how it works. So I can take advantage of the fact that I can right click on, well, normally. All right, that's not working. So I need to look up this VuFind recommend recommend interface to see exactly what methods I have to define in my local class. I mentioned our name space tells us what module our code lives in so I know that this is defined in the VuFind module under the source directory. So here's the VuFind name space. Recommend. And recommend interface. So a PHP interface just defines which methods a class needs to define. So I'm going to paste all of these method definitions from the interface. Into my new combined notes class. And for starters, I'm going to just make them all empty methods that don't do anything. There are three methods that recommendation modules have to define. The first is set config, which receives extra configuration settings that the user defines in the any file and makes use of them. So we can leave this empty if we don't have any configuration. Then there's an init method, which gets called before VuFind runs a search, but after the user's search request has been processed. We want a recommendation module to analyze user input or actually make changes to the request that we're going to make. We can do that here. This is not done very often, but for example, the side facets recommend module uses the init method to turn on the asset values that the user has configured.
-laminas has a module manager which
-allows you to organize your code into
+For today's example, we're not going to be touching in it. And finally, there's a process method, which gets called after the search has been performed, and which can be used to extract information from the search results if we want to use that to impact the message that we ultimately display to the user. But it's perfectly valid to leave all of this empty. And then you just have a recommendation module that doesn't do anything except display a template. So, let's, let's turn this on and just see what happens and spoiler alert, it's not going to work yet, because we haven't made a template, but I just want to demonstrate what this all looks like.
-modules each of which is bundled
-with a bit of configuration uh
+So I'm going to go into my local config directory. Into combined i and i, because I want to display this recommendation module at the top of my combined search results. And at the bottom of combined i and i there's a recommendation module section that lets me turn these things on. So I'm going to put it on in the top, the name, as you recall from the alias that was generated in my configuration is called combined notes. So just by adding this top equals combined notes to the recommendation modules list in combined i and i, I should now have turned on my new recommendation module, and it should appear at the top of my combined search results. Except we get an error, because I haven't created a template yet. But as you can see what i'm looking at here is the generic please contact us for help message, which doesn't really tell us anything about what went wrong. And that's because by default of VuFind runs in production mode, which does not display detailed error messages because we don't want to accidentally display something that exposes a security vulnerability to the general public. However, when we're actually working on developing VuFind on a development server. It's often helpful to turn on development mode, which will display richer error messages when things like this go wrong.
-and a laminas application can be built
-by composing together
+Let me quickly show you how to turn on development mode. I'm going to edit the Apache configuration in local slash httvufine.com and scroll down a little bit. There's a commented outline that says set end view find end development if I uncomment that. And then restart Apache. Now if VuFind is in development mode and if I refresh this page, I get a much more useful message, which is actually telling me that I didn't set up my recommendation module correctly, I have a suspicion that I didn't get saved after I made my changes over. Sure enough, that's what happened. So it was originally complaining because I hadn't saved my method definitions, and so I wasn't conforming to the interface. I've now gone back save that and fixed it so if I refresh again I should get the next error message, which is now that it's looking for a combined notes template so that it can display the recommendations, but I haven't created that yet.
-a number of these modules uh to
-get all of the functionality into one
+Can't find it, therefore it can't display recommendations and it throws an error. And so, this points out that by convention, every recommendation module needs to have a PhDML file in the recommend template directory of your team, whose name corresponds with the name of the class. Any VuFind plugin that displays something follows this convention of having a template directory containing PhDML files whose names correspond with class names. And if you look in the plugins page of the VuFind wiki, you'll find all of the plugin types you can build as well as notes on these types of conventions on a plugin by plugin basis.
-place
-and the neat thing about the code plus
+Now the important thing is, in order to proceed, we need to create this template file. And because I don't want to change core VuFind code, we should turn on our custom theme again so that we can make our custom files in our custom theme. I'm just going to bring up my config.ini file in my local configuration directory. And I'm going to comment out the boot print three theme and uncomment the tutorial theme that we set up a few months ago. Inside my theme directory, inside my tutorial theme, inside its templates directory, I'm going to create a new folder called recommend. And inside that folder, I'm going to create a new template file called combined notes.phtml. And inside that file, I'm just going to put the HTML. You are looking at combine search results. And I will actually save that this time. So now if I go back to my browser and I refresh the page again, everything is working. My custom theme is turned on, which is why things look different. And my recommendation module has loaded and rendered right above my search results.
-configuration design here
-is that you can add a module of your own
+This would be a really good time to go back to the command line and commit all of this stuff that I have just done. So I'm going to get add module tutorial source. And I'm going to get add this tutorial templates. And I'm going to commit that as create combined notes recommendation module. I can also get add my HTTP VuFind comp where I turned on development mode. Let's say turned on development mode. And for now I'm not going to commit my configuration changes. We'll see if we want to keep things this way after we've done a little bit more work.
-and load it last
-and then the configuration of your
+So at this point I've already demonstrated how to set up a local module, how to use a plugin generator to create a plugin within that module, how to turn that on and how to fill it in enough that it will work. But let's do a little bit more advanced work and talk a little bit more about recommendation modules while we have this opportunity, because it's great that we can display this template in this place.
-module will override
-equivalent configuration in any of the
+But it would be more fun to see how all the different pieces work together. So let's start by adding a configuration setting so that if we want to change the name of our combined search results, we can set that in the i and i file. As I mentioned earlier, the set config method of a recommendation module allows you to receive configuration settings that come from the i and i. So if I open up my combined notes. Let's create a protected property here called name. And then in set config. Let's just pass the settings we receive into that name property. And let's create a new public method called get name, which simply returns that name property that I just set up. So now, I'm going to go to combined i and i. I can add parameters to a recommendation module by just putting in a colon and then adding stuff after the colon. So, let's say the tutorial results, put this whole thing in double quotes since it has spaces in it. We want to be sure the configuration parses correctly. The tutorial results will get passed to the set config method. Then it will get stored in the this name property and it will be available for retrieval through this public get name method. And of course, the place where we want to retrieve it is in our template, which by convention is going to have access to our. CombinedNotes class using the name this arrow recommend. So what I can do is say this escape HTML, because we want to be sure that we don't miss render special characters in our text. This recommend get name. And I will delete. Combined search results. And actually, just for completeness, I'm going to go back and make my second big a little bit smarter, say. If the settings are empty, we'll call it combined search results. Otherwise, we'll use the settings. So this way, it has a reasonable default, but it can be overwritten. So again, the flow. I put a parameter on the recommendation module configuration in my any file. It passes to set config which stores it. My class exposes the stored property through a get name property, and I can call that get name property in my template. By referring to the this recommend object, which is always going to be available in any recommendation module template pointing at the instance of the recommendation module class.
-earlier modules
-thus you can build your own module for
+So now I come back here and I refresh the page. Combined search results has changed to the tutorial results, and I've showed you both how to configure a recommendation module and how to use properties of the recommendation module to render a response.
-viewfind
-put your code and configuration in there
+Let's just do one more clever thing and show the user's search query along with the message. We can do that by going to be going to the process method, which receives an instance of VuFind search results object after the search has been completed. Well, first, let's create another property. We'll call this query. The process, we can say this query equals results get params. Get display query, which is how you get access to the user's input in a human readable form from a search results object. We also need to create a get query method to expose this property so that the view template can read it. So we just create a query that returns this query, save all of that. In our template here, we can add for query colon, and then embed. This escape HTML, this recommend get query close friends, and save that. We can actually do a search that has a query, make this more interesting. And sure enough, now it says you're looking at the tutorial results for query web. So again, my search query got processed, the recommendation module pulled that out of the results object, and we displayed it right here.
-and this gives you the power to add to
-or replace any of the core functionality
+Of course, there's a lot more to learn. There's a lot of depth to what VuFind is doing. But the point here is that you can build small plugins like this, which have access to other pieces of VuFind, and you can pull things out and push them to the display. So that you can do some fairly sophisticated customizations from within your local module with relatively little effort. And next time around, I will go into some more code generators and show you how to do some other advanced customizations. Until then, as always, feel free to reach out with questions through the mailing lists or Slack, and have a good month.
-the modules that come with viewfind
-bundle different parts of its
-functionality the majority of the
+//This is an edited version of an automated transcript. Apologies for any errors.//
-application is in the main
-viewfinder module some more specialized
-pieces have been broken out into
-separate chunks
-and it's entirely possible that over
-time the code will become more modular
-as we split it up into more logical
-pieces
-but that's an ongoing process in any
-case
-um to get started let's create a local
-module
-where we can begin to work and when i
-create it i'll also show you what it
-looks like so you can have a better
-understanding of how these modules
-are structured fortunately
-if you want a module viewfinder's
-install script
-gives you an option to create one so
-depending on how you set up your
-viewfind
-instance you might actually already have
-one but if you don't
-don't worry you can just run the
-installer again
-keep all of your options the same except
-add a module
-and that'll do the job for you so that's
-exactly what i'm going to do
-right now the tutorial
-viewfinder instance we've been working
-with was installed from a debian package
-which does not create a local code
-module by default
-so i'm just going to from my viewfind
-home directory
-run php phpinstall.php
-to re-run the installer and this will
-give me the option
-to create a module i just have to be
-sure that
-all of the other choices i make here are
-the same as the choices that were made
-the last time
-the installer was run so it asks me
-where i want my local settings
-of viewfind local that's fine i want to
-keep the default
-now it asks me what module name i want
-to use and this is where i need to make
-a decision
-your module name can be any legal php
-namespace
-which means practically anything you
-just want to be careful that you don't
-choose
-a name that either conflicts with an
-internal php command
-or conflicts with an existing viewfind
-module
-or any of ufind's dependencies
-usually if you name it for say your
-local institution
-you'll be very safe for the purposes of
-the tutorial
-though i'm just going to call my local
-module tutorial
-so now it asks me what path to use in
-viewfind's url
-i want to keep that the same slash
-viewfind
-and i'm done so all that the installer
-has done
-is it's created the empty local module
-for me
-and it has updated my apache
-configuration
-to include a setting to load that module
-so since we got viewfind under git
-control last week
-or rather last month i can do git status
-to see what the installer actually did
-and as i can see it has created
-a module tutorial
-directory and it's modified two files
-my environment.that file which i don't
-care about because that only is used
-under windows
-and my local httpd
-viewfinder.com my apache configuration
-so let me do a quick get diff to inspect
-exactly what has changed
-so first of all what happened in the
-environment that
-which again doesn't matter because we're
-not in windows but if we were in windows
-we would care that it has added an
-environment variable
-uh pointing to tutorial the more
-important changes
-are in the apache configuration
-where you can see that it has
-uncommented
-the setting to set up the viewfind local
-modules environment variable and set
-it to tutorial so this is what
-tells viewfind which module
-code to load there's also this small
-change up here
-where a comment has changed and that's
-simply a side effect of having
-upgraded viewfind to a newer version
-that no longer mentions
-zen framework a harmless side effect of
-re-running the installer
-so if i had made any mistakes when
-running the install.php
-script i would see other unwanted
-changes in here
-like changes to viewfind's directory
-path
-uh so if that had happened i could have
-done a get reset
-to back out the changes and i could try
-again
-but in this case i've gotten it right
-the first time
-so i am just going to commit these
-changes
-so that i have all of this going forward
-so i'm going to do a gift status again
-to see what i'm working with
-i'm going to git add the changes to my
-env.bat my local http
-viewfinder.com and i'm going to add my
-new
-tutorial module i'm also going to
-delete this httpd
-viewfinder.com.back.timestamp
-file that's a backup that the install
-script made
-of my apache configuration which is a
-really nice safety mechanism to have
-if you're not using git but since we're
-using git to manage our changes in our
-our versioning we really don't need to
-keep backup files around we can revert
-using git if we really have to so i'm
-going to commit
-add tutorial module
-there are a couple more things that i
-also am going to need to do
-to fully prepare this module
-first of all because i've changed my
-apache configuration
-i need to restart apache to load the new
-configuration
-so i can do that with sudo system ctl
-restart apache 2
-and i'm just going to go over to my web
-browser and refresh my viewfinder to
-confirm that
-it still works i haven't broken
-everything by adding my
-new module that's good the other thing i
-want to do
-is be sure that i have my module defined
-as an environment variable at the
-command line
-because if i use viewfind command line
-utilities i want those to have access to
-my custom code
-as well so i do this by editing
-the etc.profile.d
-viewfind.sh script and i just add to
-that
-export find local modules equals
-tutorial
-uh then i'll reload
-my profile with source slash etc profile
-and now if i
-echo dollar viewfind underscore local
-underscore modules i get tutorials so my
-environment variables are all set up
-and i'm ready to begin working with this
-module
-but before i add anything to it let's
-take a quick look
-at what's actually in there
-and i'll actually open up vs code
-to do that because i think it will be
-easier to look at in a code editor
-all right so here i am in vs code
-and if i look under my module directory
-i see all of
-viewfind's core modules as well as the
-tutorial module
-i've created if i expand that out i see
-we have a few things here we have a
-module.php file
-every laminas module contains a
-module.php
-which is used for loading the module and
-if we look at this file
-there's not a whole lot in here uh it
-loads the configuration file for us
-it sets up an autoloader so that
-the rest of the framework knows where to
-find the code that lives in the module
-and it has a couple of empty hook
-methods where you could theoretically
-add
-actions that occur when the module
-initializes or bootstraps but you rarely
-need to do that
-so this is a file you shouldn't have to
-touch much it's just
-part of the setup of the module then
-under config there's a module.config.php
-file containing the modules
-configuration
-right now this is simply an empty array
-uh because we haven't put anything in
-here yet
-but we could in theory uh copy
-configuration from other modules and
-change it
-and it would be overridden because our
-tutorial module is going to load last
-which makes it take precedence over the
-things that are loaded before it
-and finally we have a source
-slash tutorial directory and this is
-where all of our code will live
-but we haven't added any code to the
-module yet so right now
-it's simply an empty directory
-thus uh we need to add some code
-and viewfind contains several different
-code generator tools
-that can be used to add code to a local
-module
-today we're going to look specifically
-at the plug-in generator
-which is what you use when you want to
-create a new plugin
-of an existing type so
-to run the plug-in generator uh you
-simply run
-php viewfind home
-slash public slash index.php
-space generate space plug-in and then
-some parameters
-but with any of you finds command line
-tools if you don't
-know what the parameters are you can add
-minus minus help
-and you'll get a usage screen
-so this shows us that we can provide
-the plug-in generator with the name of
-the class we want it to generate and
-optionally the name of the factory that
-we want to use to instantiate our class
-when viewfind builds it if you don't
-specify
-a factory the generator will actually
-create a new factory for you
-that will generate an instance of your
-class
-there's also an optional top level
-switch
-that you can use if you want to create a
-plugin
-in viewfind's top level service manager
-otherwise the generator is going to look
-at the class name you provided it and
-try to figure out
-what kind of plugin you're generating
-based on the name space and then put it
-in the appropriate context
-so as i mentioned at the beginning what
-we're going to generate today
-is a recommendation module we talked
-about recommendation modules
-quite a few videos ago when we were
-talking about search configuration
-so recommendation modules can be turned
-on in the ini files
-and they provide additional information
-usually above or to the side of search
-results
-today what i'm going to do is create a
-recommendation module that will display
-a message at the top of the combined
-search screen
-so this shows you how if you wanted to
-put a welcome message
-or some kind of additional local
-information
-you could easily add it to that top
-level screen
-so i'm going to call this recommendation
-module
-tutorial recommend combined notes
-so we'll go back to this
-generate command and we will say php
-if you find home public index.php
-generate plugin
-tutorial backslash backslash recommend
-backslash backslash
-combined notes i'm not going to specify
-a factory so this will allow it to
-generate one for us
-and a couple of notes about what i've
-done here so
-i want to create a class called tutorial
-recommend
-combined notes each part of this is
-important
-the tutorial the beginning of the name
-the first part of the namespace
-tells the viewfinder and the generator
-what module this belongs to
-everything in the tutorial namespace
-needs to live inside the tutorial module
-and all code in the tutorial module
-needs to belong to the tutorial
-namespace
-the next part is recommend and
-all of our recommendation modules have
-the second part of their namespace set
-to recommend
-so most of you finds core recommendation
-modules have classes that are named
-viewfind
-backslash recommend backslash something
-so we're following that same pattern
-we're just using our tutorial module
-and of course combine notes is the name
-of the actual class we want to create
-within this namespace
-the reason i have to double up my
-backslashes
-is because backslashes are how fully
-qualified php class names
-uh represent the parts of or connect
-together the parts of a namespace
-but backslashes have a special meaning
-on the linux command line
-so i have to double them up so that they
-get passed through correctly to the php
-code
-if i only put single backslashes here
-weird stuff would happen
-so that's a common gotcha be sure when
-you're providing class names
-to generators that you double up all the
-backslashes
-anyway now i can run my command and i
-see some messages
-it created my combined notes class it
-created a combined nodes factory
-it backed up my module configuration and
-then it updated
-the module configuration
-so if i do a git status now
-i see that some files have been added
-to my module tutorial source directory
-and my module configuration has been
-modified
-i'm going to switch back over to vs code
-to just
-show you uh what we've got so as you can
-see my module configuration
-has gotten some stuff added to it
-there's now a plugin managers array
-inside of you find array and it contains
-a recommend section which is where
-recommendation modules
-are defined there's a
-factories element which specifies
-that this new tutorial recommend
-combined
-notes class that i created should be
-built
-by the combined notes factory
-additionally
-there's an alias set up so that when i
-configure in my configuration files
-a recommendation module named combined
-notes it knows that that
-maps to uh the combined notes class that
-we've just created
-and going into depth on how this whole
-service manager configuration works
-would be a good topic for a future video
-but for now uh just take for granted
-that
-the generator configured this all
-correctly for you so that you don't have
-to worry about it
-you can just fill in this class and this
-factory
-and use this alias name in your
-configuration files
-so let's look at the source that was
-generated
-first of all here's our
-combinednotes.php
-as you can see it has the right tutorial
-recommend namespace on it
-it's named combined notes it implements
-the appropriate interface for a
-recommendation module
-which the generator figured out based on
-the namespace
-we told it to use when we specified our
-class name
-but there's nothing in here we're going
-to have to write this class
-we'll get there in a moment but first
-let's take a look at the factory that
-was created
-and all this does
-is return an instance of the
-requested service which based on the way
-the service manager works is always
-going to be
-the name of the class that we want to
-build which would be
-tutorial recommend combined notes
-uh based on what we're doing today there
-is actually no reason to build
-a special factory to generate this i
-just wanted to demonstrate that it's
-possible
-so that if you're building something
-with dependencies you have this class
-available to to do some dependency
-injection
-within but for today's demo we're just
-going to leave this at the default
-and not worry about it any further
-so because our combined notes class
-implements an interface we're not going
-to be able to
-use it until we've defined all of the
-methods that the interface
-requires so let's talk a little bit
-about
-the recommendation module interface
-and how it works so in vs code i can
-take advantage of the fact that i can
-right click on well normally
-all right that's not working so
-i need to look up this viewfind
-recommend recommend interface to see
-exactly
-what methods i have to define in my
-local class
-and as i mentioned our namespace tells
-us what module our code lives in so i
-know that this is defined in the meme
-you find module under the source
-directory
-so here's the view find namespace
-recommend
-and recommend interface
-so a php interface just defines which
-methods
-a class needs to define i'm just going
-to copy and paste
-all of these method definitions from the
-interface into
-my new combined notes class
-and for starters i'm going to just make
-them all
-empty methods that don't do anything
-there are three methods that
-recommendation modules have to define
-the first is set config which receives
-extra configuration settings that the
-user defines
-in the any file and makes use of them so
-we can leave this empty if we don't have
-any
-configuration then there's an init
-method
-which gets called before viewfind runs a
-search but after
-the user's search request has been
-processed
-so if we want a recommendation module to
-analyze
-user input or actually make changes to
-the
-request that we're going to make we can
-do that here
-this is not done very often but for
-example
-the side facets recommend module uses
-the init method
-to turn on the facet values that the
-user has configured
-for today's example we're not going to
-be touching init it
-and finally there's a process method
-which gets called after the search has
-been performed
-and which can be used to extract
-information from the search results if
-we want to use that
-to impact the message that we ultimately
-display to the user
-but it's perfectly valid to leave all of
-this
-empty uh and then you just have a
-recommendation module that doesn't do
-anything
-except display a template
-so let's uh let's turn this on and just
-see what happens
-and spoiler alert it's not going to work
-yet
-because we haven't made a template but i
-just want to demonstrate
-what this all looks like so i'm going to
-go
-into my local config
-directory
-into combined.ini
-because i want to display this
-recommendation module at the top of my
-combined search results
-and at the bottom of combine.ini there's
-a recommendation module section
-that lets me turn these things on so i'm
-going to put it on in the top
-the name uh as you recall from the alias
-that was generated in my configuration
-is called combined notes
-so just by adding this top equals
-combined notes to the recommendation
-modules list in combined.ini
-i should now have turned on
-my new recommendation module and it
-should appear at the top of my combined
-search results when i do a search
-except we get an error because i haven't
-created a template yet
-but as you can see what i'm looking at
-here is the generic
-please contact us for help message which
-doesn't really tell us anything about
-what went wrong
-and that's because by default a
-viewfinder runs in production mode
-which does not display detailed error
-messages because we don't want to
-accidentally display something
-that exposes a security vulnerability to
-the general public
-however when we're actually working on
-developing viewfind on a development
-server
-it's often helpful to turn on
-development mode which will display
-richer error messages when things like
-this go wrong
-let me quickly show you how to turn on
-development mode
-if i edit the apache configuration in
-local
-http viewfinder.com
-and scroll down a little bit
-there's a commented outline that says
-set end
-viewfinden development if i uncomment
-that
-and then restart
-apache
-now viewfinder is in development mode
-and if i refresh this page
-i get a much more useful message
-which is actually telling me that
-i didn't set up my recommendation module
-correctly i have a suspicion
-that i didn't hit save after i made my
-changes over here
-sure enough that's what happened so it
-was originally complaining because i
-hadn't saved
-my method definitions and so i wasn't
-conforming to the interface
-i've now gone back saved that and fixed
-it so if i refresh again i should get
-the next error message
-which is now that it's looking for
-a combined notes template so that it can
-display the recommendations but i
-haven't created that yet
-can't find it therefore it can't display
-recommendations
-and it throws an error
-and so this points out that by
-convention
-every recommendation module needs to
-have a phtml
-file in the recommend template directory
-of your theme
-whose name corresponds with the name of
-the class
-uh any viewfind plugin that displays
-something follows this convention
-of having a template directory
-containing phtml files whose names
-correspond with class names
-and if you look in the plugins page of
-the viewfind wiki
-you'll find all of the plugin types you
-can build
-as well as notes on these types of
-conventions on a plug-in by plug-in
-basis
-but for now the important thing is in
-order to proceed
-we need to create this template file
-and because i don't want to
-change core viewfind code we should
-turn on our custom theme again so that
-we can
-make our custom files in our custom
-theme
-so i'm just going to bring up
-my config.ini file
-in my local configuration directory
-and i'm going to comment out the
-bootprint 3 theme and
-uncomment the tutorial theme that we set
-up
-a few months ago and now
-inside my themes directory
-inside my tutorial theme inside its
-templates directory
-i'm going to create a new folder called
-recommend
-and inside that folder i'm going to
-create a new template file
-called combinednotes.phtml
-and inside that file i'm just going to
-put some html you
-are looking at combined search results
-and i will actually save that this time
-so now if i go back to my browser and i
-refresh the page
-again everything is working my custom
-theme is turned on which is why things
-look different
-and my recommendation module has loaded
-and rendered
-right above my search results
-this would be a really good time to go
-back to the command line
-and commit all of this stuff that i have
-just done
-so i'm going to git add module
-tutorial source i'm going to get
-add themes tutorial templates
-and i'm going to commit that as create
-combined notes recommendation module
-i can also
-get add my httpd viewfind comp
-where i turned on development mode let's
-say turned on development mode
-and for now i'm not going to commit my
-configuration changes
-uh we'll see if we want to keep things
-this way after we've
-done a little bit more work so at this
-point
-i've already demonstrated how to set up
-a local module how to use a plug-in
-generator
-to create a plug-in within that module
-how to turn that on and how to fill it
-in enough that it will work
-um but let's do a little bit more
-advanced work
-and talk a little bit more about
-recommendation modules while we have
-this opportunity
-because it's great that we can display
-this template in this place
-but it would be more fun to see how all
-the different pieces work together
-so let's start by adding a configuration
-setting
-so that if we want to
-change the name of our combined search
-results
-we can set that in the ini file
-as i mentioned earlier
-the set config method
-of a recommendation module
-uh allows you to receive configuration
-settings
-that come from uh the ini
-so if i open up my combined notes
-let's create a protected property here
-called name
-and then in set config let's just pass
-the settings we receive
-into that name property
-and let's create a new public method
-called
-get name which simply returns
-that name property that i just set up
-so now if i go to combined
-ini i can
-add parameters to a recommendation
-module by just putting in a colon and
-then adding stuff
-after the colon so
-let's say the tutorial results
-put this whole thing in double quotes
-since it has spaces in it
-we want to be sure the configuration
-parses correctly
-so at this point
-the tutorial results will get passed to
-the set config method
-then it will get stored in the this name
-property and it will be available for
-retrieval through this public
-get name method and of course the place
-where we want to retrieve it
-is in our template which by convention
-is going to have access to our
-combined notes class using the name this
-arrow recommend so what i can do is say
-this escape html because we
-want to be sure that we don't misrender
-special characters in our text
-this recommend get name
-and i will delete
-combined search results
-and actually just for completeness i'm
-going to go back
-and make my set config a little bit
-smarter
-say if the settings are empty
-we'll call it combine search results
-otherwise we'll use the settings so this
-way
-it has a reasonable default but it can
-be overwritten
-so again the flow i put a parameter
-on the recommendation module
-configuration in my any file
-it passes to set config which stores it
-my class exposes the stored property
-through a get name property
-and i can call that get name property in
-my template
-uh by referring to the this recommend
-object which is always going to be
-available in any recommendation module
-template
-pointing at the instance of the
-recommendation module class
-so now i come back here and i refresh
-the page
-combined search results has changed to
-the tutorial results
-and i've showed you both how to
-configure a recommendation module
-and how to use properties of the
-recommendation module to render a
-response
-let's do just one more clever thing
-and show a count of uh
-i'm sorry and so
-let's just do one more clever thing and
-show the user's
-search query uh along with the message
-we can do that
-by going to the process method
-which receives an instance of you finds
-search results object after the search
-has been completed
-well first let's create another property
-we'll call this
-query
-and then in the process we can say
-this query equals results
-get params
-get display query which is how you get
-access to the user's
-input in a human readable form
-from a search results object
-we also need to
-create a get query method
-to expose this property so that the
-view template can read it so we just
-create a get
-query that returns this query
-save all of that and now
-in our template here
-we can add four query colon
-single quote and then embed
-this escape html this
-recommend get query close friends
-and save that
-and let me actually do a search that has
-a query to make this more interesting
-and sure enough now it says you're
-looking at the tutorial results for
-query web
-so again my search query got processed
-the recommendation module pulled that
-out of the results object
-and we displayed it right here of course
-there's a lot more to learn there's a
-lot of depth to what viewfind is doing
-but the point here is that you can build
-small
-plug-ins like this which have access to
-other pieces if you find
-and you can pull things out and push
-them to the display
-so that you can do some fairly
-sophisticated customizations
-from within your local module with
-relatively little effort
-next time around i will go into some
-more code generators
-and show you how to do some other
-advanced customizations
-until then as always feel free to reach
-out with questions
-through the mailing lists or slack
-and have a good month
 ---- struct data ----
+properties.Page Owner :
 ----