2012-04-21, 03:54 PM
I started working on this MyCode simply as a project to learn about regular expressions. Somewhere along the way it became about giving a little present to the folks on my forum.
This tutorial will show you how to create a new MyCode that allows the user to display scrolling marquees. I hope to write a second part to this tutorial to show you how to add a code button to the editor that displays a user interface for creating the marquee.
What I hoped to accomplish by breaking down this MyCode and the process for inserting a new code button in the editor with a popup window customized for the input of properties can help someone customize their forum or create their first MyCode.
Of course if you like the MyCode you are more than welcome to use it in your forum(s)
Getting started.
The first step is to create the MyCode. In this case I am basically just porting the HTML <marquee> tag to BB code.
HTML <marquee> tag properties: behavior, direction, width, height, scroll delay, scroll amount.
Ordering them in this way will allow the user to access the most important (or most-used) properties easier.
Breaking down the MyCode:
Title: Marquee
Description: Displays a scrolling marquee.
Regular Expression:
Regular expressions can be a bit tricky. Nearly all the examples I've found use (.*?) for user input, but that is only appropriate in some situations. With regular expressions you can demand that information be provided using strict patterns or you can be lenient and allow users use several different kinds of separators, get numerical input in a range and even skip values altogether.
The ? operator is very useful in making flexible expressions for receiving user input. Let's break down the regular expression:
This first part includes "\" the escape character. It is used to allow special characters to be used in regular expressions as string literals. Literals are characters that are expected to be received literally versus in the form of user input.
For example in a regular expression "marquee" would need to be matched character for character to be accepted, but (.*?) would have a special meaning and need to interpreted by the regex engine.
The [ (square bracket) has a special meaning so it must be escaped. Then we see the word 'marquee'. So at this point the expected user input has been both literal and required. If the tag does not begin with [marquee it will fail.
The = does not have a special meaning so it is taken literally, but the trailing ? is a special character that makes the previous character's presence optional. So the user could enter the = after [marquee or not.
Now to our first property. The round brackets () are used to group expressions. The strings "alternate", "scroll" and slide are to be taken literally, but the | symbols between them indicate a Boolean OR. So if the user enters [marquee= and then one of the mentioned behaviors then the regular expression will have succeeded so far.
Note: It is important that I mention that even in this short section of the regular expression we have presented many options. The expression uses the ? character to allow users to skip characters and even properties. For example the = is completely optional. So the user input would be received (and function properly) if the user had entered
and the marquee would display properly as a alternating marquee.
While this allows the user more freedom it can also make the syntax seem more complex; and it is worth mentioning that the resulting BB code has a tendency to be more sloppy-looking. In this case we will be making a UI that will produce a consistent BB code as output.
After (alternate|scroll|slide) we see the ? again. This makes this entire property optional. The logic behind the expression so far is as follows:
If the user would like to make a marquee with the default values in the behavior section (which would then default to scroll), but change the direction (or any other later properties) then the default name scroll can be completely skipped.
Again that leaves a lot of things open. If the user inputs
Then the results will be a marquee that uses all the default values except it will scroll to the right.
[,| ]?
You will see several of these bracketed expressions throughout the rest of the regular expression. I will explain them here and then they will be skipped for the duration of this post.
The brackets indicate a list of optional single characters to accept. This allows the user to separate the input with either a space or a comma. Between the width and height property I have included the charcter 'x' as it is commonly used for such properties. Again the question mark makes this entire expression optional, so if the user entered
then it would output correctly.
(\d\d\d?%?)?
The escape character \ is seen here again. Remember that it made a special character [ be taken literally before, but the letter "d" is not a special character. So in this case instead of escaping the character to be taken literally, it actually gives the ordinary character a special meaning.
The \d is used to input one single numerical character. We want to allow users to input any number between 10-999 so we have made two of the digits required, but one optional: (\d\d\d?)
I also included the % symbol as an optional literal. This makes the marquee behave correctly when users enter percentage values in the width property but not the height. \d\d\d?%?
Then we have another ? which makes this entire expression optional: (\d\d\d?%?)? This means if a user inputs
then the code will function properly, but
will fail in this section of the expression. This is the reason that this property is optional. If the user inputs a single digit, using it for the width would make the marquee unreadable and the content would overflow the box. In this way as you will see later, if a single digit is the only input, it will be passed to the scroll amount property. The default scroll amount is six so it is a viable value for that property.
(\d\d\d?)?
The height is a simpler numerical input quite similar to the width expression. Its range is 10-999 and it is optional.
(\d\d?\d?)?
The input for the scroll delay allows a wider range (0-999) because the default value of scroll delay is 85, but 0 is also a viable value.
Also note that allowing a single digit provides a bottom limit for the width property. Because all of the fields are optional, if the minimum value for the width property (two or three digits or 10-999) then the value is shuffled past the height field which rejects it. Then the scroll delay accepts the single digit as valid input and the MyCode doesn't break and everybody is happy.
(\d\d?)?
The scroll amount property's input expression accepts a range of 0-99. It is optional.
\](.*?)\[/marquee]
The escape character \ makes the closing square bracket ] be taken literally. Note that this is not optional. If the closing brackets are not used then the MyCode breaks.
Then we see the previously discussed (.*?) expression. Grouped in round brackets the dot . means any single character. The asterisk * following the dot means any number of the preceding character and the question mark ? makes the entire expression optional.
So for all intents and purposed (.*?) means 0 or more characters or anything or nothing. This is an appropriate way to gather anything between the marquee tags as user input.
Again the escape character \ escaping the opening square bracket; the "marquee" literal and the escaped closing square bracket. These are not optional.
Examining the replacement HTML:
Replacement:
You will no doubt notice the use of the dollar signs and numbers in the HTML. These represent the groups of expressions we specified in our regular expression. They work in order from left to right and if they are skipped by the user they retain their placeholder.
In closing.
I am not a MyBB expert. I have just wanted to pass on what I have learned while it is still fresh on my mind. If you see something that I could have done better, then by all means share it with me so that I might improve.
For more information on how the tag input is received:
How to use marquee tags for nerds(with a preamble)
To try out the marquee tag on a real forum, visit Rant Central.
This tutorial will show you how to create a new MyCode that allows the user to display scrolling marquees. I hope to write a second part to this tutorial to show you how to add a code button to the editor that displays a user interface for creating the marquee.
What I hoped to accomplish by breaking down this MyCode and the process for inserting a new code button in the editor with a popup window customized for the input of properties can help someone customize their forum or create their first MyCode.
Of course if you like the MyCode you are more than welcome to use it in your forum(s)
Getting started.
The first step is to create the MyCode. In this case I am basically just porting the HTML <marquee> tag to BB code.
HTML <marquee> tag properties: behavior, direction, width, height, scroll delay, scroll amount.
Ordering them in this way will allow the user to access the most important (or most-used) properties easier.
Breaking down the MyCode:
Title: Marquee
Description: Displays a scrolling marquee.
Regular Expression:
\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
Regular expressions can be a bit tricky. Nearly all the examples I've found use (.*?) for user input, but that is only appropriate in some situations. With regular expressions you can demand that information be provided using strict patterns or you can be lenient and allow users use several different kinds of separators, get numerical input in a range and even skip values altogether.
The ? operator is very useful in making flexible expressions for receiving user input. Let's break down the regular expression:
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
This first part includes "\" the escape character. It is used to allow special characters to be used in regular expressions as string literals. Literals are characters that are expected to be received literally versus in the form of user input.
For example in a regular expression "marquee" would need to be matched character for character to be accepted, but (.*?) would have a special meaning and need to interpreted by the regex engine.
The [ (square bracket) has a special meaning so it must be escaped. Then we see the word 'marquee'. So at this point the expected user input has been both literal and required. If the tag does not begin with [marquee it will fail.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
The = does not have a special meaning so it is taken literally, but the trailing ? is a special character that makes the previous character's presence optional. So the user could enter the = after [marquee or not.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
Now to our first property. The round brackets () are used to group expressions. The strings "alternate", "scroll" and slide are to be taken literally, but the | symbols between them indicate a Boolean OR. So if the user enters [marquee= and then one of the mentioned behaviors then the regular expression will have succeeded so far.
Note: It is important that I mention that even in this short section of the regular expression we have presented many options. The expression uses the ? character to allow users to skip characters and even properties. For example the = is completely optional. So the user input would be received (and function properly) if the user had entered
[marqueealternate]Hi[/marquee]and the marquee would display properly as a alternating marquee.
While this allows the user more freedom it can also make the syntax seem more complex; and it is worth mentioning that the resulting BB code has a tendency to be more sloppy-looking. In this case we will be making a UI that will produce a consistent BB code as output.
After (alternate|scroll|slide) we see the ? again. This makes this entire property optional. The logic behind the expression so far is as follows:
If the user would like to make a marquee with the default values in the behavior section (which would then default to scroll), but change the direction (or any other later properties) then the default name scroll can be completely skipped.
Again that leaves a lot of things open. If the user inputs
[marqueeright]Hi[/marquee]Then the results will be a marquee that uses all the default values except it will scroll to the right.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
[,| ]?
You will see several of these bracketed expressions throughout the rest of the regular expression. I will explain them here and then they will be skipped for the duration of this post.
The brackets indicate a list of optional single characters to accept. This allows the user to separate the input with either a space or a comma. Between the width and height property I have included the charcter 'x' as it is commonly used for such properties. Again the question mark makes this entire expression optional, so if the user entered
[marqueealternateright]Hi[/marquee]then it would output correctly.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
(\d\d\d?%?)?
The escape character \ is seen here again. Remember that it made a special character [ be taken literally before, but the letter "d" is not a special character. So in this case instead of escaping the character to be taken literally, it actually gives the ordinary character a special meaning.
The \d is used to input one single numerical character. We want to allow users to input any number between 10-999 so we have made two of the digits required, but one optional: (\d\d\d?)
I also included the % symbol as an optional literal. This makes the marquee behave correctly when users enter percentage values in the width property but not the height. \d\d\d?%?
Then we have another ? which makes this entire expression optional: (\d\d\d?%?)? This means if a user inputs
[marquee=10]Hi[/maruee]then the code will function properly, but
[marquee=1]Hi[/marquee]will fail in this section of the expression. This is the reason that this property is optional. If the user inputs a single digit, using it for the width would make the marquee unreadable and the content would overflow the box. In this way as you will see later, if a single digit is the only input, it will be passed to the scroll amount property. The default scroll amount is six so it is a viable value for that property.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
(\d\d\d?)?
The height is a simpler numerical input quite similar to the width expression. Its range is 10-999 and it is optional.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
(\d\d?\d?)?
The input for the scroll delay allows a wider range (0-999) because the default value of scroll delay is 85, but 0 is also a viable value.
Also note that allowing a single digit provides a bottom limit for the width property. Because all of the fields are optional, if the minimum value for the width property (two or three digits or 10-999) then the value is shuffled past the height field which rejects it. Then the scroll delay accepts the single digit as valid input and the MyCode doesn't break and everybody is happy.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
(\d\d?)?
The scroll amount property's input expression accepts a range of 0-99. It is optional.
Quote:\[marquee=?(alternate|scroll|slide)?[,| ]?(left|right|up|down)?[,| ]?(\d\d\d?%?)?[x|,| ]?(\d\d\d?)?[,| ]?(\d\d?\d?)?[,| ]?(\d\d?)?\](.*?)\[/marquee]
\](.*?)\[/marquee]
The escape character \ makes the closing square bracket ] be taken literally. Note that this is not optional. If the closing brackets are not used then the MyCode breaks.
Then we see the previously discussed (.*?) expression. Grouped in round brackets the dot . means any single character. The asterisk * following the dot means any number of the preceding character and the question mark ? makes the entire expression optional.
So for all intents and purposed (.*?) means 0 or more characters or anything or nothing. This is an appropriate way to gather anything between the marquee tags as user input.
Again the escape character \ escaping the opening square bracket; the "marquee" literal and the escaped closing square bracket. These are not optional.
Examining the replacement HTML:
Replacement:
<marquee style="border: solid;" behavior="$1" direction="$2" width="$3" height="$4" scrolldelay="$5" scrollamount="$6">$7</marquee>
You will no doubt notice the use of the dollar signs and numbers in the HTML. These represent the groups of expressions we specified in our regular expression. They work in order from left to right and if they are skipped by the user they retain their placeholder.
In closing.
I am not a MyBB expert. I have just wanted to pass on what I have learned while it is still fresh on my mind. If you see something that I could have done better, then by all means share it with me so that I might improve.
For more information on how the tag input is received:
How to use marquee tags for nerds(with a preamble)
To try out the marquee tag on a real forum, visit Rant Central.