Jump to content

* * * * * 5 votes

Skins, languages, and basic upgrades to applications

Posted by Michael , 17 June 2011 · 2,126 views

application app development walkthrough
This blog entry will follow up on my last one, and will continue with the same application we started then. The goal of this entry is to show how to use skin templates and language bits in an application, and to again ensure that those get included with the file when redistributing it. And as an added bonus, since this is a continuation of the last application, we'll get to do a little bit of looking into the process of upgrading existing applications. If you've not done so already, it's probably best to start off by going through that first entry on applications so that you're not lost.

The way we last left our application, we had a public page that showed some text, and we had an Admin CP setting to control that text. The public side of the text, though, was just kind of stuck out there, and wasn't styled in any way. So what we're going to do with this entry is to pretty up that page a bit by putting it into a skin template.

To start, let's open up the /modules_public/main/view.php file from our application. As mentioned last time, it's the two lines near the bottom of our doExecute function that tell IP.Board what content to print on the page. The way we left things, we just had it printing off the text:

/* Send to screen */
        $this->registry->output->addContent( $this->settings['aboutUsText'] );
Instead of sending the $this->settings value to IP.Board as the content, let's change that to call a skin template instead. The format for doing that is as follows:

/* Send to screen */
        $this->registry->output->addContent( $this->registry->output->getTemplate('aboutus')->viewAboutUs() );
What that code is going to do is call a skin template called viewAboutUs, in a skin group called aboutus. We have not created either this skin group or template, so if you save this code now and check your page you'll get a big fat error.

I'd like to break out of the pure walkthough here to talk about skin templates a bit. A skin template is essentially a PHP function, residing in a class file. The class is the skin group, and the individual templates are the functions contained therein. Each skin template function does the exact same thing: processes whatever logic is saved in the template, and returns HTML code, which then is added to the page output. As they are PHP functions, they can take arguments you pass to them, and then use those in the function to help build the proper output. We could have passed in the $this->settings['aboutUsText'] text as an argument to the template we're about to create, and then used that as a variable in the template, but since we're just updating a common object that IP.Board will have access to inside the templates, there's no real need. If we don't have to pass around a variable manually (and use the overhead that requires), then the best practices says "don't do it".

Now that we have our PHP code updated to call our skin template, let's go create that template. Go to the Admin CP, to the Look & Feel tab, and then to the Manage Skin Sets & Templates page. Click on our IP.board skin, then click to Add a new Bit. For this template, here's how we'll set it up:

Attached Image

This is taken right from that skin template call we made above. Click Add, and then we can start putting in some code. Note that if we simply add {$this->settings['aboutUsText']} to this template at this point and save it, we'll be right back where we were before we started this walkthrough, but we don't have the error about the undefined function anymore.

Now, you can style this page however you'd like, but following the guidelines set forth by IPS for the classes and such they use in 3.2, I came up with the following basic skin template:

<h1 class="ipsType_pagetitle">
    {parse expression="IPSLib::getAppTitle('aboutus')"}
<p class="ipsType_pagedesc">
<br />
<div class="ipsBox">
    <div class="ipsBox_container ipsPad">
This is pretty basic stuff, but I should probably cover a little bit of this. The {parse expression} line I have near the top is calling a standard IP.Board function that simply pulls the application public title for this app, so that makes for a nice bit of header text. Where I have the "Stuff" part will eventually be replaced, that's just a placeholder. And the rest is simply the nicely bordered box IP.Board uses now. This is what the page currently looks like:

Attached Image

Now, personally I'm good with this look. It might use a bit more color to help the contrast a bit, but I'm not a skinner, so I'll leave that up to you to get looking the way you'd like. The one final thing I'd like to do with this template before we consider it done is to put in a language bit. Where we had "Stuff" before, let's swap that out with this:

Now save that as the final code for the template bit.

Next, we need to create that language bit we just called. In the Admin CP, go to the Manage Languages page and click on our English language. Click the Add String button at the top. For this string, we fill it out as follows:

Attached Image

Be sure to choose our About Us application from the top dropdown, put in the key we used for this language bit in the template, and whatever text you like. For the Pack Name setting, it must always follow a pattern similar to what you see there: it needs to start with either public or admin, then have an underscore, then some name for this particular word pack. Like other things we've already seen, it has to be one word, and try to keep it lowercase if possible (although that's not required, it's just done for consistency's sake). As we only have one language string in this product, we just chose something simple for our pack name. Click the Add this entry button.

If you check the page right now, you won't see that description showing up yet. We have to jump back to our /modules_public/main/view.php file and tell it to load the language pack. Right below the opening bracket of our doExecute function, add this code:

/* Language */
        $this->lang->loadLanguageFile( array( 'public_main' ), 'aboutus' );
When that is in a source file, it tells IP.Board that it can use the public_main word pack from the aboutus application, and can call language bits from that pack. Save that code, go refresh the public page of the application, and you should see that text showing up at the top now:

Attached Image

So we now have both a skin template being used, and a language bit. We have to do a bit of cleanup with the skin template to move it into the Master skin set now before we start getting stuff ready for exporting to the XML files.

