Differences

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

--- videos:creating_themes [2020/02/03 19:21] – [Video 2: Indexing MARC Records] demiankatz
+++ videos:creating_themes [2020/06/09 16:25] – [Related Resources] demiankatz
@@ Line 8: / Line 8: @@
   - [[development:architecture:user_interface|User Interface Customization wiki page]]
+  - Example theme files used in the video: [[https://vufind.org/video/tutorial-theme.zip|tutorial-theme.zip]]
 ===== Transcript =====
-// coming soon! //
+Hello! I'm Chris Hallberg and today we're
+going to discuss how to make a new theme
+in VuFind! Now that we have set up VuFind
+in the previous videos it's time to
+make it look like your institution's
+theme and style it to be all your own.
+VuFind comes with a few different
+themes, the default theme that you're
+seeing here is called bootprint3. We'll
+get to why it's called that in just a
+second. VuFind comes with three themes
+that are designed to be a good
+jumping-off point for you to do your own
+customizations, so we're going to talk
+about how to switch those and make your
+own in this video.
+So I'm going to open
+up the back-end of VuFind. I have in
+VSCode here, this is the VuFind
+folder that we've been working on in the
+previous videos on the same virtual
+machine. I just thought a visual look at
+the folders might be an easier way to go
+about this. Right now I am currently
+in "local/config/vufind/config.ini".
+This file should exist, if not you'll
+want to make a copy out of
+"config/vufind/config.ini".
+This is the config
+file that contains all the basic
+configurations. One of the sections of
+this configuration, at the top, is called
+[Site] and this is where the overall
+configurations for where the site is,
+what email address gets the feedback and
+the support messages, the title, and one
+of the first things should be the theme.
+You can see right now bootprint3
+is the enabled theme.
+I'm going to switch
+over to bootstrap3 which is a
+more blank template for you to start
+your theme on. This is obviously built-in
+Bootstrap 3 and uses as many stylings
+of that framework as is reasonable and this
+is the blankest template that VuFind offers.
+Bootprint3 that we just switched
+from is takes some of the original
+stylings of legacy VuFind and adds
+them on top of bootstrap3 and,
+finally, the newest theme that we have is
+called sandal.
+We do have a boot and shoe pun
+going on this is a more modernly
+styled theme to match the trends of the
+last two years or so and there should be
+a brand new theme coming out later in
+to match the stylings and the
+accessibility and modern
+design practices of the current day.
+Another option that you have is
+you can specify a mobile theme.
+This isn't as common now that responsive
+design is a larger thing but if you want
+to serve a particular theme just to
+mobile users this is the way that you
+can configure that. I'm going to scroll
+down a little farther to two useful
+things for developers:
+"alternate_themes" and "selectable_themes".
+I'm going to uncomment these.
+"alternate_themes" allows you to specify
+like shortcut IDs for
+different themes so you can switch back
+and forth between them by using
+URL parameters. So I'm going to put on
+these two for now just to show how this
+works. Now if I go back and I do "?ui=bs3"
+it'll switch my theme over to bootstrap3
+and I can also switch to bootprint3.
+This is very useful.
+It can get even easier if you go a
+little further down to selectable themes
+you can actually give yourself a
+drop-down they'll make this even easier.
+So, now there's a theme drop-down in the
+top bar that allows you to do the same
+kind of switching. This is also useful if
+you want to present to your users with
+different UI is such as larger text or
+higher contrast or things like that.
+That's one way to enable that feature.
+I'm going switch to Bootstrap and we're
+going to look at how themes are
+structured inside of VuFind.
+If you go back to the roots of the
+VuFind instance and you go to themes
+you'll see a bunch of different folders
+of all the different themes that we have.
+I'm gonna open up bootstrap3. You'll see
+it's broken down into several different
+folders. These are mostly self-explanatory.
+One that is missing here is
+languages if you wanted to do a custom
+language file to add particular strings
+to just a certain theme you can do that.
+The most important file in this folder
+is the theme.config.php. This file
+tells VuFind what customizations you
+want and what files to include on every
+single page. There's a few other option
+more advanced options down here that
+we're not going to get to today such as
+using less or sass/scss pre-compilers.
+There's also a ways to specify view helpers.
+I'll talk about a few of those
+later and also the important thing to
+note here is this "extends" rule at
+the top. VuFind's themes inherits from
+each other. So "roots" is a theme that
+contains a lot of templates that are
+used in every single theme and if you
+look at bootprint3's theme config, it
+extends from bootstrap3. This allows you
+to build immediately on top of what we
+offer and on top of other parent themes
+to make it easier. If you look you can
+actually notice that bootprint3
+doesn't have any templates of
+its own. It's just images and CSS on top
+of all the work that bootstrap3 is
+doing. So that's kind of the approach
+that we're going to take today as we
+make our new theme (and as you'll likely
+take) is that you're only going to
+customize the parts that you need.
+You don't need to copy over the whole
+bootstrap3 theme to use it. You're just
+gonna want to pick the parts that you
+want to customize and use only those
+files.
+I think with that we're ready to
+get started with a new theme. I will point
+out there is a command prompt tool
+to do this but
+I'm going to keep it simple today and
+just make things manually so you can see
+how everything works but if you wanted
+to auto-generate a theme that's the correct
+structure and some other things in place
+there's a good way to do that as well.
+So in order to make a new theme it's very
+simple. I'm going to make a new folder
+inside of themes. I'm going to call it
+"tutorial" and I'm going to
+add a theme config file.
+I'm actually going to copy
+bootprint3's particular theme config
+because it matches what we're going to
+start with. Save that and we are actually
+ready to go so I can go up here and I
+can switch to "tutorial". I'm also going to
+add tutorial to our configurable
+switchable options here. We're going to
+take a look so I'm going to choose the
+theme directly. You'll see that it looks
+identical to bootstrap3 because we haven't
+customized anything yet but we are in
+fact in tutorial.
+So you can see that
+even though we haven't added any code we
+are already leveraging all of the
+accessibility and all of the structure
+and all the styling of the bootstrap3 theme.
+So let's go ahead and customize this.
+We need to do this in two steps.
+We need to make the actual folders we're going to
+put our customizations and we need to
+tell "theme.config.php" that they exist.
+So I'm going to make a "css" folder. We're going
+to make a new file in that folder.
+I'm gonna call it "custom.css".
+You can call it whatever you like.
+Then in "theme.config.php", I'm going
+to tell VuFind that we want
+to load this CSS file on every single page.
+I'm going to just add a
+little bit of color here so we can see
+that it works and if we go back you can
+see that if i refresh it things are now
+slightly different as I have customized
+things. Actually, I'm going to
+punch in a bunch of a bunch more code
+here that I will share later but not
+necessarily go over now. This is just for
+demonstration purposes. I did a couple
+different things to get us started on
+showing what a custom look can do.
+You see we can change the button colors
+we can change the fonts and everything
+like that all the things you can do with
+CSS are available to you.
+So now that
+I've customized the look of it,
+I actually want to go and change some of
+the actual templates. So, for example I
+might want to make this header full
+width. I might want to change the logo up
+here. You might want to customize your footer.
+These are very easy to do because
+you can take the inheritance qualities
+and you can build on top of them. So for
+my demonstration today I'm going to show
+you how to override and make your own
+slightly customized header. Now you have
+to be careful with this kind of thing
+because if you give something the same
+name as something in the parent theme,
+it's going to completely override it.
+For example in Bootstrap the main CSS
+file is called "compiled.css". If I had names
+this file to "compiled.css", it would have
+completely overridden all of the
+Bootstrap styles and we'd have been left
+with much more of a mess
+than we intended to. But we're going to
+use this to our advantage right now by
+making a templates folder and
+I'm going to copy the header from bootstrap3
+into our custom theme.
+Open this up... so now this
+file, our custom header, is completely
+overriding the bootstrap3 theme.
+I'm going to change this to "video tutorial"
+just as a very small little thing.
+I'm going to knock out to this
+container class, which I know will make it
+full-width, and there's something I needed
+to do down here but I can't quite
+remember right now so we'll come back to
+that later.
+Now, if I refresh the page the CSS be
+fixed and you can see that the
+logo has changed to what we customized,
+it is now full width, which looks nice,
+but it still has all the themes and all
+the bits in there, which is very nice.
+Gonna go to a different view to show
+that it's going from page to page.
+Excellent.
+So that is the absolute bare-bones
+basics that you would need to customize
+a theme. I'm gonna go over a few other
+things particularly some view helpers
+and some common techniques to make sure
+that you don't get caught with some
+common problems and that you're using
+tools that can make things easier.
+In particular, with images.
+For this example, I'm going to replace
+this text up here with an actual
+picture logo, which is
+basically something that almost everyone will
+customize if they want to.
+I'm also going to add
+add a background image here just that
+show how to add background images.
+Now these are gonna be handled in different
+ways because I'm gonna add the actual
+image to the template in this case (logo)
+and I'm gonna add the image
+to the CSS in this case (background).
+The first thing I have to do is
+make an "images" folder. You can put the
+images folder wherever you like. I know
+that I like to install my fonts
+inside the CSS folder for convenience.
+Just keep in mind that paths are going
+to be relative to the CSS.
+I'm gonna grab a few example
+files that I downloaded earlier.
+I'm going to starts with the CSS
+background. So, I already included the
+stylings here so, I'll just
+discuss them. The path is relative to
+the current CSS folder this is something
+to keep in mind if you go on to use the
+pre-processing things like less and scss/sass
+that it's gonna be relative
+to the outputted CSS. So we're just going
+up to the theme root and then down into
+"images" to get this particular image.
+And now that the image
+is in place inside of the folder, if i
+refresh we should get the background
+image here inside of our theme.
+In order to add
+images to the templates it might
+be trickier to figure out the actual
+path but we have added a view helper to
+make this easier. So I'm going to go here
+to our video tutorial logo.
+I'm going to make it image
+so "<img src="(which I get to in a second)
+and make this alt tag.
+So the view helper is called "imageLink"
+and this allows VuFind to find your
+image for you if you put it in the
+default spot here. So I just need to type
+out "<?=$this->imageLink(" and then
+the name of the image that I want, which
+is "vufind-logo.png"...
+This is a nice little helper that
+helps you find the image in the proper spot
+regardless of how nested your template
+folders get this is a very useful tool.
+Now if I refresh you'll
+see that I've replaced the image the
+logo with a sillier little image that I
+got from flamingtext.com. It just takes
+a little bit of CSS to make sure that
+doesn't overstep its bounds.
+There we go. Absolutely beautiful.
+Another common thing that you'll
+want to keep in mind if you're
+making your own actual pages is that
+VuFind has breadcrumbs up at the top.
+It is fairly easy to customize these
+breadcrumbs. I just wanted to point out
+how it looks and how it works. So let me
+open up a different folder of an existing
+template just to show you what that code
+looks like.
+In the theme that's very common to see
+"$this->layout()->breadcrumbs".
+"$this->layout() is almost a global object.
+You can write to it from any template
+and this will come in to come in handy
+when the page actually renders into layouts.
+So $this->layout()->breadcrumbs
+and then breadcrumbs is a
+string so you can dot append or concat
+onto it with anything you might want.
+So, in this case, this is where we're adding
+the actual search, with "lookfor" here so
+if you wanted to completely change the
+breadcrumbs or add some breadcrumbs on
+your custom pages, this is what you'd
+want to look for to do that. Very useful
+if you're making your own unique pages
+with their own unique routes. Just
+something I wanted to point out, just in
+case.
+Another thing that I've been saying
+a lot is that when you change things in
+"theme.config.php" it adds those files to
+every single page. This is true of CSS
+and Java scripts and all the different
+things that you would be adding to a
+page but there is a fairly easy way to
+add CSS to just one or two pages.
+So for example, in our header or if we have a
+custom search home page we might want to
+add to some vendor files or add some
+unique scripts so I just want to show
+how that looked so you are aware of what
+you'd be looking for if you wanted to do
+that. Scripts look like this. Both of
+these are helpers that come with
+Zend Framework and we've tweaked them a
+little bit to help make sure all the
+paths are correct.
+"$this->headScript()->appendFile()" adds a
+JavaScript file from the JS folder of
+your theme to the header list. This is
+useful if you want to add functionality
+to just one page, so for example the
+advanced search has a whole bunch of
+JavaScript so you can add and
+dynamically remove different fields and
+move them around. So this file is only
+included on the advanced search page and
+that's done with one of these tags at
+the top of the template. Similarly if you
+wanted to add specific CSS to just a
+page you can do it this way with
+"$this->headLink->appendStylesheet()".
+You can pull in vendor files, you can
+pull-in CSS that you just want on one
+particularly heavy page. This is a good
+technique so that way if you have
+particularly heavy JavaScript or CSS
+files or ones that are doing a lot of
+work they don't want to interfere with
+other pages, this is one way to do it
+in a way that will stay uniquely on
+one page. You'll see this most commonly
+on the search home if you want to add
+some carousels or things like that.
+You'll see this throughout the VuFind
+templates if you take a look.
+That more or less summarizes the absolute basics
+of making your own theme. There are some
+more advanced topics that we're going to
+cover in later videos. For example,
+mix-ins which are very useful for
+institutions that have multiple looks or
+multiple themes. For example a college
+that might have multiple libraries you
+might want to solve a different look for
+each one. mix-ins allow you to share files
+among different themes more easily.
+It's just another tool for customization.
+There's also built-in preprocessor
+abilities for less and scss/sass.
+I will cover that in another video.
+There's ways to do that to compile with PHP
+or if you have node installed,
+there is a grunt file that
+we can use to make tasks and
+load less and CSS files.
+And finally in
+order to use those tools it might be
+easiest to use the command lines
+generators so when I do those examples
+I'll show you how those work and how it
+gives you a pre-built structure for
+your themes.
+So I'm going to leave this
+up as the final screen so you can see
+the structure of our new theme. Thank you
+for watching this video! If you have any
+questions please feel free to check out
+the VuFind wiki and send us any
+emails on our mailing lists that you
+might have. We'd be more than happy to
+clarify and cover things in future
+videos. Thank you for watching and
+Happy Searching!
 ---- struct data ----
 ----