Customization

So you would like to extend the functionality, or improve the looks of your OmniShell? Well, you are in the right section of the docs, my friend. In this section I will be going over how to make extensions, themes, and scripts for OmniShell.

How to make themes

So you would like to make a theme for Omnishell? Don't worry, this is very easy and this guide will walk you through how to make a theme, and get your OmniShell looking sexy in no time!

Now, before we begin, this guide will show you how to make and apply your theme using the theme tool that comes packaged with OmniShell, you can apply themes without the use of the tool but it is not recommended.

1. First enter the themes directory in your root OmniShell folder (the one that contains boot.py), and create a new directory called whatever the name of your theme will be
2. Now enter the directory you just created and make a new file called theme.py
3. Next open theme.py in your preferred editor, and create three new variables called info, logo, and prompt, so it looks like this:

info = """""" 

logo = """"""

prompt = """"""

4. Set the logo variable as your logo; this could be ASCII art, an ASCII banner, or any other string. It should look something like this:

info = """""" 

logo = """    _      _
   / \    | |    ___   __ _  ___
  / _ \   | |   / _ \ / _` |/ _ \
 / ___ \  | |__| (_) | (_| | (_) |
/_/   \_\ |_____\___/ \__, |\___/
                      |___/"""

prompt = """"""

5. Set the prompt variable to your prompt. It should look something like this:

info = """""" 

logo = """    _      _
   / \    | |    ___   __ _  ___
  / _ \   | |   / _ \ / _` |/ _ \
 / ___ \  | |__| (_) | (_| | (_) |
/_/   \_\ |_____\___/ \__, |\___/
                      |___/"""

prompt = """A
Prompt
can
be
multi
line> """

6. Nearly done! Set the info variable to any info you would like users to know about your theme, e.g. the name of the author and the inspiration for the theme. This will be printed when selecting a theme. Your file should now look like this:

info = """TEST THEME

This is a test theme to demonstrate how to create themes

By: D1j1t""" 

logo = """    _      _
   / \    | |    ___   __ _  ___
  / _ \   | |   / _ \ / _` |/ _ \
 / ___ \  | |__| (_) | (_| | (_) |
/_/   \_\ |_____\___/ \__, |\___/
                      |___/"""

prompt = """A
Prompt
can
be
multi
line> """

7. Add finishing touches. Remember that all these variables are printed with rich so you can do some fancy stuff. Here are some ideas:
   • You can use Unicode characters like this: u"\uCHARACTERCODE", e.g. for █ write u"\u2588"
   • You can use coloured, bold, italic, and blinking text like this
   • You can use variables in your prompt, logo, or info to make user customization easy, e.g.:

   animal = "cow"
   prompt = (animal + " = best animal> ")
   

   • You can use Python modules to put things like the time or battery percentage into the prompt, logo, or info, e.g.:

   from datetime import datetime
   now = datetime.now()
   prompt = ("the time is: " + now.strftime('%H:%M:%S') + " > ")
   

   • Here is a simple yet powerful trick to improve the look and usablity of the prompt: add \n as the first thing in the prompt variable to add spacing in between prompts, e.g. prompt = """\nAPrompt> """
8. Your theme is now complete. Apply it with themetool and gaze in awe at your new theme!

How to make extensions

If you want to extend the functionality or add features to OmniShell then you might want to use extensions. This section will explain how to make and apply extensions.

However before we start there is an issue: different extensions do different things, the solution is that this guide will only show you how to set up environments to make extensions in, and apply the extensions you have made.

1. First enter the scripts directory in the root of your OmniShell folder (the one that contains boot.py), and create a new directory called whatever you want the command to run your extension to be
2. Now in the directory that you've just created, create a file called WHATEVER_YOU_CALLED_THE_DIRECTORY.py
3. Next write your extension in the .py file you've just created
4. If you want the extension to run at startup of OmniShell, then put exec(open('</PATH/TO/PY/FILE>').read()) somewhere in your .omnirc.py file
5. Now go and make kick-ass extensions, and show the true power of OmniShell!