Like I talked about in my first blog entry in this series, I do not use the Master Skins method IPS added for working when in the IN_DEV environment. I find it to be too clunky and difficult to work with. I like to simply code my templates in the Admin CP like normal, and move the completed templates to the Master skin manually. The way I do this is talked about at the bottom of this entry.

So following that method, fire up phpMyAdmin, browse the skin_templates table, and sort them by template_id descending. You'll see two entries at the top of the list for the viewAboutUs template. Delete the entry where template_set_id is equal to 0, and edit the other one. Set the template_set_id, template_removable, template_added_to, template_user_added & template_user_edited should to 0, and template_master_key to root, then save this template.

We can now start getting the XML stuff ready for this application. Start off by going to your application's home directory, to the /xml folder, and edit the versions.xml file. We'll want to update this to add a new version for what we've just done to it, so make the content of the file be this now:

<?xml version="1.0" encoding="UTF-8"?>
Save and close that file. Now go to the Admin CP, to the Manage Applications & Modules page. Click the Edit button beside our About Us application, and set the Application Version to 1.0.1, then save that. I like to keep my application's modules with the same version number as my application, but this is not strictly necessary. If you'd like to do this, click the far right button beside our About Us application, then click either the Public or Admin modules links there, edit each module in each, and set the Module Version there to 1.0.1 as well. Then, back on the Manage Applications & Modules page, you can click the buttons to Export the Modules XML and Applications XML files.

We have to do one small bit of hand-editing at this point. In your application's /xml directory, edit the information.xml file. There will be a section there called <templategroups/>. We need to edit that to indicate which template groups come with this app, so edit that to the following:

    	<template match="exact">skin_aboutus</template>
Save that file. This will let the next tool know which template group is part of this application.

Next, in the Admin CP, go to the Look & Feel tab -> Template Tools page. Use the Developer's Tools section at the bottom, and run the Export HTML Templates Into Application Directories tool. Finally, go to the Manage Languages page and click the Export button near the bottom of the page, where it says "Export language files to application directories". If you check the /xml folder for your application now, you should see 3 more XML files have just been created: aboutus_mobile_templates.xml, aboutus_root_templates.xml & public_aboutus_language_pack.xml. These are the skin templates and language bits we added in this version.

Before we package this update up, jump back to the Manage Applications & Modules page. The entry for this application should say that there is an Upgrade Available, so you can go ahead and run that. All it will do is essentially re-import the XML data we just exported, as well as updating the entry for this application to let IP.Board know that this application is now version 1.0.1.

We can now package this application up again for redistribution. Users will be able to either install this application fresh, or if they had version 1.0.0, they can upload this new version and upgrade. Again, I have attached our source code to this entry so you can see it to help you along.

I hope you enjoyed this, and found it helpful. Please let me know if there are any questions, or you have suggestions for things we can add to this application to show off other possibilities of the IP.Board applications system. :)

Attached File  Application Sample 1.0.1.zip (17.3KB)
downloads: 169

  • InvisionHQ, BomAle and SidV like this

:D. Amazing.

Perhaps a next blog entry is making custom ACP pages?

EDIT: I'm trying my hand at creating my own app and the public side only shows a blank screen. I can't figure out what's going on.
thanks dear
nice job.
Thank you Michael
Thanks a ton.
Hey Michael? IS it possible to make a front-end page that doesn't appear in the navigation? For example I'm hoping/thinking of an app that would need a front end page but only accessible via certain links so you wouldn't navigate per say straight the that page.
Sure, just use the Tab Permissions tab when setting up the application to hide the tab from everyone.

Sure, just use the Tab Permissions tab when setting up the application to hide the tab from everyone.

Oo thanks. Also (and I hate to be such a pest) is there any way you could walk through a front end form? Mostly I'm looking at how to a) create a form template bit, b) use $_REQUEST for the different pages within the front end form (like form submissions) and then c) how to handle form requests.
Mr Washington
Jun 26 2011 11:01 AM

:D. Amazing. Perhaps a next blog entry is making custom ACP pages? EDIT: I'm trying my hand at creating my own app and the public side only shows a blank screen. I can't figure out what's going on.

I too get this. Also i want the ACP pages. I would need that to get done if I where to make my own apps.
Thank you!

For those how cannot get rid of error even after template bit is created. Check if you in DEV_mode! If so, go to ACP->Look and Feel -> Template Tools and click on Run for Create Master PHP Templates Directory. You must do it after every change to the template.
    • Mikhail Kozlov likes this
Mikhail Kozlov
Nov 03 2011 01:11 AM

Thank you!For those how cannot get rid of error even after template bit is created. Check if you in DEV_mode! If so, go to ACP->Look and Feel -> Template Tools and click on Run for Create Master PHP Templates Directory. You must do it after every change to the template.

Also if you in DEV_mode don't forget copy aboutus_public_main.php to master folder.

Thank you

Recent Comments

0 user(s) viewing

0 members, 0 guests, 0 anonymous users

Latest Visitors

  • Photo
    Yesterday, 08:05 PM
  • Photo
    Yesterday, 02:12 PM
  • Photo
    do namson_512859
    19 Aug 2014 - 09:13
  • Photo
    18 Aug 2014 - 18:27
  • Photo
    18 Aug 2014 - 14:00