Hemingway Custom Templates Instruction Manual V0.91

You don't have the latest version of Adobe Flash Player.

Please update your flash player.

Please login or register to make a comment!

...Description...... more. less.

the publicly available Custom Templates (specialized templates created by third parties) from the top right of the "My Webs" page. Also, Authors with the CreateTemplate permission can upload custom templates to the Hemingway server and designate them for public or private access. If you don't have permission, contact a support person for access. What do they do? A custom template can be a very simple template, which only renders a single page with a single Item on it. Or it can be more elaborate with conditional statements and for loops which render entire websites, very much like the existing Hemingway templates act. They can have embedded graphics, logos, and text which is never changed, or have dynamic content changing using Hemingway's content management server. It is up to the author who creates the custom template to provide the design, and structure of the newly rendered websites. Custom Templates work with ItemWizard, ItemMover and all other Hemingway tools EXCEPT the color schemes cannot be modified (as the main templates can) and the Interface Map buttons don't display the mapping for the custom template. Of course, an existing custom template can be edited and then re-uploaded to provide color changes. When a custom template is uploaded, the author may choose to share the template with other users of the Hemingway server. In this case, a preview image can be provided as well as a sample web demonstrating the look and feel of the custom template. Who can build them? Any Hemingway Author with the correct permissions can build and upload Custom Templates. What you'll need is a rudimentary understanding of HTML and understanding simple programming constructs like "if" and "for loops" and "variables." Also, if you understand a bit about XML or XML, it helps. This feature is not intended for the beginner. 2 Hemingway Custom Template Manual How do they work? An Author goes to the Add Custom Template screen and uploads: 1) A main page HTML file; 2) A section page HTML file; and 3) a .zip file with the support images and CSS files to be used (ex. A copyright.jpg file may appear on every page). The Author also provides: 1) A template Name; 2) A Description; 3) A Preview JPG file*; 4) A sample Template URL*; 5) contact Email address; and chooses whether to make the template accessible to other Hemingway users. *optional Once submitted, the template becomes part of the My Custom Templates for the Author. To choose a template for a particular website, the Author will need to select the custom template name from the pop-up menu in the Style for Web settings. The Author may also choose from a variety of Custom Templates available from the Custom Template Library. Once chosen, the library template becomes available to the Author to use in rendering any website. Preparing the HTML files Website structure Hemingway's content management system matches specified data in it's database to specific areas of a template. It does this by replacing custom Hemingway script text (called 'tags') residing in the template, with the corresponding specified data from the database. Though it can be changed, the basic Hemingway website structure is: A single Home (Main) page acting as a Table of Contents for multiple Section pages. The contents of each of these is: [brackets denote the same contents in both Main page and Section page] Main page: [Company Logo or Web Name, Table of Contents, Last Modified Date, Contact Individual and Email Address,] Website Title, Website Description, Main Web Image Section page: [Company Logo or Web Name, Table of Contents, Last Modified Date, Contact Individual and Email Address,] Section Title, Section Description, Item Title(s), Item Description(s),Item Image(s), Item Link(s) You can omit parts of each page if you like. For instance, you may wish to have the Last Modified Date only appear on the Main page, but not on the Section pages. There is only one Main page. Section pages are rendered for each Section in the web. Each Section page contains all the Items for that Section. So, if you had a web with 5 Sections, you would typically have a total of 6 pages rendered -- One Main page and 5 Section pages. 3 Hemingway Custom Template Manual If you want a picture or text to appear on all Section pages, you can 'hard-code' it in the HTML. Just include it in the original Section.html template file and it will appear on all rendered Section pages. Simple Web Often it's valuable to start with a very simple example. In this case we will build a template, which renders a single page, with only Company Logo, Website Title and Website Description. The exact HTML for the above page is: <html> <head> <title> simple web </title> </head> <body> <img src= "Bluehills.jpg" border= "0" > Blue Hills Website Design <h6> Welcome to our One-Page website! It's actually just an example of how to create a Main.html file for uploading to Hemingway's custom template builder. </h6> </body> </html> Now, what we really want to do is replace the "Bluehills.jpg" with the Company Logo, replace "Blue Hills Website Design" with the Website Title and replace the text with Website Description. This way, the template will work with Hemingway and render correctly any Hemingway site, which has a Logo Image, Web Title and Web Description. 4 Hemingway Custom Template Manual HTML and XML In order for Hemingway to correctly parse (or figure out) the HTML you will upload, it needs to view it in a particular way. The format it wants to see is XML. The above HTML is not XML compliant. XML compliant HTML is called XHTML. For those interested, there's a quick tutorial on XHTML and XML at w3schools.com ( http://www.w3schools.com/ ). But for our purposes, here's a quick refresher on HTML to XML conversion. We're going to assume you know something of HTML. Tags Let's start with the concept of "tags". <html> is called an html tag. <img> is called an img tag. Valid XML tags must be lowercase . HTML is composed of lots of tags, which tell the browser how to display the text in between the tags. Most tags come in pairs. <html> and </html>, <body> and </body>. Paired tags should always be nested "correctly," as shown below: <html><body></body></html> This is valid HTML and valid XML. Sometimes it is easier to read if it is displayed as: <html> <body> < </html> /body> This is NOT valid HTML and XML: <html> <body> </html> </body> Notice the tags are not properly nested . Tag Pairs must always be nested . In HTML, there are also single tags sometimes referred to as 'empty' elements. An example of a single tag is . These can occur anyware outside a tag. So the following is valid HTML: <body> </body> But, this is not: <body ></body> Single HTML tags must be converted to work in XML . The conversion is simple. You just put a space and "/" before the last ">" in the single tag. So, becomes . Another single tag to watch out for is <img src="test.gif"> which should be converted to: <img src="test.gif" /> 5 Hemingway Custom Template Manual Attributes A tag can have attributes enclosed inside the tag. For instance, the single tag: <img src="test.gif" /> has a single attribute name called "src" and an attribute value called "test.gif". Attribute values must always be enclosed in quotes . Elements A paired tag group with text in between is called an 'element.' An example of an element is: <a href="http://www.ibm.com>Click HERE to link to IBM</a> which has the <a> tag with an "href" attribute with the value: "http://www.ibm.com" and element text with the value: "Click HERE to link to IBM." We will refer to elements, element text and element attributes later on. That's about if for the rules Hemingway cares about. So, if you convert your existing HTML using the above rules, you'll end up with XHTML (except for a couple declarations we're not interested in). So, first convert the HTML into XHTML, and then we'll add new elements, replace some element attributes and element text to build our final XML compatible upload template file. (Note, when we do this, the file will no longer be XHTML compatible, only XML compatible.) Building the HTML Main Page file Converting HTML to XHTML You can convert your HTML to XHTML using the rules above or use a free program called TidyGUI ( http://perso.wanadoo.fr/ablavier/TidyGUI/ ) to automatically convert existing HTML (using the above rules) to XHTML. Then we edit it to make valid XML. TidyGUI generates: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" > <html xmlns= "http://www.w3.org/1999/xhtml" > <head> <meta name= "generator" content= "HTML Tidy, see www.w3.org" /> <title> simple web </title> </head> <body> <img src= "Bluehills.jpg" border= "0" /> Blue Hills Website Design <h6> Welcome to our One-Page website! It's actually just an example of how to create a Main.html file for uploading to Hemingway's custom template builder. </h6> </body> 6 Hemingway Custom Template Manual </html> Converting XHTML to XML Next, we'll remove some stuff we're not going to need. Delete from the Top: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" > You can also change <html xmlns= "http://www.w3.org/1999/xhtml" > to be <html> And while you're at it, remove: <meta name= "generator" content= "HTML Tidy, see www.w3.org" /> Now we need to tell Hemingway to begin parsing this file. This is done putting at the top: <root type= "web" > The type="web" must stay the same as it tells Hemingway to insert certain functional render scripts. Also, only use type="web" on the main.htm page. If you use it on the section.htm page you will get an error. Then put: </root> at the very end -- after the </html> tag. So now our XML looks like this: <root type= "web" > <head> <title> simple web </title> </head> <body> <img src= "Bluehills.jpg" border= "0" /> Blue Hills Website Design <h6> Welcome to our One-Page website! It's actually just an example of how to create a Main.html file for uploading to Hemingway's custom template builder. </h6> </body> </html> </root> Now, this is a valid XML file that Hemingway can read and parse. In fact, this file can be uploaded as is to Hemingway custom templates, but of course it will always render the exact same "Blue Hills Website Design" Page. What we need to do, is change the XML so that it uses content in the Hemingway database to render the web. To do this, we need to insert some special commands (or 'tags') into the XML where we want the content to go. The first thing we want to replace is the "Bluehills.jpg" with the Logo Image from the Hemingway server. To do this, we replace the "Bluehills.jpg" with: $web.logoimage 7 Hemingway Custom Template Manual So, the 12th line would now read: <img src= "$web.logoimage" border= "0" /> Pretty easy, right? Next, we replace "Blue Hills Website Design" with <web property= "webTitle" /> so, the 14th line will now read: <web property= "webTitle" /> Now, this probably seems confusing. Why wouldn't we just use $web.webtitle? This is how the rule works. If you are replacing a value inside an tag attribute which uses quotes, then you'll need to use the $web.webtitle format, but if you're replacing valid element text then you'll need to use the tag format: <web property="webtitle" /> The reason for this is that $web.webtitle is actually a valid string for the element text. So we need a different form for attribute text. For more about attributes and elements you can check out W3Schools.com ( http://www.w3schools.com ). Let's finish. We'll replace the description text between the h6 tags with: <web property= "description" /> And we're done. The final main.htm file ready for upload should look like: <root type= "web" > <html> <head> <meta name= "generator" content= "Microsoft FrontPage 4.0" /> <title> simple web </title> </head> <body> <img src= "$web.logoimage" border= "0" /> <web property= "webtitle" /> <h6><web property= "description" /></h6> </body> </html> </root> 8 Hemingway Custom Template Manual Uploading the HTML files as a Custom Template Now we're ready to upload the file. Logon to Hemingway, enter the Custom Template area, and click on the button cUpload New Template." If you don't see it, then you don't have the correct permissions to upload templates. Check with your administrator. Below is a view of the Add Custom Template form. Enter a Name for the template. This is the name which will be represented in the Style menu for webs. Once submitted, the name cannot change. Enter a Description . This description will be seen by yourself in the My Custom Templates page. If you choose to share this template, this description will also be shown in the Template Library. Next upload an HTM or HTML file for the Home page . The one we just created works fine here. 9 Hemingway Custom Template Manual Since we haven't rendered any Section pages, we don't need to upload anything in the Section Page HTML file form field. We also haven't designated any support files (we get to those later!), so we can skip the Support Files form field. If we want we can upload a JPG image 3 which if needed will be automatically scaled to 89 pixels wide by 67 pixels high. If you're planning on sharing this template with other Hemingway users, it might be a good idea to build a website demonstrating how it looks and works. You can even archive the source code on the website so others can download and modify. If you do this, you can provide a link to your demo website in the Template Instructions URL form field. Provide your Email address so that others can contact you if they have questions using this template. Check the box at the bottom of the page if you wish to Share this template with the other Hemingway users on this server. Click Submit All . You will then be taken back to My Custom Templates and there you will see your newly created Template. Rendering Using the Custom Template Now, you can go back to the My Webs page, choose a web and press the Style button and you can select your new web template from the popup Style button. 10 Hemingway Custom Template Manual Building the HTML files (Main Page Extended) Let's continue with our custom template and this time we'll add Section pages. While the Home page is rendered only once, the Section page is rendered once for each section. And, typically it has multiple items on it as well. Before we render the Section page, we should create on the Home page a Table of Contents which links to all the section pages. Here's what it will look like: This assumes there are 3 sections titled: About Blue Hills, Image Gallery and Contact Blue Hills. Here's the XML which does this. <root type= "web" > <html> <head> <title> simple web </title> </head> <body> <img src= "$web.logoimage" border= "0" /> <web property= "webtitle" /> <h6><web property= "description" /> Table of Contents </h6> <img src= "arrow2_x.gif" border= "0" width= "11" height= "12" > Home <for set= "baseSection" > <a href= "$section.url" ><section property= "sectionTitle" /></a> 11 Hemingway Custom Template Manual </for> </body> </html> </root> The blue highlighted text shows an Arrow2_x.gif pointing to "Home." There's nothing fancy here, it's just plain HTML. But, now we have our first "support file." Because this template page depends on this file, we'll need to upload it with the template html pages. Before we upload it, we'll need to compress it and any other support files into a single ZIP file. The yellow highlighted text contains the magic "for" looping code. When Hemingway sees this code, it will render everything between the <for set="baseSection"> and </for> for each section of the web 3 replacing the $section.url with a valid link address and the <section property="sectionTitle" /> with the Section title. If you have 5 sections, it will render it 5 times 4each with a different Section title. (Notice the indentation and spacing is for readability and doesn't affect the finished HTML presentation.) So, this code will render a link for each section of the web. It does this by first referencing the URL to the section page ($section.url --Which is in the $ format because it is within attribute quotes) in a link tag. Then the actual Section Title word is <section property="sectionTitle" /> of course followed by a </a> which finishes the link tag. The is a carriage return so that the next section link starts on the line below. 12 Hemingway Custom Template Manual Building the HTML files (Section Page) Great, now we're ready to build the Section Page. Here's what we want it to look like. At the top is the Section Title with the Section Description underneath. Next, is the Table of Contents. We want the arrow to point to the current section with links to the other sections. This is followed by the items. The topmost item consists only of an image, with each item displayed next to the item text. This is a bit more complicated than the main page and introduces two new concepts: Variables and If statements. Unlike the Main page XML which renders only one page, the Section page XML will render a page for each Section in the web. Let's look at the XML, then we'll examine the different parts. <root type= "section" > <html> <head> <title> simple web </title> </head> <body> <section property= "sectionTitle" set= "thisSection" /> <h6> <section property= "sectionDescription" set= "thisSection" /> Table of Contents </h6> 13 Hemingway Custom Template Manual <a href= "default.htm" > Home </a> <variable name= "blueHillsSection" set= "thisSection" value= "$section.sectionTitle" />  <for set= "baseSection" > <if lhs= "blueHillsSection" cond= "=" rhs= "$section.sectionTitle" > <img src= "arrow2_x.gif" border= "0" width= "11" height= "12" > <section property= "sectionTitle" /> <else /> <a href= "$section.url" ><section property= "sectionTitle" /></a> </if> </for> <hr />  <for set= "baseItem" > <if lhs= " = "$item.showImage" cond= "=" rhs cstr(true)" > <img border= "0" src= "$item.itemimage" align= "left" /> </if> <item property= "ItemText" /> <hr /> </for> </body> </html> </root> Now we can look at the component parts of this XML file. <root type= "section" > The root tag this type has "section" as it's attribute. This tells Hemingway to create two lists (sets). The first list is a set of all the sections in the web. It is called "baseSection". The second list is the set for the current section 3 in other words the current page being rendered. It is called "thisSection". The root tag is mandatory. <section property= "sectionTitle" set= "thisSection" /> This prints out the Section Title at the top of the page. Note the 'set="thisSection" which will change depending on which section page is being rendered (the second set as described above). <section property= "sectionDescription" set= "thisSection" /> This prints out the Section Description for this section. Table of Contents  This is just a comment and will be ignored by Hemingway. <variable name= "blueHillsSection" set= "thisSection" value= "$section.sectionTitle" /> 14 Hemingway Custom Template Manual This declares a variable called "blueHillsSection" from the "thisSection" set and assigns it the value of the Section Title. We will use this next to help us build the Table of Contents. Any name can be assigned to a variable 3 we just decided to call ours "blueHillsSection". <for set= "baseSection" > <if lhs= "blueHillsSection" cond= "=" rhs= "$section.sectionTitle" > <img src= "arrow2_x.gif" border= "0" width= "11" height= "12" > <section property= "sectionTitle" /> <else /> <a href= "$section.url" ><section property= "sectionTitle" /></a> </if> </for> This is the Table of Contents loop. Similar to the <for> loop we used in the Main page Table of Contents. Of course, we could use the same <for> loop as the Main page, but we wouldn't be able to dynamically put the arrow2_x.gif next to the current Section page. Remember, the <for> loop will step through each section, one at a time, and write out the html. What we would like to do is check the <for> loop Section title first and see if it's the same as the Section title of the page we're building. If it is, then we'll need to put the arrow.gif in front of it, else we need to link it to the correct page. Logically, it looks like this: (the indentations are only for readability 3 the same is true for the XML. Indentation is not necessary) Remember the name of the page we're working on now&let's call it "BlueHillsPage" Repeat this for all the Sections in this web: (Start with the first and step through them one at a time) If the "BlueHillsPage" is equal to the SectionTitle (means we're on the same page) then Put an arrow and write SectionTitle text Else (it's not equal) Print the SectionTitle text and link it to the Section page. Go to the next Section. Remember, the SectionTitle keeps changing on each pass through the <for> loop, but the variable "BlueHillsPage" stays the same. Now that we understand what we're trying to do in plain English, let's convert it to XML that Hemingway can understand. <variable name= "blueHillsSection" set= "thisSection" value= "$section.sectionTitle" /> This is the same as: Remember the name of the page we're working on now&let's call it "BlueHillsPage" <for set= "baseSection" > This is the same as: Repeat this for all the Sections in this web: (Start with the first and step through them one at a time) <if lhs= "blueHillsSection" cond= "=" rhs= "$section.sectionTitle" > 15 Hemingway Custom Template Manual This is the same as: If the "BlueHillsPage" is equal to the SectionTitle (means we're on the same page) then Semantic note: "lhs" means left-hand side; "cond" means condition "=" means equals to 3 you could also use "<>" (less than greater than) for not equals to; "rhs" means right-hand side. Because it's XML, you can order them in any way you like. All of these mean exactly the same: <if lhs= "blueHillsSection" cond= "=" rhs= "$section.sectionTitle" > <if cond= "=" rhs= "$section.sectionTitle" lhs= "blueHillsSection" > <if rhs= "blueHillsSection" lhs= "$section.sectionTitle" cond= "=" > <img src= "arrow2_x.gif" border= "0" width= "11" height= "12" > <section property= "sectionTitle" /> This is the same as: Put an arrow and write SectionTitle text <else /> This is the same as: Else (it's not equal) <a href= "$section.url" ><section property= "sectionTitle" /></a> This is the same as: Print the SectionTitle text and link it to the Section page. </if> Semantic note: the <if> tag (like all plain XML tags) needs to end with an </if> tag. The same hold true for the <for> tag. </for> This is the same as: Go to the next Section. Render Items <for set= "baseItem" > <if lhs= " = "$item.showImage" cond= "=" rhs cstr(true)" > <img border= "0" src= "$item.itemimage" align= "left" /> </if> <item property= "ItemText" /> <hr /> </for> When each Section Page is rendered, a list for the Items called the "baseItem" set is created, and can therefore be referenced. A complete list of all the Web, Section and Item properties is included in the reference section. 16 Hemingway Custom Template Manual Here we have the Items display XML. Like the Table of Contents, each Item in the set will be rendered using the <for> loop. As you should know, some Items in the Hemingway database have associated images, while others do not. If we try and show an image that's not there, we'll see the following on the final rendered page. Well, we don't want that. So, we need to check to see if the checkbox "Show Image" has been selected for a particular item. If it has,(or it's true) then we can show the picture. In any case, we should show the Item description text. Logically, it looks like this: (the indentations are only for readability 3 the same is true for the XML. Indentation is not necessary) Repeat this for all the Items in this Section: (Start with the first and step through them one at a time) If the checkbox of the Item Picture is true then Put the Picture on the page Next, put the Item description on the page followed by a horizontal rule Go to the next Item. Now that we understand what we're trying to do in plain English, let's convert it to XML that Hemingway can understand. <for set= "baseItem" > This is the same as: Repeat this for all the Items in this Section: (Start with the first and step through them one at a time) <if lhs= " = "$item.showImage" cond= "=" rhs ="cstr(true)" > This is the same as: If the checkbox of the Item Picture is true then Semantic Note: This is the same <if> tag we saw in the Table of Contents. But now we're checking for a true or false value. This is because $item.showImage can only be true or false. "cstr(true)" and "cstr(false)" are what is know as constant variables and do not need to be assigned previously as we did earlier with "BlueHillsSection". <img border= "0" src= "$item.itemimage" align= "left" /> This is the same as: Put the Picture on the page </if> This 'closes' the <if> tag. Only statements between the <if> and </if> are executed. <item property= "ItemText" /> <hr /> This is the same as: Put the Item description on the page followed by a horizontal rule </for> 17 Hemingway Custom Template Manual Closes the <for> loop. Closing the Root </root> Needs to be at the end of the Section XML page. What's next? Well we can upload the new Section XML page and build a template and test it out. Don't forget to create a ZIP file with the arrow2_x.gif file with it! If you design a template with other graphics or Cascading Style Sheets (css) you should include them as well in your ZIP file. No .asp, .exe, .jsp, .com or other executable files can be included in your ZIP file. Advanced Concepts If you wish to make a 'complete' template, like the ones in Hemingway, you'll need to check for different dependencies and execute different XML based upon those dependencies. For instance, you may want to check for links and display different buttons depending upon the button type. Also, you'll need to check to see whether a link goes to a URL (and is opened in a new window) or goes to a file, or a big picture. All of this can be done using the <for><if> and <variable> tags. Check the Altuit website for examples. We'll be posting 'complete' templates there for you to study, change and create your own. Reference Section Web Properties Section Properties Item Properties First a bit about properties. The webTitle property of a web can be referenced both ways: <web property="webTitle" /> $web.webTitle Which way it is used depends upon where it is found in the XML. If it is to be an attribute (between quotes) then use the $web.webtitle form. Else, use the <web property="webtitle" /> form (note the space between the last quote and the />) If the property is a checkbox (see illustrations below) then it can only be "true" or "false". Use the <if> control to reference it. Else the property is text. Some Item properties, such as LinkType and LinkStyle have integer values and return either a 1,2,3 or 4. You can use <if> control structures to apply them appropriately. 18 Hemingway Custom Template Manual 19 others: WebHits number of hits since counter reset LastMod Last Date Web Modified WebID ID number of this web Web Properties AccessList Restricted Access LinkShareURL ShowLinkShare EmailList EmailOnChange AuthorEmail ShowAuthorEmail AuthorName ShowAuthorName SplashImage ShowSplash LogoImage ShowLogo Description ShowDescrip SubWebName SubWebURL IsSubWeb ShowTitle WebTitle ShowName WebName Hemingway Custom Template Manual 20 Section Pro erties Other Section Properties: url The filename of the section page. SectionURL ShowURL SectionDescription ShowSectionDescrip SectionTitle ShowSectionTitle If you wish to skip a particular Section or Item in a <for> loop, you can use these commands: <movenext set="baseSection" /> <movefirst set="baseSection" /> <movenext set="baseItem" /> <movefirst set="baseItem" /> Hemingway Custom Template Manual 21 LinkToNewWd LinkURL LinkText ItemFile LinkStyle: 1=More Info Button 2=Link Button 3=Picture is the Button 4=Use LinkText LinkType=3 LinkType=2 ItemImage ShowImage HtmlOn Item Pro erties LinkType=1 ShowLink ItemText ShowText ItemTitle ShowTitle

less