Creating a Custom Page on a Channel
in Hubzilla
In this tutorial, we will go over how create a custom web page (associated with a channel) in Hubzilla using the built-in Webpages app.
Overview of Steps
- Set the correct permissions for the channel.
- Add a layout.
- Create blocks for CSS (if desired).
- Create the page.
Note: Although these instructions seem long, some of this stuff you only need to do once.
Requirements
- Administrator access to Hubzilla (to give a channel the ability to post unfiltered code).
- Knowledge of HTML & CSS (or at least enough to copy and paste someone else's code and do basic editing).
Note: The channel where the web pages will be created does not need administrator access, but an administrator would need to set the correct permissions for the channel.
Step 1: Set Permissions
By default, members of your website (hub) can create web pages on their channel, but for security reasons, their code is filtered, which prevents them from using certain tags.
If you want the channel to be able to use all HTML and JavaScript tags, then you have to allow the channel to use code. You can still create web pages without enabling code for the channel, but you will be limited in what tags you can use.
To turn on code for a channel:
- Log in as an Administrator.
- Go to Admin > Channels
- Click on
>_next to the channel you wish to enable code.- This is a toggle switch. Its appearance will change when it is enabled.
Now that code is enabled, they can create pages with any HTML, CSS, JavaScript, or PHP code they want.
Warning: Only give this permission to users you trust.
Step 2: Add a Layout
Next you will need to create a layout in the Webpages app.
You have several layouts to choose from, but we recommend that you use the one called nonelayout to get started with. You can use other layouts, but if you do, you have to be careful of conflicting code, especially if you are using example code from elsewhere, or using an app that generates HTML for you.
If you are using standard HTML tags and/or standard Bootstrap 5 classes, there should be no conflicts with your theme, unless you add CSS overriding the Bootstrap or theme's CSS.
To create a layout, follow these steps:
- Go to the Webpages app in Hubzilla.
- It can be found in the Apps menu, or on the Manage Apps page.
- Click on Layouts.
- Click on the Create button.
- Give the layout a description and name.
- The name must be lowercase and have no spaces or special characters.
- Copy one of the examples below into the text area.
- Click on the Edit button to save your work.
You only have to create a layout once, since you can reuse the same layout on multiple web pages.
Example for a Full Page with No Hubzilla Navigation Bar
Use this if you want full control over the page.
Give this layout the name nonelayout (or something else you would remember), and paste the following code into the layout text area. (Remember the name you give this layout. You will need it in step 4.)
[template]none[/template]
[region=content]
$content[/region]If you use this layout, you would skip step 3 (Create a CSS block) and put the CSS in your page in step 4. You can still use blocks like [block=cssblock][/block] to manage and reuse pieces of code; you just have to be careful how you arrange them since the order matters.
Note: If you intend on having a custom HTML structure or need to put something in the <head> tags, it is recommended that you use the template called none because it gives you full control of the page. Be sure to include all of the HTML for the page, not just the content, if you choose the none template.
Example for Standard Three Column Layout with Nav Bar
This is the default Hubzilla layout (or the default layout for your theme). You can define additional widgets here and add your CSS blocks.
Choose this option if your web page has HTML and CSS that would not conflict with your theme. For example, tags like <h2> and <p> and <div class="alert alert-info"> would not conflict with the default theme. Since the default theme uses Bootstrap 5, you can include Bootstrap classes in your code and it will render in the style of the theme.
Your rendered HTML would appear in the content area of your theme's layout.
Use this code for the layout to use the default template in your theme:
[region=aside]
[widget=fullprofile][/widget][/region]
[region=content]
[block=cssblock][/block]
$content[/region]
[region=right_aside]
[widget=notifications][/widget]
[widget=newmember][/widget][/region]If your page does not have custom CSS, you can remove the line that says [block=cssblock][/block].
Note: If you are using a custom or third-party theme that is not based on redbasic, then you might need to put something else here. Most themes reuse at least some of the code from the redbasic theme, so this layout will probably work. If it does not work for your third-party theme, consult the theme's documentation or support forums for assistance.
Caution: If you use the default layout or any other layout, beware of conflicting code. You may have to remove conflicts manually. Using "Reveal Code" and "Developer Tools" in your web browser to see the generated HTML might help you track down issues.
Step 3: Create a CSS Block
To make it easier to manage the CSS for your webpages, and to reuse the same code, it is recommended that you create a block. A block can include any code, but we will be using it to store your custom CSS in this case.
If your HTML code does not need any custom CSS, then you can skip this step. You can also skip this step if you intend on including your CSS inline.
To create a block, follow these steps:
- Go to the Webpages app.
- Click on Blocks in the sidebar.
- Click on the Create button.
- Give it a title and block name.
- If you used the layout examples in the previous step, call your block
cssblock.
- If you used the layout examples in the previous step, call your block
- Paste your CSS into the text area.
- Make sure that your CSS is surrounded by
<style>and</style>tags.
- Make sure that your CSS is surrounded by
- Click on the Share button to save your work.
Tip: You can create more than one CSS block and you can name them whatever you want. Be sure to update the layouts you are using with the correct block names. Blocks can be used for any code you want to reuse. Simply include the block in the desired layout to reuse the code on multiple pages.
Step 4: Create the Page
Now we have gotten to the point where you can create your web page.
- If you selected the None template, then you would insert the code for the entire page, including the
<html>tags, and everything in the<head>and the<body>. - If you selected another template, then you would only put the HTML code that belongs in the body of the page.
To create the web page, follow these instructions:
- Go to the Webpages app.
- Click on Pages in the sidebar.
- Click on the Create button.
- Change the Page Content Type to "HTML".
- Change the Page Layout to the one you want.
- Select
nonelayout(or whatever you named the layout in step 2) if you want full control of the page. - Select the default layout or another layout if you want your HTML to appear as content in an existing theme.
- Select
- Give your page a title and page link name.
- For most templates, whatever you enter in the title field will become the title of the page.
- If you selected the layout called
nonelayout, you will also have to manually update the<title>tag in the HTML. - The page link will show up in the URL, so select an appropriate link name.
- Enter or paste the HTML for your page in the main text area.
- Click on the lock icon to change who can see it.
- Click on Share to save your changes.
This should take you back to the list of pages you created. If you want to see what it looks like, click on the hyperlink for that page.
Pro Tip: Since the default theme and most third-party themes support Bootstrap 5, you can use example code from the Bootstrap website to create interesting designs that do not conflict with your existing theme.
Debugging
The hardest part of creating web pages is the the debugging. Sometimes one small typo or missing bracket can mess up a whole page. Here are some common issues that you may encounter.
HTML & CSS Conflicts
If you are trying to combine code from somewhere else, and use it in Hubzilla, you will frequently encounter conflicts in the CSS. If there are conflicts, you can use your browser's developer tools to check the CSS and experiment by turning on and off individual instructions in the CSS. This can be a combersome process, but you will need to resolve these conflicts if you want code from different sources to play nicely together.
To avoid conflicts, you can use the none template in your layout, and only the code you paste will be shown. If it is your first time creating pages in Hubzilla, it is recommended that you use nonelayout as the layout to learn the process first.
500 Errors
If you are getting a 500 Error when viewing the web page, there is probably an issue with the block or layout. It contains invalid code somewhere. Check for typos and syntax.
You might also get a 500 Error if you selected PHP instead of HTML for the web page's content type. This is a result in invalid PHP code. If your code only contains HTML, then switch to the HTML content type. If your code contains PHP, check it for errors. You may want to edit your code in a IDE that automatically flags issues in the code.
Content for tab 2.
Content for tab 3.